Reformatted.

[chise/xemacs-chise.git] / man / xemacs / picture.texi

@node Picture, Sending Mail, Abbrevs, Top
@chapter Editing Pictures
@cindex pictures
@findex edit-picture

  If you want to create a picture made out of text characters (for example,
a picture of the division of a register into fields, as a comment in a
program), use the command @code{edit-picture} to enter Picture mode.

  In Picture mode, editing is based on the @dfn{quarter-plane} model of
text.  In this model, the text characters lie studded on an area that
stretches infinitely far to the right and downward.  The concept of the end
of a line does not exist in this model; the most you can say is where the
last non-blank character on the line is found.

  Of course, Emacs really always considers text as a sequence of
characters, and lines really do have ends.  But in Picture mode most
frequently-used keys are rebound to commands that simulate the
quarter-plane model of text.  They do this by inserting spaces or by
converting tabs to spaces.

  Most of the basic editing commands of Emacs are redefined by Picture mode
to do essentially the same thing but in a quarter-plane way.  In addition,
Picture mode defines various keys starting with the @kbd{C-c} prefix to
run special picture editing commands.

  One of these keys, @kbd{C-c C-c}, is pretty important.  Often a picture
is part of a larger file that is usually edited in some other major mode.
@kbd{M-x edit-picture} records the name of the previous major mode. 
You can then use the @kbd{C-c C-c} command (@code{picture-mode-exit}) to
restore that mode.  @kbd{C-c C-c} also deletes spaces from the ends of
lines, unless you give it a numeric argument.

  The commands used in Picture mode all work in other modes (provided the
@file{picture} library is loaded), but are only  bound to keys in
Picture mode.  Note that the descriptions below talk of moving ``one
column'' and so on, but all the picture mode commands handle numeric
arguments as their normal equivalents do.

@vindex picture-mode-hook
  Turning on Picture mode calls the value of the variable
@code{picture-mode-hook} as a function, with no arguments, if that value
exists and is non-@code{nil}.

@menu
* Basic Picture::         Basic concepts and simple commands of Picture Mode.
* Insert in Picture::     Controlling direction of cursor motion
                           after "self-inserting" characters.
* Tabs in Picture::       Various features for tab stops and indentation.
* Rectangles in Picture:: Clearing and superimposing rectangles.
@end menu

@node Basic Picture, Insert in Picture, Picture, Picture
@section Basic Editing in Picture Mode

@findex picture-forward-column
@findex picture-backward-column
@findex picture-move-down
@findex picture-move-up
  Most keys do the same thing in Picture mode that they usually do, but do
it in a quarter-plane style.  For example, @kbd{C-f} is rebound to run
@code{picture-forward-column}, which moves point one column to
the right, by inserting a space if necessary, so that the actual end of the
line makes no difference.  @kbd{C-b} is rebound to run
@code{picture-backward-column}, which always moves point left one column,
converting a tab to multiple spaces if necessary.  @kbd{C-n} and @kbd{C-p}
are rebound to run @code{picture-move-down} and @code{picture-move-up},
which can either insert spaces or convert tabs as necessary to make sure
that point stays in exactly the same column.  @kbd{C-e} runs
@code{picture-end-of-line}, which moves to after the last non-blank
character on the line.  There was no need to change @kbd{C-a}, as the choice
of screen model does not affect beginnings of lines.@refill

@findex picture-newline
  Insertion of text is adapted to the quarter-plane screen model through
the use of Overwrite mode (@pxref{Minor Modes}).  Self-inserting characters
replace existing text, column by column, rather than pushing existing text
to the right.  @key{RET} runs @code{picture-newline}, which just moves to
the beginning of the following line so that new text will replace that
line.

@findex picture-backward-clear-column
@findex picture-clear-column
@findex picture-clear-line
  Text is erased instead of deleted and killed.  @key{DEL}
(@code{picture-backward-clear-column}) replaces the preceding character
with a space rather than removing it.  @kbd{C-d}
(@code{picture-clear-column}) does the same in a forward direction.
@kbd{C-k} (@code{picture-clear-line}) really kills the contents of lines,
but never removes the newlines from a buffer.@refill

@findex picture-open-line
  To do actual insertion, you must use special commands.  @kbd{C-o}
(@code{picture-open-line}) creates a blank line, but does so after
the current line; it never splits a line.  @kbd{C-M-o}, @code{split-line},
makes sense in Picture mode, so it remains unchanged.  @key{LFD}
(@code{picture-duplicate-line}) inserts another line
with the same contents below the current line.@refill

@kindex C-c C-d (Picture mode)
@findex delete-char
 
  To actually delete parts of the picture, use @kbd{C-w}, or with
@kbd{C-c C-d} (which is defined as @code{delete-char}, as @kbd{C-d} is
in other modes), or with one of the picture rectangle commands
(@pxref{Rectangles in Picture}).

@node Insert in Picture, Tabs in Picture, Basic Picture, Picture
@section Controlling Motion After Insert

