Graphics.UI.Threepenny.Editors

Types and combinators to create widgets for editing algebraic datatypes.

This module builds around the idea that editors usually have the same shape as the data they are editing. We can immediately take advantage of this to automatically build editors from datatype definitions.

data Person = Person { first, last, email :: String, age :: Int }

deriveGeneric ''Person

instance Editable Person

This produces a generic editor with a fixed vertical layout. To customize the layout, we can use a explicit instance and monoidal layout builders:

instance Editable Person where
  editor = Person <$> fieldLayout Next  "First:" first editor
                  <*> fieldLayout Break "Last:"  last  editor
                  <*> fieldLayout Next  "Email:" email editor
                  <*> fieldLayout Next  "Age:"   age   editor

We can take this a step further by repurposing datatype definitions to represent not only data, but also the collections of editors that are composed to build the datatype editor. This is done via the Purpose type and the Field type family.

data Person purpose =
  Person { first, last, email :: Field purpose String
         , age                :: Field purpose Int}

deriveGeneric ''Person

instance Editable (Person Data) where
  type EditorWidget (Person Data) = Person Edit
  editor = editorGenericBi

instance Renderable (Person Edit) where
  render = renderGeneric

renderGeneric will produce a vertical layout. A direct implementation would use standard threepenny layout combinators since the fields of Person Edit are instances of Widget:

instance Renderable (Person Edit) where
  render Person{..} =
    grid [[string "First:", element first, string "Email:", element email]
         ,[string "Last:",  element last, string "Age:", element age]
         ]

Editors

newtype Editor outer widget inner

An editor for values of type inner inside a datatype outer realized by a widget.

All the three type arguments are functorial, but outer is contravariant, so Editor is a Biapplicative functor and a Profunctor (via dimapE).

Biapplicative allows to compose editors on both their widget and inner structure. When widget is monoidal, widget composition is implicit and Applicative suffices.

Profunctor allows to apply an inner editor to an outer datatype.

Once created, an Editor yields a tuple of an widget and a Tidings inner which can be integrated in a threepenny app.

Constructors

Editor

Fields

• create :: Behavior outer -> UI (GenericWidget widget inner)

Instances

Bifunctor (Editor a)

Methods

bimap :: (a -> b) -> (c -> d) -> Editor a a c -> Editor a b d

first :: (a -> b) -> Editor a a c -> Editor a b c

second :: (b -> c) -> Editor a a b -> Editor a a c

Biapplicative (Editor a)

Methods

bipure :: a -> b -> Editor a a b

(<<*>>) :: Editor a (a -> b) (c -> d) -> Editor a a c -> Editor a b d

(*>>) :: Editor a a b -> Editor a c d -> Editor a c d

(<<*) :: Editor a a b -> Editor a c d -> Editor a a b

Functor (Editor a el)

Methods

fmap :: (a -> b) -> Editor a el a -> Editor a el b

(<$) :: a -> Editor a el b -> Editor a el a

Monoid el => Applicative (Editor a el)

Methods

pure :: a -> Editor a el a

(<*>) :: Editor a el (a -> b) -> Editor a el a -> Editor a el b

(*>) :: Editor a el a -> Editor a el b -> Editor a el b

(<*) :: Editor a el a -> Editor a el b -> Editor a el a

class Renderable (EditorWidget a) => Editable a where

The class of Editable datatypes.

There are several ways to create an instance, from easiest to most advanced:

• Automatically (via SOP), producing an editor with a vertical layout:

instance Editable MyDatatype

• Using the applicative layout combinators:

 instance Editable MyDatatype where
   editor = MyDatatype <$> field "Name:" name editor
                       -*- field "Age:"  age  editor

• Using a monoidal layout builder:

 instance Editable MyDatatype where
   editor = MyDatatype <$> fieldLayout Break "Name:" name editor
                       <*> fieldLayout Next  "Age:"  age  editor

• Using a dual purpose datatype, leaving the layout details for the Renderable instance.

