@@ -1,7 +1,8 @@
11module Graphics.Input.Field where
2−{-| This library specifically addresses text fields. It uses the same general
3−approach as the [`Graphics.Input`](Graphics-Input) module for describing an
4−`Input`, so this library focuses on creating and styling text fields.
2+{-| This library provides an API for creating and updating text fields.
3+Text fields use exactly the same approach as [`Graphics.Input`](Graphics-Input)
4+for modelling user input, allowing you to keep track of new events and update
5+text fields programmatically.
56
67# Create Fields
78@docs field, password, email
@@ -20,21 +21,33 @@ import Graphics.Input (Input, Handle)
2021import Native.Graphics.Input
2122import Text
2223
23−{-| Easily create uniform dimensions:
24+{-| Create uniform dimensions:
2425
2526 uniformly 4 == { left=4, right=4, top=4, bottom=4 }
27+
28+The following example creates an outline where the left, right, top, and bottom
29+edges all have width 1:
30+
31+ Outline grey (uniformly 1) 4
2632-}
2733uniformly : Int -> Dimensions
2834uniformly n = Dimensions n n n n
2935
3036{-| For setting dimensions of a fields padding or border. The left, right, top,
31−and bottom may all have different sizes.
37+and bottom may all have different sizes. The following example creates
38+dimensions such that the left and right are twice as wide as the top and bottom:
39+
40+ myDimensions : Int -> Dimensions
41+ myDimensions n = { left = 2 * n, right = 2 * n, top = n, bottom = n }
3242-}
3343type Dimensions = { left:Int, right:Int, top:Int, bottom:Int }
3444
3545{-| A field can have a outline around it. This lets you set its color, width,
3646and radius. The radius allows you to round the corners of your field. Set the
37−width to zero to make it invisible.
47+width to zero to make it invisible. Here is an example outline that is grey
48+and thin with slightly rounded corners:
49+
50+ { color = grey, width = uniformly 1, radius = 4 }
3851-}
3952type Outline = { color:Color, width:Dimensions, radius:Int }
4053
@@ -42,8 +55,12 @@ type Outline = { color:Color, width:Dimensions, radius:Int }
4255noOutline : Outline
4356noOutline = Outline Color.grey (uniformly 0) 0
4457
45−{-| When a field is selected, it has an highlight around it by default. Set the
46−width of the `Highlight` to zero to make it go away.
58+{-| When a field has focus, it has a blue highlight around it by default. The
59+`Highlight` lets you set the `color` and `width` of this highlight. Set the
60+`width` to zero to turn the highlight off. Here is an example highlight that
61+is blue and thin:
62+
63+ { color = blue, width = 1 }
4764-}
4865type Highlight = { color:Color, width:Int }
4966
@@ -51,10 +68,18 @@ type Highlight = { color:Color, width:Int }
5168noHighlight : Highlight
5269noHighlight = Highlight Color.blue 0
5370
54−{-| Describes the style of a text box. The `style` field describes the style
55−of the text itself. The `outline` field describes the glowing blue outline that
56−shows up when the field has focus. Turn off `outline` by setting its width to
57−zero. The
71+{-| Describe the style of a text box. `style` describes the style of the text
72+itself using [`Text.Style`](/Text#Style). `outline` describes the glowing blue
73+outline that shows up when the field has focus. `outline` describes the line
74+surrounding the text field, and `padding` adds whitespace between the `outline`
75+and the text.
76+
77+The width and height of the text box *includes* the `padding` and `outline`.
78+Say we have a text box that is 40 pixels tall. It has a uniform outline of
79+1 pixel and a uniform padding of 5 pixels. Both of these must be subtracted
80+from the total height to determine how much room there is for text. The
81+`padding` and `outline` appear on the top and bottom, so there will be 28
82+vertical pixels remaining for the text (40 - 1 - 5 - 5 - 1).
5883-}
5984type Style =
6085 { padding : Dimensions
@@ -77,27 +102,32 @@ defaultStyle =
77102
78103{-| Represents the current content of a text field. For example:
79104
80− Content "She sells sea shells" (Selection 0 3 Backward)
105+ content = Content "She sells sea shells" (Selection 0 3 Backward)
81106
82−This means the user highlighted the substring `"She"` backwards.
107+This means the user highlighted the substring `"She"` backwards. The value of
108+`content.string` is `"She sells sea shells"`.
83109-}
84110type Content = { string:String, selection:Selection }
85111
86112{-| The selection within a text field. `start` is never greater than `end`:
87113
88− Selection 0 0 Forward -- cursor precedes all characters
114+ Selection 0 0 Forward -- cursor precedes all characters
89115
90− Selection 5 9 Backward -- highlighting characters starting after
91− -- the 5th and ending after the 9th
116+ Selection 5 9 Backward -- highlighting characters starting after
117+ -- the 5th and ending after the 9th
92118-}
93119type Selection = { start:Int, end:Int, direction:Direction }
94120
95−{-| The direction of selection.-}
121+{-| The direction of selection. When the user highlights a selection in a text
122+field, they must do it in a particular direction. This determines which end of
123+the selection moves when they change the selection by pressing Shift-Left or
124+Shift-Right.
125+-}
96126data Direction = Forward | Backward
97127
98128{-| A field with no content:
99129
100− Content "" (Selection 0 0 Forward)
130+ Content "" (Selection 0 0 Forward)
101131-}
102132noContent : Content
103133noContent = Content "" (Selection 0 0 Forward)