@findex picture-movement-up
@findex picture-movement-down
@findex picture-movement-left
@findex picture-movement-right
@findex picture-movement-nw
@findex picture-movement-ne
@findex picture-movement-sw
@findex picture-movement-se
@kindex C-c < (Picture mode)
@kindex C-c > (Picture mode)
@kindex C-c ^ (Picture mode)
@kindex C-c . (Picture mode)
@kindex C-c ` (Picture mode)
@kindex C-c ' (Picture mode)
@kindex C-c / (Picture mode)
@kindex C-c \ (Picture mode)
  Since ``self-inserting'' characters just overwrite and move point in
Picture mode, there is no essential restriction on how point should be
moved.  Normally point moves right, but you can specify any of the eight
orthogonal or diagonal directions for motion after a ``self-inserting''
character.  This is useful for drawing lines in the buffer.

@table @kbd
@item C-c <
Move left after insertion (@code{picture-movement-left}).
@item C-c >
Move right after insertion (@code{picture-movement-right}).
@item C-c ^
Move up after insertion (@code{picture-movement-up}).
@item C-c .
Move down after insertion (@code{picture-movement-down}).
@item C-c `
Move up and left (``northwest'') after insertion @*(@code{picture-movement-nw}).
@item C-c '
Move up and right (``northeast'') after insertion @*
(@code{picture-movement-ne}).
@item C-c /
Move down and left (``southwest'') after insertion
@*(@code{picture-movement-sw}).
@item C-c \
Move down and right (``southeast'') after insertion
@*(@code{picture-movement-se}).
@end table

@kindex C-c C-f (Picture mode)
@kindex C-c C-b (Picture mode)
@findex picture-motion
@findex picture-motion-reverse
  Two motion commands move based on the current Picture insertion
direction.  The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
same direction as motion after ``insertion'' currently does, while @kbd{C-c
C-b} (@code{picture-motion-reverse}) moves in the opposite direction.

@node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
@section Picture Mode Tabs
 
@kindex M-TAB
@findex picture-tab-search
@vindex picture-tab-chars
  Two kinds of tab-like action are provided in Picture mode.
Context-based tabbing is done with @kbd{M-@key{TAB}}
(@code{picture-tab-search}).  With no argument, it moves to a point
underneath the next ``interesting'' character that follows whitespace in
the previous non-blank line.  ``Next'' here means ``appearing at a
horizontal position greater than the one point starts out at''.  With an
argument, as in @kbd{C-u M-@key{TAB}}, the command moves to the next such
interesting character in the current line.  @kbd{M-@key{TAB}} does not
change the text; it only moves point.  ``Interesting'' characters are
defined by the variable @code{picture-tab-chars}, which contains a string
of characters considered interesting.  Its default value is
@code{"!-~"}.@refill

@findex picture-tab
  @key{TAB} itself runs @code{picture-tab}, which operates based on the
current tab stop settings; it is the Picture mode equivalent of
@code{tab-to-tab-stop}.  Without arguments it just moves point, but with
a numeric argument it clears the text that it moves over.

@kindex C-c TAB (Picture mode)
@findex picture-set-tab-stops
  The context-based and tab-stop-based forms of tabbing are brought
together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}.)
This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
would consider significant in the current line.  If you use this command
with @key{TAB}, you can get the effect of context-based tabbing.  But
@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.

@node Rectangles in Picture,, Tabs in Picture, Picture
@section Picture Mode Rectangle Commands
@cindex rectangle

  Picture mode defines commands for working on rectangular pieces of the
text in ways that fit with the quarter-plane model.  The standard rectangle
commands may also be useful (@pxref{Rectangles}).

@table @kbd
@item C-c C-k
Clear out the region-rectangle (@code{picture-clear-rectangle}).  With
argument, kill it.
@item C-c C-w @var{r}
Similar but save rectangle contents in register @var{r} first
(@code{picture-clear-rectangle-to-register}).
@item C-c C-y
Copy last killed rectangle into the buffer by overwriting, with upper
left corner at point (@code{picture-yank-rectangle}).  With argument,
insert instead.
@item C-c C-x @var{r}
Similar, but use the rectangle in register @var{r}@*
(@code{picture-yank-rectangle-from-register}).
@end table

@kindex C-c C-k (Picture mode)
@kindex C-c C-w (Picture mode)
@findex picture-clear-rectangle
@findex picture-clear-rectangle-to-register
  The picture rectangle commands @kbd{C-c C-k}
(@code{picture-clear-rectangle}) and @kbd{C-c C-w}
(@code{picture-clear-rectangle-to-register}) differ from the standard
rectangle commands in that they normally clear the rectangle instead of
deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
mode.@refill

  However, deletion of rectangles can be useful in Picture mode, so these
commands delete the rectangle if given a numeric argument.

@kindex C-c C-y (Picture mode)
@kindex C-c C-x (Picture mode)
@findex picture-yank-rectangle
@findex picture-yank-rectangle-from-register
  The Picture mode commands for yanking rectangles differ from the standard
ones in overwriting instead of inserting.  This is the same way that
Picture mode insertion of other text is different from other modes.
@kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting) the
rectangle that was most recently killed, while @kbd{C-c C-x}
(@code{picture-yank-rectangle-from-register}) does for the
rectangle found in a specified register.

Since most region commands in Picture mode operate on rectangles, when you
select a region of text with the mouse in Picture mode, it is highlighted
as a rectangle.