Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 226 lines (158 sloc) 10.488 kB
ceb6a35 snapshot save
megaannum authored
1 # Forms Tutorial
2
3 This is a tutorial covering the use of the VimL Forms library.
4
5 ## Self
6
7 The Forms library is built upon the VimL Self library, a object prototype
8 system. To understand the Self library see the
9 [Self Tutorial](https://github.com/megaannum/self/blob/master/tutorial/self/Tutorial.md).
10
11 ## Glyph Overview
12
13 The Glyph is the base Object for all Forms components.
14
15 Glyphs can be abstract or concrete.
16
17 Glyphs can be of kind: Leaf - no children, Mono - single child, Poly - list of children or Grid - list of lists of children.
18
19 A Glyph can be be interactive (have focus) or non-interactive.
20 An interactive Glyph
21 response to keyboard and/or mouse events while a non-interactive Glyph
22 does not. Well, thats mostly true. All Glyph's respond to a right mouse click,
0124e71 sixth tutorial snapshot save
megaannum authored
23 &ltRightMouse>, and displays context sensitive information in a popup.
ceb6a35 snapshot save
megaannum authored
24
25 For more detail see [Glyph Overview](https://github.com/megaannum/forms/blob/master/tutorial/forms/GlyphOverview.md)
26
27 ## Code Structure
28
29 The code that generates a Form, generally, has the same structure.
30 The code is in a function which may or may not take arguments which
31 are used to tailor the Form. The code creates the components that
32 will make up the Form, This is followed by the Form creation and
33 call for the Form to run. When a Form stops running it will
34 generate a return value. The default return value is 0 meaning that
35 the Form wants nothing to be done. Alternatively, a Form can return
36 a Dictionary of results; as keys Glyph tags and the associated values is
37 determined by each Glyph. Lastly, the code in the function can do
38 something based upon the Form's returned results.
39
40 For more detail see [Code Structure](https://github.com/megaannum/forms/blob/master/tutorial/forms/CodeStructure.md)
41
42 ## Label
43
44 A Label is a Leaf Glyph which takes a "text" attribute. Its size is one
45 character in height with a width equal to the number of its charaters.
46 It is a non-interactive Glyph.
47
48 For more detail see [Label](https://github.com/megaannum/forms/blob/master/tutorial/forms/Label.md)
49
50 ## Layout Labels Horizontally
51
52 A HPoly is a kind of Poly and is used to layout its child Glyphs horizontally.
53 In this case, all of the child Glyphs will be Labels. Thus the height of
54 the HPoly will be the maximum height of its child Glyphs and, since,
55 all Labels have a height of 1, the height of the HPoly is 1 character.
56 The width of the HPoly is the sum of the widths of its children.
57
58 For more detail see [Layout Labels Horizontally](https://github.com/megaannum/forms/blob/master/tutorial/forms/LayoutLabelsHorizontally.md)
59
60 ## Alignment
61
62 When a parent Glyph is to draw one of its child Glyph in a region and the
63 child Glyph is smaller than the region, either smaller in width or height
64 or both, then the parent Glyph must use an alignment to position the child
65 Glyph. A horizontal alignment attribute can have discrete values: 'L', 'C'
66 or 'R' or a Float value between 0.0 and 1.0. Similarly, a vertical alignment
67 attribute has discrete values: 'T', 'C' or 'B' or Float 0.0 to 1.0.
68
69 For more detail see [Alignment](https://github.com/megaannum/forms/blob/master/tutorial/forms/Alignment.md)
70
71 ## Layout Labels Vertically with Alignment
72
73 A VPoly is a Poly that lays out its children vertically. A VPoly that contains
74 multiple Label Glyphs as children will have to align some of the Labels if
75 they have different sizes. By default, a VPoly aligns to the Left but
76 the default can be overridden for all children and/or on a case-by-case
77 basis.
78
79 For more detail see [Layout Labels Vertically](https://github.com/megaannum/forms/blob/master/tutorial/forms/LayoutLabelsVertically.md)
80
81 ## Grid, Polys and Boxes
82
83 Forms lets Glyphs be surrounded by box drawing characters. This is useful
84 for organizing the presentation. Forms supports the "standard" ASCII
85 box drawing characters: '+', '-' and '|'; as well as, UTF-8 characters
86 specifically designed for drawing boxes (they are actually called box
87 drawing character!).
88
0124e71 sixth tutorial snapshot save
megaannum authored
89 For more detail see [Boxes](https://github.com/megaannum/forms/blob/master/tutorial/forms/Boxes.md)
ceb6a35 snapshot save
megaannum authored
90
91 ## Action
92
93 Associated with many interactive Glyphs are Actions. When you click a button,
0124e71 sixth tutorial snapshot save
megaannum authored
94 its Action executes. When you enter &ltCR> on a line editor, its Action executes.
ceb6a35 snapshot save
megaannum authored
95 When a slider is moved, its Action executes. All interactive Glyphs with
96 Actions execute the Action provided by the developer or executes its
97 default Action, the NoOp-Action that does nothing.
98
99 For more detail see [Action](https://github.com/megaannum/forms/blob/master/tutorial/forms/Action.md)
100
101 ## Command
102
103 Some interactive Glyphs can take a command String or an Action. When such
104 a Glyph is selected, an Event of type "Command" with additional attribute
105 with key "command" and value the command String is created and pre-pended
106 to the input queue. When the Viewer reads the next item from the input
107 queue, if its an inner Viewer, the Command Event is put back onto the
108 front of the input queue and the Viewer control "pops" up to its the
109 parent Viewer - which repeats the process - until it is the top-level
110 Viewer that removes the Command Event from the input queue. This
111 Viewer (it run() method) simply returns the Command Event to the
112 calling Form run() method and it is this Form that then takes the
113 command String from the Event and, as the last thing it does before
114 exiting its run() method, executes the command.
115
116 For more detail see [Command](https://github.com/megaannum/forms/blob/master/tutorial/forms/Command.md)
117
118 ## Button
119
120 A Button is an interactive Glyph. A Button can have an Action Object associated
0124e71 sixth tutorial snapshot save
megaannum authored
121 with it or a command String. When it is selected (&ltCR>, &ltSpace>
122 or &ltRightMouse>), if the Button has an Action, that Action executes.
ceb6a35 snapshot save
megaannum authored
123 If the Button has a command, the Button creates an Event of type "Command"
124 with an additional entry of key "command" and value the Button's command
125 String and places the Command Event at the front of the input queue.
126
127 For more detail see [Button](https://github.com/megaannum/forms/blob/master/tutorial/forms/Button.md)
128
129 ## More Code Structure (return values)
130
131 When the Form run() method returns, it returns either 0, meaning no return
132 value or it returns a Dictionary of Glyph tags as the keys and the Glyph
133 result values. It is up to the code that originally launched
134
135 For more detail see [More Code Structure](https://github.com/megaannum/forms/blob/master/tutorial/forms/MoreCodeStructure.md)
136
137 ## Submit Button
138
139 When a Button's Action creates an Event of type "Submit", Sub-Viewers that
140 read the Submit Event simply place it back on the input queue and pop up to
141 their parent Viewer. The top-level viewer, returns the Submit Event
142 to the Form that called the Viewer code. This Form then walks the Glyph
143 tree with a Dictionary requesting each Glyph add to the Dictionary its
144 tag as a key and its result value as the value associated with the key.
145 Not all Glyphs have to add a tag/result pair. Mostly, Editors, Radiobuttons,
146 ToggleButtons, Sliders, and other interactive Glyphs that maintain user
147 entered state are the ones that add such tag/result pairs.
148
149 For more detail see [Submit Button](https://github.com/megaannum/forms/blob/master/tutorial/forms/SubmitButton.md)
150
151 ## Events (Submit Cancel)
152
153 Traditional forms can be:
154
155 * Information which present some information to the user and have a Close Button,
156 * Binary, Yes and No Buttons, presenting the user with an option,
157 * Requesting information from the user with Cancel and Accept/Submit Buttons, et.
158
159 In each of these cases, the Buttons either generate a Submit Event or a Cancel Event and place the Event at the front of the input queue.
160
161 For more detail see [Events](https://github.com/megaannum/forms/blob/master/tutorial/forms/Events.md)
162
163 ## Linking Glyphs
164
165 Sometimes two or more interactive Glyphs maybe linked, changing the value of one of them is reflected in the other(s).
166
167 ### Editor and Slider
168
169 Common example is a Line Editor
170 with a fixed width and a Slider that has resolution and size sufficient
171 to display the values.
172
173 For more detail see [Linking Editor and Slider](https://github.com/megaannum/forms/blob/master/tutorial/forms/LinkingEditorSlider.md)
174
175 ### SelectList and Deck
176
177 Another useful linking is that of a SelectList and a Deck. A SelectList allows
178 on to choose a value from a list of values. A Deck is a Poly that is like
179 a deck of cards; only the selected, "top", Card is displayed. Each value
180 in the SelectList is associated with one card in the Deck. When a SelectList
181 value is selected, the associated Card is moved to the top of the Deck.
182
183 For more detail see [Linking SelectList and Deck](https://github.com/megaannum/forms/blob/master/tutorial/forms/LinkingSelectListDeck.md)
184
185 ## Viewer
186
187 The Viewer is a Mono Glyph that handles keyboard and mouse events in
188 its 'run()' method.
189 Some such events it handles itself while other is passes down to the
190 descendent that currently has focus (if it exists).
191
0124e71 sixth tutorial snapshot save
megaannum authored
192 For more detail see [Viewer](https://github.com/megaannum/forms/blob/master/tutorial/forms/Viewer.md)
ceb6a35 snapshot save
megaannum authored
193
194 ## Form
195
196 The Form Glyph is a Viewer Glyph that is concerned with assuring that
197 it, the Form, can, in fact, be displayed (enough room in the window),
198 save the current window state,
199 runs its underlying Viewer, performs cleanup and restores
200 the previously saved window state.
201 It overrides the Viewer's 'run()' method to do these things, but in the
202 middle it does call the Viewer's version of the 'run()' method.
203
204 For more detail see [Form](https://github.com/megaannum/forms/blob/master/tutorial/forms/Form.md)
205
ee8c778 second tutorial snapshot save
megaannum authored
206 ## Modifying an Existing Glyph
207
208 Sometimes an existing Glyph has most of what a developer wants and,
209 with some minor adjustments, it would be just right. So, does one
210 create a whole new Glyph Prototype or does one simply create a
211 clone of the existing Prototype and then modify that Object.
212 Of course, its a trade off.
ceb6a35 snapshot save
megaannum authored
213
214 For more detail see [Modifying Glyph](https://github.com/megaannum/forms/blob/master/tutorial/forms/ModifyingGlyph.md)
215
216 ## Creating a new Glyph
217
ee8c778 second tutorial snapshot save
megaannum authored
218 When creating a new Glyph kind for general usage, there are a number of
219 things that must be considered. Is it a container Glyph which is to say,
220 is it a Mono, Poly or Grid Glyph or is it a Leaf Glyph. Will it be
221 an interactive Glyph of non-interactive. Will it handle Events.
222 Will it work only if UTF-8 characters are available. Does it create
223 any highlighting. Can its size change during usage.
224
ceb6a35 snapshot save
megaannum authored
225 For more detail see [Creating Glyph](https://github.com/megaannum/forms/blob/master/tutorial/forms/CreatingGlyph.md)
Something went wrong with that request. Please try again.