DrawIt.txt*    The DrawIt Tool                Nov 25, 2013Authors:  Charles E. Campbell  <NdrchipO@ScampbellPfamily.AbizM>          Sylvain Viart             <molo@multimania.com>      (remove NOSPAM from Campbell‘s email first)Copyright:    Copyright (C) 2004-2013 Charles E. Campbell          Permission is hereby granted to use and distribute this code,          with or without modifications, provided that this copyright          notice is copied with it. Like anything else that‘s free,          DrawIt.vim and DrawItPlugin.vim are provided *as is*; it comes          with no warranty of any kind, either expressed or implied. By          using this plugin, you agree that in no event will the copyright          holder be liable for any damages resulting from the use of this          software.==============================================================================1. Contents                        *drawit-contents* {{{1    1. Contents......................: |drawit-contents|    2. DrawIt Manual.................: |drawit|    3. DrawIt Usage..................: |drawit-usage|         Starting....................: |drawit-start|         Stopping....................: |drawit-stop|         User Map Protection.........: |drawit-protect|         Drawing.....................: |drawit-drawing|         Tip.........................: |drawit-tip|         Changing Drawing Characters.: |drawit-setdrawit|         Moving......................: |drawit-moving|         Erasing.....................: |drawit-erase|         Example.....................: |drawit-example|         Visual Block Mode...........: |drawit-visblock|         Brushes.....................: |drawit-brush|         DrawIt Modes................: |drawit-modes|    4. DrawIt History................: |drawit-history|==============================================================================2. DrawIt Manual                    *drawit* {{{1                            *drawit-manual* /===============+============================================================ || Starting &   |                                                           || || Stopping     | Explanation                                               || ++--------------+-----------------------------------------------------------++ ||  \di         | start DrawIt                     |drawit-start|             || ||  \ds         | stop  DrawIt                     |drawit-stop|              || ||  :DIstart    | start DrawIt                     |drawit-start|             || ||  :DIstart S  | start DrawIt in single-bar mode  |drawit-start|             || ||  :DIstart D  | start DrawIt in double-bar mode  |drawit-start|             || ||  :DIsngl     | start DrawIt in single-bar mode  |drawit-start| |drawit-sngl| || ||  :DIdbl      | start DrawIt in double-bar mode  |drawit-start| |drawit-dbl|  || ||  :DIstop     | stop  DrawIt                     |drawit-stop|              || ||  :DrawIt[!]  | start/stop DrawIt                |drawit-start| |drawit-stop| || ||              |                                                           || ++==============+===========================================================++ ||   Maps       | Explanation                                               || ++--------------+-----------------------------------------------------------++ ||              | The DrawIt routines use a replace, move, and              || ||              | replace/insert strategy.  The package also lets one insert|| ||              | spaces, draw arrows by using the following characters or  || ||              | keypad characters:                                        || ||              +-----------------------------------------------------------++ || <left>       | move and draw left                         |drawit-drawing| || || <right>      | move and draw right, inserting lines/space as needed      || || <up>         | move and draw up, inserting lines/space as needed         || || <down>       | move and draw down, inserting lines/space as needed       || || <s-left>     | move cursor left                              |drawit-move| || || <s-right>    | move cursor right, inserting lines/space as needed        || || <s-up>       | move cursor up, inserting lines/space as needed           || || <s-down>     | move cursor down, inserting lines/space as needed         || || <space>      | toggle into and out of erase mode                         || || >            | insert a > and move right    (draw -> arrow)              || || <            | insert a < and move left     (draw <- arrow)              || || ^            | insert a ^ and move up       (draw ^  arrow)              || || v            | insert a v and move down     (draw v  arrow)              || || <pgdn>       | replace with a \, move down and right, and insert a \     || || <end>        | replace with a /, move down and left,  and insert a /     || || <pgup>       | replace with a /, move up   and right, and insert a /     || || <home>       | replace with a \, move up   and left,  and insert a \     || || \>           | insert a fat > and move right    (draw -> arrow)          || || \<           | insert a fat < and move left     (draw <- arrow)          || || \^           | insert a fat ^ and move up       (draw ^  arrow)          || || \v           | insert a fat v and move down     (draw v  arrow)          || ||<s-leftmouse> | drag and draw with current brush            |drawit-brush|  || ||<c-leftmouse> | drag and move current brush                 |drawit-brush|  || ||              |                                                           || ||==============+===========================================================++ ||Visual Cmds   | Explanation                                               || ||--------------+-----------------------------------------------------------++ ||              | The drawing mode routines use visual-block mode to        || ||              | select endpoints for lines, arrows, and ellipses. Bresen- || ||              | ham and Bresenham-like algorithms are used for this.      || ||              |                                                           || ||              | These routines need a block of spaces, and so the canvas  || ||              | routine must first be used to create such a block.  The   || ||              | canvas routine will query the user for the number of      || ||              | lines to hold |‘textwidth‘| spaces.                         || ||              +-----------------------------------------------------------++ || \a           | draw arrow from corners of visual-block selected region   ||  |drawit-a| || \b           | draw box on visual-block selected region                  ||  |drawit-b| || \c           | the canvas routine (will query user, see above)           ||  |drawit-c| || \e           | draw an ellipse on visual-block selected region           ||  |drawit-e| || \f           | flood figure with a character (you will be prompted)      ||  |drawit-f| || \l           | draw line from corners of visual-block selected region    ||  |drawit-l| || \s           | spacer: appends spaces up to the textwidth (default: 78)  ||  |drawit-s| ||              |                                                           || ++==============+===========================================================++ || Function and Explanation                                                 || ++--------------+-----------------------------------------------------------++ ||  :call SetDrawIt(‘vertical‘,‘horizontal‘,‘crossing‘,‘\‘,‘/‘,‘X‘,‘*‘)     || ||            set drawing characters for motions for moving                 || ||            and for the ellipse drawing boundary        |drawit-setdrawit|  || ||  default   motion                                                        || ||  |         up/down,                                                      || ||  -         left/right,                                                   || ||  +         -| crossing,                                                  || ||  \         downright,                                                    || ||  /         downleft, and                                                 || ||  X         \/ crossing                                                   || ++=======================+==================================================++ ||  Commands             | Explanation                                      || ++-----------------------+--------------------------------------------------++ ||  :SetBrush a-z        | sets brush (register) to given register          || ||  :‘<,‘>SetBrush a-z   | yanks visual block to brush      |drawit-brush|||    || ||  :DInrml              | switch to normal mode            |drawit-nrml|     || ||  :DIsngl              | switch to single-line mode       |drawit-sngl|     || ||  :DIdbl               | switch to double-line mode       |drawit-dbl|      || \============================================================================/==============================================================================3. DrawIt Usage                        *drawit-usage* {{{1STARTING                        *drawit-start* {{{2\di           (starts in normal     drawing mode)       *drawit-\di*:DrawIt       (starts in normal     drawing mode)       *drawit-DrawIt*:DIstart      (starts in normal     drawing mode)       *drawit-DIstart*:DIstart S    (starts in single-bar drawing mode):DIstart D    (starts in double-bar drawing mode):DInrml       (starts in normal     drawing mode)       *drawit-DInrml*:DIsngl       (starts in single-bar drawing mode)       *drawit-DIsngl*:DIdbl        (starts in double-bar drawing mode)       *drawit-DIdbl*Typically one puts <drawit.vim> into the .vim/plugin directory(vimfiles\plugin for Windows) where it becomes always available.  It uses aminimal interface (\di: you can think of it as *D*raw*I*t or *D*rawIt*I*nitialize) to start it and (\ds: *D*rawIt *S*top) to stop it.  Instead ofusing "\" you may specify your own preference for a map leader (see|mapleader|).With a trailing ‘S‘, :DIstart will begin in single-bar mode (see |drawit-sngl|).With a trailing ‘D‘, :DIstart will begin in double-bar mode (see |drawit-dbl|).Similarly, :DIsngl and :DIdbl will start DrawIt as well as begin insingle-bar or double-bar mode, respectively.A message, "[DrawIt]", will appear on the message line.STOPPING                        *drawit-stop* {{{2\ds:DIstop:DrawIt!When you are done with DrawIt, use \ds to stop DrawIt mode.  Stopping DrawItwill restore your usual options and remove the maps DrawIt set up.A message, "[DrawIt off]", will appear on the message line.                        *drawit-utf16*                        *drawit-utf8* *drawit-unicode*NORMAL, SINGLE BAR, AND DOUBLE BAR MODES    *drawit-sngl* *drawit-dbl*:DInrml  :DIsngl  :DIdblOne may use these commands to start up Drawit in normal, single-bar, ordouble-bar modes, respectively.  When your |‘encoding‘| is utf-8 or utf-16,DrawIt supports drawing with special box characters (single-bar, double_bar).These commands are also used to switch to normal, single-bar, or double-barmodes.USER MAP PROTECTION                    *drawit-protect* {{{2Starting DrawIt causes it to set up a number of maps which facilitate drawing.DrawIt accommodates users with conflicting maps by saving both maps and useroptions and before setting them to what DrawIt needs.  When you stop DrawIt(|drawit-stop|), DrawIt will restore the user‘s maps and options as they werebefore DrawIt was started.OPTIONS                                                   *drawit-options* {{{2                            *g:drawit_insertmode*g:drawit_insertmode : if this variable exists and is 1 then maps are                  made which make cursor-control drawing available              while in insert mode, too.  Otherwise, DrawIt‘s              maps only affect normal mode.DRAWING                            *drawit-drawing* {{{2After DrawIt is started, use the number pad or arrow keys to move the cursorabout.  As the cursor moves, DrawIt will then leave appropriate "line"characters behind as you move horizontally, vertically, or diagonally, andwill transparently enlarge your file to accommodate your drawing as needed.The trail will consist of -, |, \, / characters (depending on which directionand SetDrawIt() changes), and + and X characters where line crossings occur.You may use h-j-k-l to move about your display and generally use editingcommands as you wish even while in DrawIt mode.Another tool that may be used to convert Ascii-art into nice pictures isavailable at https://github.com/christiangoltz/shaape .CHANGING DRAWING CHARACTERS                *drawit-setdrawit* {{{2The SetDrawIt() function is available for those who wish to change thecharacters that DrawIt uses. >    ex. :call SetDrawIt(‘*‘,‘*‘,‘*‘,‘*‘,‘*‘,‘*‘,‘*‘)    ex. :call SetDrawIt(‘-‘,‘|‘,‘-‘,‘\‘,‘/‘,‘/‘,‘*‘)<The first example shows how to change all the DrawIt drawing characters toasterisks, and the second shows how to give crossing priority to - and /.The default setting is equivalent to: >    :call SetDrawIt(‘|‘,‘-‘,‘+‘,‘\‘,‘/‘,‘X‘,‘*‘)<where SetDrawit()‘s arguments refer, in order, to the >    vertical            drawing character        horizontal            drawing character        horizontal/vertical crossing    drawing character        down right            drawing character        down left            drawing character        diagonal crossing        drawing character    ellipse boundary                drawing character<TIP                            *drawit-tip*I have found that sometimes one or more of the <home>, <end>, <pageup>,and <pagedown> keys give unique sequences but are not interpretedproperly by Vim.  This problem impacts DrawIt as it uses those fourkeys to signify diagonal moves/drawing.  One solution I use is toput into my <.vimrc> file mapings like:    map ^V... <home>where the ellipsis (...) is the actual character sequence produced byhitting the key.  The way to generate such maps is to type "map ",followed by three control-v presses, press the associated key, thena space followed by the proper interpretation sequence (ie. <home>).MOVING                    *drawit-move* *drawit-moving* {{{2DrawIt supports shifting the arrow keys to cause motion of the cursor.  Themotion of the cursor will not modify what‘s below the cursor.  The cursorwill move and lines and/or spaces will be inserted to support the move asrequired.  Your terminal may not support shifted arrow keys, however, or Vimmay not catch them as such.  For example, on the machine I use, shift-up(<s-up>) produced <Esc>[161q, but vim didn‘t know that sequence was a <s-up>.I merely made a nmap:    nmap <Esc>[161q    <s-up>and vim thereafter recognized the <s-up> command.ERASING                            *drawit-erase* {{{2<space>The <space> key will toggle DrawIt‘s erase mode/DrawIt mode.  When in [DrawIterase] mode, a message "[DrawIt erase]" will appear and the number pad willnow cause spaces to be drawn instead of the usual drawing characters.  Thedrawing behavior will be restored when the <space> key toggles DrawIt backto regular DrawIt mode.EXAMPLES                        *drawit-example* {{{2Needless to say, the square spirals which follow were done with DrawIt anda bit of block editing with Vim: >   +------------ -----------+ +------------ -----------+ +------------   |+----------+ +---------+| |+----------+ +---------+| |+----------+   ||+--------+| |+-------+|| ||+--------+| |+-------+|| ||+--------+|   |||-------+|| ||+------||| |||-------+|| ||+------||| |||-------+||   ||+-------+|| ||+------+|| ||+-------+|| ||+------+|| ||+-------+||   |+---------+| |+--------+| |+---------+| |+--------+| |+---------+|   +-----------+ +----------+ +-----------+ +----------+ +-----------+VISUAL BLOCK MODE FOR ARROWS LINES BOXES AND ELLIPSES    *drawit-visblock* {{{2\a : draw arrow from corners of visual-block selected region    *drawit-a*\b : draw box on visual-block selected region            *drawit-b*\c : the canvas routine (will query user, see above)        *drawit-c*\e : draw an ellipse on visual-block selected region        *drawit-e*\f : flood figure with a character (you will be prompted)    *drawit-f*\l : draw line from corners of visual-block selected region    *drawit-l*\s : spacer: appends spaces up to the textwidth (default: 78)    *drawit-s*The DrawIt package has been merged with Sylvain Viart‘s drawing package (bypermission) which provides DrawIt with visual-block selection ofstarting/ending point drawing of arrows (\a), lines (\l), and boxes (\b).Additionally I wrote an ellipse drawing function using visual blockspecification (|drawit-e|).One may create a block of spaces for these maps to operate in; the "canvas"routine (\c) will help create such blocks.  First, the s:Canvas() routine willquery the user for the number of lines s/he wishes to have, and will then fillthose lines with spaces out to the |‘textwidth‘| if user has specified it;otherwise, the display width will be used.Although most of the maps use visual-block selection, that isn‘t true of the\f map.  Instead, it assume that you have already drawn some closed figureand want to fill it with some character.The Sylvain Viart functions and the ellipse drawing function dependupon using visual block mode.  As a typical use: >    Example: * \h                   DrawIt asks: how many lines under the cursor? 10                   DrawIt then appends 10 lines filled with blanks                   out to textwidth (if defined) or 78 columns.                 * ctrl-v (move) \b                   DrawIt then draws a box         * ctrl-v (move) \e                   DrawIt then draws an ellipse<Select the first endpoint with ctrl-v and then move to the other endpoint.One may then select \a for arrows, \b for boxes, \e for ellipses, or \l forlines.  The internal s:AutoCanvas() will convert tabs to spaces and willextend with spaces as needed to support the visual block.  Note that whenDrawIt is enabled, virtualedit is also enabled (to "all").>        Examples:        __                _         ***************           +-------+          \_            _/      ****               ****       |       |            \_        _/      **      --------->       **     |       |              \_    _/          ****               ****       |       |                \__/   <-------     ***************           +-------+        \l        \a           \e and \a                  \b<                            *drawit-setbrush*BRUSHES                            *drawit-brush* {{{2> :SetBrush [a-z]<    Set the current brush to the selected brush register:>        ex.  :SetBrush b :‘<,‘>SetBrush [a-z]<    Select text for the brush by using visual-block mode: ctrl-v, move .    Then set the current text into the brush register:  (default brush: a)> <leftmouse><    Select a visual-block region.  One may use "ay, for example,    to yank selected text to register a.> <shift-leftmouse><    One may drag and draw with the current brush (default brush: a)    by holding down the shift key and the leftmouse button and moving    the mouse.  Blanks in the brush are considered to be transparent.> <ctrl-leftmouse><    One may drag and move a selection with <ctrl-leftmouse>.  First,    select the region using the <leftmouse>.  Release the mouse button,    then press ctrl and the <leftmouse> button; while continuing to press    the button, move the mouse.  The selected block of text will then    move along with the cursor.> \ra ... \rz<    Replace text with the given register‘s contents (ie. the brush).> \pa ... \pz<    Like \ra ... \rz, except that blanks are considered to be transparent.    Example: Draw the following >            \             o o             *            ---<        Then use ctrl-v, move, "ay to grab a copy into register a.        By default, the current brush uses register a (change brush        with :SetBrush [reg]).  Hold the <shift> and <leftbutton>        keys down and move the mouse; as you move, a copy of the        brush will be left behind.DRAWIT MODES                        *drawit-modes* {{{2  -[DrawIt]       regular DrawIt mode                     (|drawit-start|)  -[DrawIt off]   DrawIt is off                           (|drawit-stop| )  -[DrawIt erase] DrawIt will erase using the number pad  (|drawit-erase|)  g:DrChipTopLvlMenu: by default its "DrChip"; you may set this to whatever                  you like in your <.vimrc>.  This variable controls where          DrawIt‘s menu items are placed.==============================================================================4. History                        *drawit-history* {{{1    13    Sep 05, 2013    * improved s:Strlen() -- now uses |strdisplaywidth()|                  if available.        Sep 13, 2013    * (Paul Wagland) found a case where lines were                  being drawn with the wrong character.  This                  affected the Bresenham-algorithm based                  drawing facility (ie. lines and arrows                  specified by visual blocks;                  |drawit-a|, |drawit-l|).    12    Nov 16, 2012    * (Alexandre Viau) arrows weren‘t being drawn.                  Fixed.        Nov 29, 2012    * (Kim Jang-hwan) reported that with                  g:Align_xstrlen set to 3 that the cursor was                  moved (linewise) after invocation.  This                  problem also afflicted DrawIt.  Fixed.    11    Jan 21, 2010    * (Evan Stern) several places were using                  hardcoded drawing characters instead of                  b:di_... equivalents.        Feb 22, 2011    * for menus, &go =~# used to insure correct case        Sep 22, 2011    * ctrl-leftmouse (see |drawit-brush|) now moves the                  selected text entirely, no longer leaving a copy                  of the text where it was initially.        Nov 07, 2011    * included support for utf-8 box drawing characters        Nov 16, 2011    * included support for utf-8 single-double characters        Nov 16, 2011    * included support for cp437 box drawing characters        Dec 06, 2011    * included support for box and line drawing (\b, \l)                  support for utf-8 / cp437 box drawing characters        Dec 06, 2011    * fat arrows now use utf-8 characters when available        Jan 30, 2012    * \f supported when using utf-8/cp437 box drawing                  characters as boundary characters    10    Jun 12, 2008    * Fixed a bug with ctrl-leftmouse (which was leaving                  a space in the original selected text)        Mar 24, 2009    * :DrawIt starts, :DrawIt! stops DrawIt mode.        Mar 24, 2009    * I‘ve included <script> modifiers to the maps to                  cause rhs remapping only with mappings local to                  the script (see |:map-script|)    9    Sep 14, 2007    * Johann-Guenter Simon fixed a bug with s:DrawErase();                  it called SetDrawIt() and that call hadn‘t been                  updated to account for the new b:di_ellipse                  parameter.    8    Feb 12, 2007    * fixed a bug which prevented multi-character user                  maps from being restored properly        May 03, 2007    * Extended SetDrawIt() to handle b:di_ellipse, the                  ellipse boundary drawing character                * Changed "Holer" to "Canvas", and wrote AutoCanvas(),                  which allows one to use the visual-block drawing                  maps without creating a canvas first.                * DrawIt implements using the ctrl-leftmouse to move                  a visual-block selected region.                * Floods can now be done inside an ellipse                * DrawIt‘s maps are now all users of <buffer>     7    Feb 16, 2005    * now checks that "m" is in &go before attempting to                  use menus        Aug 17, 2005    * report option workaround        Nov 01, 2005    * converted DrawIt to use autoload feature of vim 7.0        Dec 28, 2005    * now uses cecutil to save/restore user maps        Jan 18, 2006    * cecutil now updated to use keepjumps        Jan 23, 2006    * :DIstart and :DIstop commands provided; thus users                  using  "set noremap" can still use DrawIt.        Jan 26, 2006    * DrawIt menu entry now keeps its place        Apr 10, 2006    * Brushes were implemented     6    Feb 24, 2003    * The latest DrawIt now provides a fill function.                  \f will ask for a character to fill the figure                  surrounding the current cursor location.  Plus                  I suggest reading :he drawit-tip for those whose                  home/pageup/pagedown/end keys aren‘t all working                  properly with DrawIt.        08/18/03    * \p[a-z] and \r[a-z] implemented        08/04/03    * b:..keep variables renamed to b:di_..keep variables                  StopDrawIt() now insures that erase mode is off        03/11/03    * included g:drawit_insertmode handling        02/21/03    * included flood function        12/11/02    * deletes trailing whitespace only if holer used        8/27/02        * fat arrowheads included                * shift-arrow keys move but don‘t modify ---------------------------------------------------------------------vim:tw=78:ts=8:ft=help:fdm=marker