|
1 *drawit.txt* The DrawIt Tool Apr 10, 2006 |
|
2 |
|
3 Authors: Charles E. Campbell, Jr. <NdrchipO@ScampbellPfamily.AbizM> |
|
4 Sylvain Viart <molo@multimania.com> |
|
5 (remove NOSPAM from Campbell's email first) |
|
6 Copyright: Copyright (C) 2004-2006 Charles E. Campbell, Jr. {{{1 |
|
7 Permission is hereby granted to use and distribute this code, |
|
8 with or without modifications, provided that this copyright |
|
9 notice is copied with it. Like anything else that's free, |
|
10 DrawIt.vim is provided *as is* and comes with no warranty |
|
11 of any kind, either expressed or implied. By using this |
|
12 plugin, you agree that in no event will the copyright |
|
13 holder be liable for any damages resulting from the use |
|
14 of this software. |
|
15 |
|
16 |
|
17 ============================================================================== |
|
18 1. Contents *drawit-contents* |
|
19 |
|
20 1. Contents......................: |drawit-contents| |
|
21 2. DrawIt Manual.................: |drawit| |
|
22 3. DrawIt Usage..................: |drawit-usage| |
|
23 Starting....................: |drawit-start| |
|
24 Stopping....................: |drawit-stopping| |
|
25 User Map Protection.........: |drawit-protect| |
|
26 Drawing.....................: |drawit-drawing| |
|
27 Changing Drawing Characters.: |drawit-setdrawit| |
|
28 Moving......................: |drawit-moving| |
|
29 Erasing.....................: |drawit-erase| |
|
30 Example.....................: |drawit-example| |
|
31 Visual Block Mode...........: |drawit-visblock| |
|
32 Brushes.....................: |drawit-brush| |
|
33 DrawIt Modes................: |drawit-modes| |
|
34 4. DrawIt History................: |drawit-history| |
|
35 |
|
36 |
|
37 ============================================================================== |
|
38 2. DrawIt Manual *drawit* |
|
39 *drawit-manual* |
|
40 /=============+============================================================\ |
|
41 || Starting & | || |
|
42 || Stopping | Explanation || |
|
43 ++------------+-----------------------------------------------------------++ |
|
44 || \di | start DrawIt || |
|
45 || \ds | stop DrawIt || |
|
46 || :DIstart | start DrawIt || |
|
47 || :DIstop | stop DrawIt || |
|
48 || | || |
|
49 ++============+===========================================================++ |
|
50 || Maps | Explanation || |
|
51 ++------------+-----------------------------------------------------------++ |
|
52 || | The DrawIt routines use a replace, move, and || |
|
53 || | replace/insert strategy. The package also lets one insert|| |
|
54 || | spaces, draw arrows by using the following characters or || |
|
55 || | keypad characters: || |
|
56 || +-----------------------------------------------------------++ |
|
57 || <left> | move and draw left || |
|
58 || <right> | move and draw right, inserting lines/space as needed || |
|
59 || <up> | move and draw up, inserting lines/space as needed || |
|
60 || <down> | move and draw down, inserting lines/space as needed || |
|
61 || <s-left> | move left || |
|
62 || <s-right> | move right, inserting lines/space as needed || |
|
63 || <s-up> | move up, inserting lines/space as needed || |
|
64 || <s-down> | move down, inserting lines/space as needed || |
|
65 || <space> | toggle into and out of erase mode || |
|
66 || > | insert a > and move right (draw -> arrow) || |
|
67 || < | insert a < and move left (draw <- arrow) || |
|
68 || ^ | insert a ^ and move up (draw ^ arrow) || |
|
69 || v | insert a v and move down (draw v arrow) || |
|
70 || <pgdn> | replace with a \, move down and right, and insert a \ || |
|
71 || <end> | replace with a /, move down and left, and insert a / || |
|
72 || <pgup> | replace with a /, move up and right, and insert a / || |
|
73 || <home> | replace with a \, move up and left, and insert a \ || |
|
74 || \> | insert a fat > and move right (draw -> arrow) || |
|
75 || \< | insert a fat < and move left (draw <- arrow) || |
|
76 || \^ | insert a fat ^ and move up (draw ^ arrow) || |
|
77 || \v | insert a fat v and move down (draw v arrow) || |
|
78 || | || |
|
79 ||============+===========================================================++ |
|
80 ||Visual Cmds | Explanation || |
|
81 ||------------+-----------------------------------------------------------++ |
|
82 || | The drawing mode routines use visual-block mode to || |
|
83 || | select endpoints for lines, arrows, and ellipses. Bresen- || |
|
84 || | ham and Bresenham-like algorithms are used for this. || |
|
85 || | || |
|
86 || | These routines need a block of spaces, and so the "holer" || |
|
87 || | routine must first be used to create such a block. The || |
|
88 || | holer routine will query the user for the number of lines || |
|
89 || | to hold |'textwidth'| spaces. || |
|
90 || +-----------------------------------------------------------++ |
|
91 || \a | draw arrow from corners of visual-block selected region || |
|
92 || \b | draw box on visual-block selected region || |
|
93 || \e | draw an ellipse on visual-block selected region || |
|
94 || \f | flood figure with a character (you will be prompted) || |
|
95 || \h | the holer routine (will query user, see above) || |
|
96 || \l | draw line from corners of visual-block selected region || |
|
97 || \s | spacer: appends spaces up to the textwidth (default: 78) || |
|
98 || | || |
|
99 ++============+===========================================================++ |
|
100 || Function and Explanation || |
|
101 ++------------+-----------------------------------------------------------++ |
|
102 || :call SetDrawIt('vertical','horizontal','crossing','\','/','X') || |
|
103 || set drawing characters for motions for moving || |
|
104 || default motion || |
|
105 || | up/down, || |
|
106 || - left/right, || |
|
107 || + -| crossing, || |
|
108 || \ downright, || |
|
109 || / downleft, and || |
|
110 || X \/ crossing || |
|
111 ++=====================+==================================================++ |
|
112 || Commands | Explanation || |
|
113 ++---------------------+--------------------------------------------------++ |
|
114 || :SetBrush a-z | sets brush (register) to given || |
|
115 || :'<,'>SetBrush a-z | yanks visual block to brush (register) || |
|
116 \==========================================================================/ |
|
117 |
|
118 |
|
119 ============================================================================== |
|
120 3. DrawIt Usage *drawit-usage* |
|
121 |
|
122 STARTING *drawit-start* |
|
123 \di |
|
124 |
|
125 Typically one puts <drawit.vim> into the .vim/plugin directory |
|
126 (vimfiles\plugin for MS) where it becomes always available. It uses a minimal |
|
127 interface (\di: you can think of it as *D*raw*I*t or *D*rawIt *I*nitialize) to |
|
128 start it and (\ds: *D*rawIt *S*top) to stop it. Instead of using "\" you may |
|
129 specify your own preference for a map leader (see |mapleader|). |
|
130 |
|
131 A message, "[DrawIt]", will appear on the message line. |
|
132 |
|
133 |
|
134 STOPPING *drawit-stopping* |
|
135 \ds |
|
136 |
|
137 When you are done with DrawIt, use \ds to stop DrawIt mode. Stopping DrawIt |
|
138 will restore your usual options and remove the maps DrawIt set up. |
|
139 |
|
140 A message, "[DrawIt off]", will appear on the message line. |
|
141 |
|
142 |
|
143 USER MAP PROTECTION *drawit-protect* |
|
144 |
|
145 Starting DrawIt causes it to set up a number of maps which facilitate |
|
146 drawing. Just use the arrow keys or the keypad to cruise around your display. |
|
147 DrawIt will then leave appropriate lines as you move horizontally, vertically, |
|
148 or diagonally, and will transparently enlarge your file to accommodate your |
|
149 drawing as needed. DrawIt saves both maps and user options and sets them to |
|
150 its own needs. You may use h-j-k-l to move about your display and generally |
|
151 use editing commands as you wish even while in DrawIt mode. |
|
152 |
|
153 |
|
154 OPTIONS |
|
155 |
|
156 g:drawit_insertmode : if this variable exists *drawit-options* |
|
157 and is 1 then maps are made |
|
158 which make cursor-control |
|
159 drawing available while in |
|
160 insert mode. |
|
161 |
|
162 DRAWING *drawit-drawing* |
|
163 |
|
164 After DrawIt is started, just use the number pad to move the cursor about. It |
|
165 will leave a trail of -s, |s, \s, /s (depending on which direction and |
|
166 SetDrawIt() changes), and +s and Xs where line crossing occurs. |
|
167 |
|
168 |
|
169 CHANGING DRAWING CHARACTERS *drawit-setdrawit* |
|
170 |
|
171 The SetDrawIt() function is available for those who wish to change the |
|
172 characters that DrawIt uses. > |
|
173 |
|
174 ex. :call SetDrawIt('*','*','*','*','*','*') |
|
175 ex. :call SetDrawIt('-','|','-','\','/','/') |
|
176 < |
|
177 The first example shows how to change all the DrawIt drawing characters to |
|
178 asterisks, and the second shows how to give crossing priority to - and /. |
|
179 |
|
180 |
|
181 MOVING *drawit-move* *drawit-moving* |
|
182 |
|
183 DrawIt supports shifting the arrow keys to cause motion of the cursor. The |
|
184 motion of the cursor will not modify what's below the cursor. The cursor |
|
185 will move and lines and/or spaces will be inserted to support the move as |
|
186 required. Your terminal may not support shifted arrow keys, however, or Vim |
|
187 may not catch them as such. For example, on the machine I use, shift-up |
|
188 (<s-up>) produced <Esc>[161q, but vim didn't know that sequence was a <s-up>. |
|
189 I merely made a nmap: |
|
190 |
|
191 nmap <Esc>[161q <s-up> |
|
192 |
|
193 and vim thereafter recognized the <s-up> command. |
|
194 |
|
195 |
|
196 ERASING *drawit-erase* |
|
197 <space> |
|
198 |
|
199 The <space> key will toggle DrawIt's erase mode/DrawIt mode. When in |
|
200 [DrawIt erase] mode, a message "[DrawIt erase]" will appear and the |
|
201 number pad will now cause spaces to be drawn instead of the usual drawing |
|
202 characters. The drawing characters will be restored when the <space> |
|
203 key toggles DrawIt back to regular DrawIt mode. |
|
204 |
|
205 |
|
206 EXAMPLES *drawit-example* |
|
207 |
|
208 Needless to say, the bottom spirals were done with DrawIt and some |
|
209 block editing with Vim: > |
|
210 |
|
211 +------------ -----------+ +------------ -----------+ +------------ |
|
212 |+----------+ +---------+| |+----------+ +---------+| |+----------+ |
|
213 ||+--------+| |+-------+|| ||+--------+| |+-------+|| ||+--------+| |
|
214 |||-------+|| ||+------||| |||-------+|| ||+------||| |||-------+|| |
|
215 ||+-------+|| ||+------+|| ||+-------+|| ||+------+|| ||+-------+|| |
|
216 |+---------+| |+--------+| |+---------+| |+--------+| |+---------+| |
|
217 +-----------+ +----------+ +-----------+ +----------+ +-----------+ |
|
218 |
|
219 VISUAL BLOCK MODE FOR ARROWS LINES BOXES AND ELLIPSES *drawit-visblock* |
|
220 \a \b \e \h \l \s |
|
221 |
|
222 The DrawIt package has been merged with Sylvain Viart's drawing package |
|
223 which provides DrawIt with visual-block selection of starting/ending |
|
224 point drawing of arrows (\a), lines (\l), and boxes (\b). Additionally |
|
225 I wrote an ellipse drawing function using visual block specification (\e). |
|
226 |
|
227 One must have a block of spaces for these maps which the "holer" routine |
|
228 (\h) will help create. The holer routine will query the user for the number |
|
229 of lines s/he wishes to have, and will fill those lines with spaces out to the |
|
230 |'textwidth'| (or 78 spaces if that option hasn't been set). |
|
231 |
|
232 The Sylvain Viart functions and the ellipse drawing function depend |
|
233 upon using visual block mode. Typical use: > |
|
234 |
|
235 Example: * \h |
|
236 DrawIt asks: how many lines under the cursor? 10 |
|
237 DrawIt then appends 10 lines filled with blanks |
|
238 out to textwidth (if defined) or 78 columns. |
|
239 * ctrl-v (move) \b |
|
240 DrawIt then draws a box |
|
241 < |
|
242 One first creates a number of blank-filled lines; the \h map (the "holer") is |
|
243 useful for this. Select the first endpoint with ctrl-v and then move to the |
|
244 other endpoint. One may then select \a for arrows, \b for boxes, \e for ellipses, |
|
245 or \l for lines. |
|
246 > |
|
247 Examples: |
|
248 |
|
249 __ _ *************** +-------+ |
|
250 \_ _/ **** **** | | |
|
251 \_ _/ ** ---------> ** | | |
|
252 \_ _/ **** **** | | |
|
253 \__/ <------- *************** +-------+ |
|
254 |
|
255 \l \a \e and \a \b |
|
256 < |
|
257 *drawit-setbrush* |
|
258 BRUSHES *drawit-brush* |
|
259 > |
|
260 :SetBrush a-z |
|
261 < |
|
262 Set the current brush to the given letter (actually, its |
|
263 a named register; see |quotea|). Default brush: a |
|
264 > |
|
265 :'<,'>SetBrush a-z |
|
266 < |
|
267 Set the current brush to the given letter, and yank the visual |
|
268 block to that named register (see |quotea|). Default brush: a |
|
269 > |
|
270 <shift-leftmouse> |
|
271 < |
|
272 One may drag and draw with the current brush (default brush: a) |
|
273 by holding down the shift key and the leftmouse button and moving |
|
274 the mouse. Blanks in the brush are considered to be transparent. |
|
275 > |
|
276 \ra ... \rz |
|
277 < |
|
278 Replace text with the given register. |
|
279 > |
|
280 \pa ... \pz |
|
281 < |
|
282 Like \ra ... \rz, except that blanks are considered to be transparent. |
|
283 |
|
284 DRAWIT MODES *drawit-modes* |
|
285 |
|
286 -[DrawIt] regular DrawIt mode |
|
287 -[DrawIt off] DrawIt is off |
|
288 -[DrawIt erase] DrawIt will erase using the number pad |
|
289 |
|
290 g:DrChipTopLvlMenu: by default its "DrChip"; you may set this to whatever |
|
291 you like in your <.vimrc>. This variable controls where |
|
292 DrawIt's menu items are placed. |
|
293 |
|
294 |
|
295 ============================================================================== |
|
296 4. History *drawit-history* |
|
297 |
|
298 7 Feb 16, 2005 * now checks that "m" is in &go before attempting to |
|
299 use menus |
|
300 Aug 17, 2005 * report option workaround |
|
301 Nov 01, 2005 * converted DrawIt to use autoload feature of vim 7.0 |
|
302 Dec 28, 2005 * now uses cecutil to save/restore user maps |
|
303 Jan 18, 2006 * cecutil now updated to use keepjumps |
|
304 Jan 23, 2006 * :DIstart and :DIstop commands provided; thus users |
|
305 using "set noremap" can still use DrawIt. |
|
306 Jan 26, 2006 * DrawIt menu entry now keeps its place |
|
307 Apr 10, 2006 * Brushes were implemented |
|
308 6 Feb 24, 2003 * The latest DrawIt now provides a fill function. |
|
309 \f will ask for a character to fill the figure |
|
310 surrounding the current cursor location. Plus |
|
311 I suggest reading :he drawit-tip for those whose |
|
312 home/pageup/pagedown/end keys aren't all working |
|
313 properly with DrawIt. |
|
314 08/18/03 : \p[a-z] and \r[a-z] implemented |
|
315 08/04/03 : b:..keep variables renamed to b:di_..keep variables |
|
316 StopDrawIt() now insures that erase mode is off |
|
317 03/11/03 : included g:drawit_insertmode handling |
|
318 02/21/03 : included flood function |
|
319 12/11/02 : deletes trailing whitespace only if holer used |
|
320 8/27/02 : fat arrowheads included |
|
321 : shift-arrow keys move but don't modify |
|
322 |
|
323 vim:tw=78:ts=8:ft=help |