git.iko.soy/elk
on master help sign in
Try to improve documentation
ed0380eEvan Czaplicki
libraries/Graphics/Input/Field.elm+49−19
compare with master
unifiedsplit
@@ -1,7 +1,8 @@
1module Graphics.Input.Field where
1module Graphics.Input.Field where
2−{-| This library specifically addresses text fields. It uses the same general
2+{-| This library provides an API for creating and updating text fields.
3−approach as the [`Graphics.Input`](Graphics-Input) module for describing an
3+Text fields use exactly the same approach as [`Graphics.Input`](Graphics-Input)
4−`Input`, so this library focuses on creating and styling text fields.
4+for modelling user input, allowing you to keep track of new events and update
5+text fields programmatically.
5
6
6# Create Fields
7# Create Fields
7@docs field, password, email
8@docs field, password, email
@@ -20,21 +21,33 @@ import Graphics.Input (Input, Handle)
20import Native.Graphics.Input
21import Native.Graphics.Input
21import Text
22import Text
22
23
23−{-| Easily create uniform dimensions:
24+{-| Create uniform dimensions:
24
25
25 uniformly 4 == { left=4, right=4, top=4, bottom=4 }
26 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
26-}
32-}
27uniformly : Int -> Dimensions
33uniformly : Int -> Dimensions
28uniformly n = Dimensions n n n n
34uniformly n = Dimensions n n n n
29
35
30{-| For setting dimensions of a fields padding or border. The left, right, top,
36{-| 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 }
32-}
42-}
33type Dimensions = { left:Int, right:Int, top:Int, bottom:Int }
43type Dimensions = { left:Int, right:Int, top:Int, bottom:Int }
34
44
35{-| A field can have a outline around it. This lets you set its color, width,
45{-| A field can have a outline around it. This lets you set its color, width,
36and radius. The radius allows you to round the corners of your field. Set the
46and 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 }
38-}
51-}
39type Outline = { color:Color, width:Dimensions, radius:Int }
52type Outline = { color:Color, width:Dimensions, radius:Int }
40
53
@@ -42,8 +55,12 @@ type Outline = { color:Color, width:Dimensions, radius:Int }
42noOutline : Outline
55noOutline : Outline
43noOutline = Outline Color.grey (uniformly 0) 0
56noOutline = Outline Color.grey (uniformly 0) 0
44
57
45−{-| When a field is selected, it has an highlight around it by default. Set the
58+{-| When a field has focus, it has a blue highlight around it by default. The
46−width of the `Highlight` to zero to make it go away.
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 }
47-}
64-}
48type Highlight = { color:Color, width:Int }
65type Highlight = { color:Color, width:Int }
49
66
@@ -51,10 +68,18 @@ type Highlight = { color:Color, width:Int }
51noHighlight : Highlight
68noHighlight : Highlight
52noHighlight = Highlight Color.blue 0
69noHighlight = Highlight Color.blue 0
53
70
54−{-| Describes the style of a text box. The `style` field describes the style
71+{-| Describe the style of a text box. `style` describes the style of the text
55−of the text itself. The `outline` field describes the glowing blue outline that
72+itself using [`Text.Style`](/Text#Style). `outline` describes the glowing blue
56−shows up when the field has focus. Turn off `outline` by setting its width to
73+outline that shows up when the field has focus. `outline` describes the line
57−zero. The
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).
58-}
83-}
59type Style =
84type Style =
60 { padding : Dimensions
85 { padding : Dimensions
@@ -77,27 +102,32 @@ defaultStyle =
77
102
78{-| Represents the current content of a text field. For example:
103{-| Represents the current content of a text field. For example:
79
104
80− Content "She sells sea shells" (Selection 0 3 Backward)
105+ content = Content "She sells sea shells" (Selection 0 3 Backward)
81
106
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"`.
83-}
109-}
84type Content = { string:String, selection:Selection }
110type Content = { string:String, selection:Selection }
85
111
86{-| The selection within a text field. `start` is never greater than `end`:
112{-| The selection within a text field. `start` is never greater than `end`:
87
113
88− Selection 0 0 Forward -- cursor precedes all characters
114+ Selection 0 0 Forward -- cursor precedes all characters
89
115
90− Selection 5 9 Backward -- highlighting characters starting after
116+ Selection 5 9 Backward -- highlighting characters starting after
91− -- the 5th and ending after the 9th
117+ -- the 5th and ending after the 9th
92-}
118-}
93type Selection = { start:Int, end:Int, direction:Direction }
119type Selection = { start:Int, end:Int, direction:Direction }
94
120
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+-}
96data Direction = Forward | Backward
126data Direction = Forward | Backward
97
127
98{-| A field with no content:
128{-| A field with no content:
99
129
100− Content "" (Selection 0 0 Forward)
130+ Content "" (Selection 0 0 Forward)
101-}
131-}
102noContent : Content
132noContent : Content
103noContent = Content "" (Selection 0 0 Forward)
133noContent = Content "" (Selection 0 0 Forward)