@@ -6,7 +6,16 @@ import Native.Graphics.Input as N
66
77id x = x
88
9−buttons : a -> { button : a -> String -> Element, events : Signal a }
9+-- Create a group of buttons.
10+--
11+-- * The first argument is the default value of the `events` signal.
12+-- * The `events` signal represents all of the activity in this group
13+-- of buttons.
14+-- * The `button` function creates a button
15+-- with the given name, like “Submit” or “Cancel”.
16+-- The `a` value is sent to `events` whenever the button is pressed.
17+buttons : a -> { events : Signal a,
18+ button : a -> String -> Element }
1019
1120-- Create a button with a given label. The result is an `Element` and
1221-- a signal of units. This signal triggers whenever the button is pressed.
@@ -15,8 +24,17 @@ button txt =
1524 let pool = N.buttons ()
1625 in (pool.button () txt, pool.events)
1726
18−customButtons : a -> { button : a -> Element -> Element -> Element -> Element,
19− events : Signal a }
27+-- Create a group of custom buttons.
28+--
29+-- * The first argument is the default value of the `events` signal.
30+-- * The `events` signal represents all of the activity in this group
31+-- of custom buttons.
32+-- * The `customButton` function creates a button with three different visual
33+-- states, one for up, hovering, and down. The resulting button has dimensions
34+-- large enough to fit all three possible `Elements`.
35+-- The `a` value is sent to `events` whenever the button is pressed.
36+customButtons : a -> { events : Signal a,
37+ customButton : a -> Element -> Element -> Element -> Element }
2038
2139-- Create a button with custom states for up, hovering, and down
2240-- (given in that order). The result is an `Element` and
@@ -26,41 +44,76 @@ customButton up hover down =
2644 let pool = N.customButtons ()
2745 in (pool.button () up hover down, pool.events)
2846
29−checkboxes : a -> { box : (Bool -> a) -> Bool -> Element, events : Signal a }
47+-- Create a group of checkboxes.
48+--
49+-- * The first argument is the default value of the `events` signal.
50+-- * The `events` signal represents all of the activity in this group
51+-- of checkboxes.
52+-- * The `checkbox` function creates a
53+-- checkbox with a given state. The `(Bool -> a)` function is used
54+-- when the checkbox is modified. It takes the new state and turns
55+-- it into a value that can be sent to `events`. For example, this
56+-- lets you add an ID to distinguish between checkboxes.
57+checkboxes : a -> { events : Signal a,
58+ checkbox : (Bool -> a) -> Bool -> Element }
3059
31−-- Create a checkbox with a given start state. Notice that the result is a *signal*
32−-- of elements. That is because a checkbox has state that updates based on user input.
60+-- Create a checkbox with a given start state. Unlike `button`, this result
61+-- is a *signal* of elements. That is because a checkbox has state that
62+-- updates based on user input.
3363-- The boolean signal represents the current state of the checkbox.
3464checkbox : Bool -> (Signal Element, Signal Bool)
3565checkbox b =
3666 let cbs = N.checkboxes b
3767 in (lift (cbs.box id) cbs.events, cbs.events)
3868
39−type FieldState = { string:String, start:Int, end:Int }
69+-- Represents the current state of a text field. The `string` represents the
70+-- characters filling the text field. The `selectionStart` and `selectionEnd`
71+-- values represent what the user has selected with their mouse or keyboard.
72+-- For example:
73+--
74+-- { string="She sells sea shells", selectionStart=3, selectionEnd=0 }
75+--
76+-- This means the user highlighted the substring `"She"` backwards.
77+type FieldState = { string:String, selectionStart:Int, selectionEnd:Int }
4078
41−fields : a -> { field : (FieldState -> a) -> String -> FieldState -> Element,
42− events : Signal a }
79+-- Create a group of text input fields.
80+--
81+-- * The first argument is the default value of the `events` signal.
82+-- * The `events` signal represents all of the activity in this group
83+-- of text fields.
84+-- * The `field` function creates a
85+-- field with the given ghost text and initial field state.
86+-- When the field is modified, the `(FieldState -> a)` function
87+-- takes the new state and turns
88+-- it into a value that can be sent to `events`. For example, this
89+-- lets you add an ID to distinguish between input fields.
90+fields : a -> { events : Signal a,
91+ field : (FieldState -> a) -> String -> FieldState -> Element }
4392
44−empty = { string="", start=0, end=0 }
93+-- The empty field state:
94+--
95+-- { string="", selectionStart=0, selectionEnd=0 }
96+emptyFieldState : FieldState
97+emptyFieldState = { string="", selectionStart=0, selectionEnd=0 }
4598
4699-- Create a field with the given default text. The output is an element that
47100-- updates to match the user input and a signal of strings representing the
48101-- content of the field.
49102field : String -> (Signal Element, Signal String)
50103field placeHolder =
51− let tfs = N.fields empty
104+ let tfs = N.fields emptyFieldState
52105 in (lift (tfs.field id placeHolder) tfs.events, lift .string tfs.events)
53106
54107-- Same as `field` but the UI element blocks out each characters.
55108password : String -> (Signal Element, Signal String)
56109password placeHolder =
57− let tfs = N.passwords empty
110+ let tfs = N.passwords emptyFieldState
58111 in (lift (tfs.field id placeHolder) tfs.events, lift .string tfs.events)
59112
60−-- Same as `field` but it adds an annotation that this field is for email addresses.
61−-- This is helpful for auto-complete and for mobile users who may get a custom keyboard
62−-- with an `@` and `.com` button.
113+-- Same as `field` but it adds an annotation that this field is for email
114+-- addresses. This is helpful for auto-complete and for mobile users who may
115+-- get a custom keyboard with an `@` and `.com` button.
63116email : String -> (Signal Element, Signal String)
64117email placeHolder =
65− let tfs = N.emails empty
118+ let tfs = N.emails emptyFieldState
66119 in (lift (tfs.field id placeHolder) tfs.events, lift .string tfs.events)