Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 142 lines (110 sloc) 6.173 kb
ceb6a35 snapshot save
megaannum authored
1 # Form
2
3 A Form Glyph is a kind of Viewer Glyph.
4
5 The Form Glyph's 'run()' method is responsible for:
6
7 * Saving Vim's current state,
8 * Making sure an appropriate font is used,
9 * Determining if the form can fit in the current window,
10 * Determining where to place in form in the window,
11 * Saving the current text in the window where the form will be rendered,
12 * Making sure that the area where the form will be rendered is "adequate"
13 and if it is not making it "adequate",
14 * Doing a top-down size request of the Form's child,
15 * Calling the Form's Viewer's 'run()' method,
16 * Processing the Form's Viewer's 'run()' method return value,
17 * Restoring the original text in the window,
18 * Restoring the original font,
19 * Restoring the original Vim state, and, if appropriate,
20 * Returning a value to the calling code.
21
22 ## Saving Vim's current state,
23
24 During this part of the Form 'run()' method, the existing Vim
25 state is saved - specifically:
26
27 * Option values.
28 * The matches returned by 'getmatches()' then then 'clearmatches()' is
29 called.
30 * The value of '&mouse' is saved and then 'mouse' is set to 'a'.
31 * The value of '&wrap' is saved and then 'set nowrap' is executed.
32 * Both '&scrolloff' and '&sidescrolloff' are saved and then both are
33 set to zero.
34
35 Then, if the Viewer Stack is empty, meaning that this is the top-level
36 Form, then the following are saved:
37
38 * Both '&syntax' and 'b:current_syntax' are saved and 'syntax' is set
39 to empty and 'syntax clear' is executed.
40 * If 'gui_running' is true, then '&guifont' is save and then 'guifont'
41 is set to the value of 'g:forms_gui_font' which has default value
42 'Fixed 20'.
43 * The result of calling 'winsaveview()' is saved.
44 * And, finally, code is executed to make sure the undo list is not empty:
45 ' execute ":normal G$a "', and temp-file is gotten and the
46 undo list is written to that file (using wundo).
47
48 ## Can Window hold Form
49
50 By calling 'requestSize()' on the Form's child Glyph, the size of the
51 form to be rendered is gotten. This is a List containing the width and
52 height of the Form. It should be noted that **ALL** Forms are rectangular.
53 Next, the line at the top-of-the-window
54 is determined as well as the number of lines in the window and the
55 number of columns. If the form can fit within the window, all is good.
56 If not, then if an error information Form can be displayed to the
57 user, then it is displayed. Otherwise, an exception is throw containing
58 the same message that the error Form would have displayed.
59
60 ## Saving Current Text
61
62 A Form overwrites existing text so it is important to save the original
63 text in the window, if there is any, so that it can be restored when
64 the Form exits.
65
66 It is also important to provide a field of characters, whether part of
67 the original text or new lines of characters, so that when the Form
68 renders all of the Vim draw command are replacing or substituting over
69 existing text. If for some line/column positions there are characters
70 while for others the are none, it is more difficult to assure that
71 all of the Form renders correctly. Think of it as adding
72 [Gesso](https://en.wikipedia.org/wiki/Gesso) over a canvas in order to
73 provide a uniform surface.
74
75 So, prior to rendering the Form, the area where the Form is to be
76 rendered must be saved and then all the lines must be at least the
77 width of the right side of the Form and no line should wrap.
78 There, one of Form's secret sauce is out.
79
80
81 ## Initial Rendering of Form
82
83 The Form must be rendered to the window. This is done by calling
84 the Form's child Glyph's 'draw(allocation)' passing it the top-level
85 Form allocation:
86
87 let allocation = {
88 \ 'line': top_line_of_form,
89 \ 'column': left_column_of_form,
90 \ 'width': width_of_form,
91 \ 'height': height_of_form
92 \ }
93
94 As each descendent Glyph calls its children to draw, they pass down an
95 allocation Dictionary. If the parent Glyph has a single child Glyph and
96 they both have the same size and position, such as the Background Glyph,
97 then the same allocation can be passed from parent to child. But,
98 generally and its safer, to pass down a copy. If the allocation
99 has to be modified by the parent to give to a child, the it is
100 important to make a copy. Each Glyph caches the allocation it receives
101 in its 'draw(allocation)' method. Many Glyph reuse this allocation
102 in other methods and a non-empty allocation is the means used to
103 determine if a Glyph has been rendered at least once.
104
105
106 ## Calling 'run()' Method
107
108 A Form Glyph is a Viewer Glyph; the Form 'run()' method calls the Viewer 'run()'
109 method. The Viewer 'run()' method returns one of the following Event types:
110
9e930f0 seventh tutorial snapshot save
megaannum authored
111 * Exit: Character <Esc> maps to 'Exit' and Form returns empty Dictionary.
ceb6a35 snapshot save
megaannum authored
112 * ReSize: The size of the form has changed, the window text is recaptured and the Viewer 'run()' method is called again.
113 * Command: A command to execute on the command-line, and an empty Dictionary is
114 returned.
115 * Submit: Form descendent Glyphs add tag/values to Dictionary returned.
116 * Cancel; Similar to 'Exit', the Form returns empty Dictionary.
117
118 ## Returning Cleanup
119
120 Everything that was saved and set in preparation to call the Viewer 'run()'
121 method is now restored and unset. The original captured text is restored
122 to the window. If lines had to be added, they are removed. All of the
123 highlights attached to all of the Form's dependences are deleted.
124 If the Form's 'delete' attribute is 'true', then the child body of the Form
125 has its 'delete()' method call which enables Glyphs to do any Glyph
126 particular cleanup.
127
128 The original syntax settings are restored.
129
130 If the Viewer Stack is empty, then the original 'gui' font is restored.
131
132 The undo list is set using 'rundo' with the contents of the previously
133 saved undo file. Also ":normal u" is executed to remove the space that
134 was originally inserted (making sure the undo list was not empty).
135
136 The view of the current window is restored by calling 'winrestview(saved_view)'.
137
138 If a command is to be executed, it is now evaluated.
139
140 And, finally, control is returned to the code that called the Form's 'run()'
141 method with the Dictionary return value.
Something went wrong with that request. Please try again.