path: root/vim/doc/DrawIt.txt

DrawIt.txt*	The DrawIt Tool				Nov 25, 2013

Authors:  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* {{{1

STARTING						*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 a
minimal 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 of
using "\" 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 in
single-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 DrawIt
will 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  :DIdbl

One may use these commands to start up Drawit in normal, single-bar, or
double-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-bar
modes.


USER MAP PROTECTION					*drawit-protect* {{{2

Starting DrawIt causes it to set up a number of maps which facilitate drawing.
DrawIt accommodates users with conflicting maps by saving both maps and user
options 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 were
before 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* {{{2

After DrawIt is started, use the number pad or arrow keys to move the cursor
about.  As the cursor moves, DrawIt will then leave appropriate "line"
characters behind as you move horizontally, vertically, or diagonally, and
will transparently enlarge your file to accommodate your drawing as needed.
The trail will consist of -, |, \, / characters (depending on which direction
and 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 editing
commands as you wish even while in DrawIt mode.

Another tool that may be used to convert Ascii-art into nice pictures is
available at https://github.com/christiangoltz/shaape .


CHANGING DRAWING CHARACTERS				*drawit-setdrawit* {{{2

The SetDrawIt() function is available for those who wish to change the
characters that DrawIt uses. >

    ex. :call SetDrawIt('*','*','*','*','*','*','*')
    ex. :call SetDrawIt('-','|','-','\','/','/','*')
<
The first example shows how to change all the DrawIt drawing characters to
asterisks, 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 interpreted
properly by Vim.  This problem impacts DrawIt as it uses those four
keys to signify diagonal moves/drawing.  One solution I use is to
put into my <.vimrc> file mapings like:

	map ^V... <home>

where the ellipsis (...) is the actual character sequence produced by
hitting the key.  The way to generate such maps is to type "map ",
followed by three control-v presses, press the associated key, then
a space followed by the proper interpretation sequence (ie. <home>).


MOVING					*drawit-move* *drawit-moving* {{{2

DrawIt supports shifting the arrow keys to cause motion of the cursor.  The
motion of the cursor will not modify what's below the cursor.  The cursor
will move and lines and/or spaces will be inserted to support the move as
required.  Your terminal may not support shifted arrow keys, however, or Vim
may 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 [DrawIt
erase] mode, a message "[DrawIt erase]" will appear and the number pad will
now cause spaces to be drawn instead of the usual drawing characters.  The
drawing behavior will be restored when the <space> key toggles DrawIt back
to regular DrawIt mode.


EXAMPLES						*drawit-example* {{{2

Needless to say, the square spirals which follow were done with DrawIt and
a 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 (by
permission) which provides DrawIt with visual-block selection of
starting/ending point drawing of arrows (\a), lines (\l), and boxes (\b).
Additionally I wrote an ellipse drawing function using visual block
specification (|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 will
query the user for the number of lines s/he wishes to have, and will then fill
those 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 figure
and want to fill it with some character.

The Sylvain Viart functions and the ellipse drawing function depend
upon 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 for
lines.  The internal s:AutoCanvas() will convert tabs to spaces and will
extend with spaces as needed to support the visual block.  Note that when
DrawIt 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