instance Editable (MyDatatype Data) where
  type EditorWidget (MyDatatype Data) = MyDatatype Edit
  editor = editorGenericBi

Associated Types

type EditorWidget a

The widget type that realizes the editor. Defaults to Layout and only needs to be manually defined when using custom renderables.

Methods

editor :: Editor a (EditorWidget a) a

editor :: (Generic a, HasDatatypeInfo a, All (All Editable `And` All NonEmpty) (Code a), EditorWidget a ~ Layout) => Editor a (EditorWidget a) a

Instances

Editable Bool

Associated Types

type EditorWidget Bool :: *

Methods

editor :: Editor Bool (EditorWidget Bool) Bool

Editable Double

Associated Types

type EditorWidget Double :: *

Methods

editor :: Editor Double (EditorWidget Double) Double

Editable Int

Associated Types

type EditorWidget Int :: *

Methods

editor :: Editor Int (EditorWidget Int) Int

Editable ()

Associated Types

type EditorWidget () :: *

Methods

editor :: Editor () (EditorWidget ()) ()

(~) * a Char => Editable [a]

Associated Types

type EditorWidget [a] :: *

Methods

editor :: Editor [a] (EditorWidget [a]) [a]

Editable (Maybe Double)

Associated Types

type EditorWidget (Maybe Double) :: *

Methods

editor :: Editor (Maybe Double) (EditorWidget (Maybe Double)) (Maybe Double)

Editable (Maybe Int)

Associated Types

type EditorWidget (Maybe Int) :: *

Methods

editor :: Editor (Maybe Int) (EditorWidget (Maybe Int)) (Maybe Int)

Editable a => Editable (Identity a)

Associated Types

type EditorWidget (Identity a) :: *

Methods

editor :: Editor (Identity a) (EditorWidget (Identity a)) (Identity a)

(Editable a, Editable b) => Editable ((-*-) a b)

Associated Types

type EditorWidget ((-*-) a b) :: *

Methods

editor :: Editor (a -*- b) (EditorWidget (a -*- b)) (a -*- b)

(Editable a, Editable b) => Editable ((|*|) a b)

Associated Types

type EditorWidget ((|*|) a b) :: *

Methods

editor :: Editor (a |*| b) (EditorWidget (a |*| b)) (a |*| b)

All * Editable xs => Editable (NP * I xs)

Associated Types

type EditorWidget (NP * I xs) :: *

Methods

editor :: Editor (NP * I xs) (EditorWidget (NP * I xs)) (NP * I xs)

dimapE :: (a' -> a) -> (b -> b') -> Editor a el b -> Editor a' el b'

Editor composition

(|*|) :: Editor s Layout (b -> a) -> Editor s Layout b -> Editor s Layout a infixl 4

Left-right editor composition

(|*) :: Editor s Layout a -> UI Element -> Editor s Layout a infixl 5

Left-right composition of an element with a editor

(*|) :: UI Element -> Editor s Layout a -> Editor s Layout a infixl 5

Left-right composition of an element with a editor

(-*-) :: Editor s Layout (b -> a) -> Editor s Layout b -> Editor s Layout a infixl 4

Left-right editor composition

(-*) :: Editor s Layout a -> UI Element -> Editor s Layout a infixl 5

Left-right composition of an element with a editor

(*-) :: UI Element -> Editor s Layout a -> Editor s Layout a infixl 5

Left-right composition of an element with a editor

field :: Renderable m => String -> (out -> inn) -> Editor inn m a -> Editor out Layout a

A helper that arranges a label and an editor horizontally.

fieldLayout :: (Renderable m, Renderable m') => (Layout -> m') -> String -> (out -> inn) -> Editor inn m a -> Editor out m' a

A helper that arranges a label and an editor horizontally, wrapped in the given monoidal layout builder.

withSomeWidget :: Renderable w => Editor a w b -> Editor a Layout b

Conceal the widget type of some Editor

Editor constructors

editorUnit :: Editor b Element b

editorIdentity :: Editor a el a -> Editor (Identity a) el (Identity a)

editorReadShow :: (Read a, Show a) => Editor (Maybe a) TextEntry (Maybe a)

editorEnumBounded :: (Bounded a, Enum a, Ord a, Show a) => Behavior (a -> UI Element) -> Editor (Maybe a) (ListBox a) (Maybe a)

editorSelection :: Ord a => Behavior [a] -> Behavior (a -> UI Element) -> Editor (Maybe a) (ListBox a) (Maybe a)

An editor that presents a dynamic choice of values.

editorSum :: (Ord tag, Show tag, Renderable el) => (Layout -> Layout -> Layout) -> [(tag, Editor a el a)] -> (a -> tag) -> Editor a Layout a

An editor for union types, built from editors for its constructors.

editorJust :: Editor (Maybe b) el (Maybe b) -> Editor b el b

Ignores Nothing values and only updates for Just values

someEditor :: Editable a => Editor a Layout a

A version of editor with a concealed widget type.

withSomeWidget :: Renderable w => Editor a w b -> Editor a Layout b

Conceal the widget type of some Editor

Dual purpose datatypes

type family Field (purpose :: Purpose) a where ...

Type level fields. Used to define dual purpose datatypes, example:

data PersonF (purpose :: Purpose) = Person
  { education           :: Field purpose Education
  , firstName, lastName :: Field purpose String
  , age                 :: Field purpose (Maybe Int)

type Person = PersonF Data
type PersonEditor = PersonF Edit

Equations

Field Data a = a

Field Edit a = EditorWidget a

data Purpose

Purpose is a kind for type level Fields

Constructors

Data

Edit

Generic editors

editorGeneric :: forall a. (Generic a, HasDatatypeInfo a, All (All Editable `And` All NonEmpty) (Code a)) => Editor a Layout a

A generic editor derivation for SOP types.

The datatype arguments are layered in vertical fashion and labelled with field names if available.

editorGenericBi :: forall xs typ. (Generic (typ Data), Generic (typ Edit), All Editable xs, Code (typ Data) ~ '[xs], Code (typ Edit) ~ '[EditorWidgetsFor xs]) => Editor (typ Data) (typ Edit) (typ Data)

A generic editor derivation for dual purpose datatypes with a single constructor.

e.g. for the datatype

 data Person purpose = Person { firstName, lastName :: Field purpose String }

 instance Editable (Person Data) where
     type EditorWidget (Person Data) = Person Edit
     editor = editorGenericBi

will be equivalent to

instance Editable (Person Data) where
 type EditorWidget (Person Data) = Person Edit
 editor = bipure DataItem DataItem
             <<*>> edit firstName editor
             <<*>> edit lastName editor

Widgets

data GenericWidget control a

Constructors

GenericWidget

Fields

• widgetTidings :: Tidings a

  The dynamic contents of the widget.

• widgetControl :: control

  The actual widget.

Instances

Bifunctor GenericWidget

Methods

bimap :: (a -> b) -> (c -> d) -> GenericWidget a c -> GenericWidget b d

first :: (a -> b) -> GenericWidget a c -> GenericWidget b c

second :: (b -> c) -> GenericWidget a b -> GenericWidget a c

Functor (GenericWidget control)

Methods

fmap :: (a -> b) -> GenericWidget control a -> GenericWidget control b

(<$) :: a -> GenericWidget control b -> GenericWidget control a

Widget el => Widget (GenericWidget el a)

Methods

getElement :: GenericWidget el a -> Element

Renderable el => Renderable (GenericWidget el a)

Methods

render :: GenericWidget el a -> UI Element

getLayout :: GenericWidget el a -> Layout

edited :: GenericWidget el a -> Event a

contents :: GenericWidget el a -> Behavior a

Layouts

data Layout

Instances

Renderable Layout

Methods

render :: Layout -> UI Element

getLayout :: Layout -> Layout

Monoidal layouts

newtype Vertical

A monoidal layout builder that places everything in a single column

Constructors

Vertical

Fields

• getVertical :: Layout

Instances

Monoid Vertical

Methods

mempty :: Vertical

mappend :: Vertical -> Vertical -> Vertical

mconcat :: [Vertical] -> Vertical

Renderable Vertical

Methods

render :: Vertical -> UI Element

getLayout :: Vertical -> Layout

newtype Horizontal

A monoidal layout builder that places everything in a single row

Constructors

Horizontal

Fields

• getHorizontal :: Layout

Instances

Monoid Horizontal

Methods

mempty :: Horizontal

mappend :: Horizontal -> Horizontal -> Horizontal

mconcat :: [Horizontal] -> Horizontal

Renderable Horizontal

Methods

render :: Horizontal -> UI Element

getLayout :: Horizontal -> Layout

data Columns

A monoidal layout builder that lays elements in columns

Constructors

Next Layout

Continue in the same column

Break Layout

Continue in the next column

Instances

Show Columns

Methods

showsPrec :: Int -> Columns -> ShowS

show :: Columns -> String

showList :: [Columns] -> ShowS

Monoid Columns

Methods

mempty :: Columns

mappend :: Columns -> Columns -> Columns

mconcat :: [Columns] -> Columns

Renderable Columns

Methods

render :: Columns -> UI Element

getLayout :: Columns -> Layout

Custom layout definition

class Renderable w where

Closely related to Widget, this class represents types that can be rendered to an Element, either directly or via Layout.

Minimal complete definition

render | getLayout

Methods

render :: w -> UI Element

getLayout :: w -> Layout

Instances

Renderable String

Methods

render :: String -> UI Element

getLayout :: String -> Layout

Renderable TextEntry

Methods

render :: TextEntry -> UI Element

getLayout :: TextEntry -> Layout

Renderable Element

Methods

render :: Element -> UI Element

getLayout :: Element -> Layout

Renderable Columns

Methods

render :: Columns -> UI Element

getLayout :: Columns -> Layout

Renderable Horizontal

Methods

render :: Horizontal -> UI Element

getLayout :: Horizontal -> Layout

Renderable Vertical

Methods

render :: Vertical -> UI Element

getLayout :: Vertical -> Layout

Renderable Layout

Methods

render :: Layout -> UI Element

getLayout :: Layout -> Layout

Renderable (ListBox a)

Methods

render :: ListBox a -> UI Element

getLayout :: ListBox a -> Layout

Renderable a => Renderable (UI a)

Methods

render :: UI a -> UI Element

getLayout :: UI a -> Layout

(Renderable a, Renderable b) => Renderable ((-*-) a b)

Methods

render :: (a -*- b) -> UI Element

getLayout :: (a -*- b) -> Layout

(Renderable a, Renderable b) => Renderable ((|*|) a b)

Methods

render :: (a |*| b) -> UI Element

getLayout :: (a |*| b) -> Layout

Renderable el => Renderable (GenericWidget el a)

Methods

render :: GenericWidget el a -> UI Element

getLayout :: GenericWidget el a -> Layout

renderGeneric :: forall a xs. (Generic a, HasDatatypeInfo a, All Renderable xs, Code a ~ '[xs]) => a -> UI Element

A generic render derivation for data types with a single constructor which renders the (labelled) fields in a vertical layout. For custom layouts use getLayoutGeneric.

e.g. given the declarations

data PersonEditor = PersonEditor { firstName, lastName :: EditorWidget String }
deriveGeneric ''PersonEditor

using renderGeneric to instantiate Renderable

instance Renderable PersonEditor where
  getLayout = renderGeneric

will be equivalent to writing the below by hand

instance Renderable PersonEditor where
  getLayout PersonEditor{..} =
      grid [ [string "First name:", element firstName]
           , [string "Last name:",  element lastName ]
           ]

getLayoutGeneric :: forall a xs. (Generic a, HasDatatypeInfo a, All Renderable xs, Code a ~ '[xs]) => a -> [[Layout]]

A helper to implement getLayout for data types with a single constructor. Given a value, getLayoutGeneric returns a grid of Layouts with one row per field. Rows can carry one element, for unnamed fields; two elements, for named fields; or three elements, for operators.