Reformatted.
[chise/xemacs-chise.git] / man / xemacs / picture.texi
1
2 @node Picture, Sending Mail, Abbrevs, Top
3 @chapter Editing Pictures
4 @cindex pictures
5 @findex edit-picture
6
7   If you want to create a picture made out of text characters (for example,
8 a picture of the division of a register into fields, as a comment in a
9 program), use the command @code{edit-picture} to enter Picture mode.
10
11   In Picture mode, editing is based on the @dfn{quarter-plane} model of
12 text.  In this model, the text characters lie studded on an area that
13 stretches infinitely far to the right and downward.  The concept of the end
14 of a line does not exist in this model; the most you can say is where the
15 last non-blank character on the line is found.
16
17   Of course, Emacs really always considers text as a sequence of
18 characters, and lines really do have ends.  But in Picture mode most
19 frequently-used keys are rebound to commands that simulate the
20 quarter-plane model of text.  They do this by inserting spaces or by
21 converting tabs to spaces.
22
23   Most of the basic editing commands of Emacs are redefined by Picture mode
24 to do essentially the same thing but in a quarter-plane way.  In addition,
25 Picture mode defines various keys starting with the @kbd{C-c} prefix to
26 run special picture editing commands.
27
28   One of these keys, @kbd{C-c C-c}, is pretty important.  Often a picture
29 is part of a larger file that is usually edited in some other major mode.
30 @kbd{M-x edit-picture} records the name of the previous major mode. 
31 You can then use the @kbd{C-c C-c} command (@code{picture-mode-exit}) to
32 restore that mode.  @kbd{C-c C-c} also deletes spaces from the ends of
33 lines, unless you give it a numeric argument.
34
35   The commands used in Picture mode all work in other modes (provided the
36 @file{picture} library is loaded), but are only  bound to keys in
37 Picture mode.  Note that the descriptions below talk of moving ``one
38 column'' and so on, but all the picture mode commands handle numeric
39 arguments as their normal equivalents do.
40
41 @vindex picture-mode-hook
42   Turning on Picture mode calls the value of the variable
43 @code{picture-mode-hook} as a function, with no arguments, if that value
44 exists and is non-@code{nil}.
45
46 @menu
47 * Basic Picture::         Basic concepts and simple commands of Picture Mode.
48 * Insert in Picture::     Controlling direction of cursor motion
49                            after "self-inserting" characters.
50 * Tabs in Picture::       Various features for tab stops and indentation.
51 * Rectangles in Picture:: Clearing and superimposing rectangles.
52 @end menu
53
54 @node Basic Picture, Insert in Picture, Picture, Picture
55 @section Basic Editing in Picture Mode
56
57 @findex picture-forward-column
58 @findex picture-backward-column
59 @findex picture-move-down
60 @findex picture-move-up
61   Most keys do the same thing in Picture mode that they usually do, but do
62 it in a quarter-plane style.  For example, @kbd{C-f} is rebound to run
63 @code{picture-forward-column}, which moves point one column to
64 the right, by inserting a space if necessary, so that the actual end of the
65 line makes no difference.  @kbd{C-b} is rebound to run
66 @code{picture-backward-column}, which always moves point left one column,
67 converting a tab to multiple spaces if necessary.  @kbd{C-n} and @kbd{C-p}
68 are rebound to run @code{picture-move-down} and @code{picture-move-up},
69 which can either insert spaces or convert tabs as necessary to make sure
70 that point stays in exactly the same column.  @kbd{C-e} runs
71 @code{picture-end-of-line}, which moves to after the last non-blank
72 character on the line.  There was no need to change @kbd{C-a}, as the choice
73 of screen model does not affect beginnings of lines.@refill
74
75 @findex picture-newline
76   Insertion of text is adapted to the quarter-plane screen model through
77 the use of Overwrite mode (@pxref{Minor Modes}).  Self-inserting characters
78 replace existing text, column by column, rather than pushing existing text
79 to the right.  @key{RET} runs @code{picture-newline}, which just moves to
80 the beginning of the following line so that new text will replace that
81 line.
82
83 @findex picture-backward-clear-column
84 @findex picture-clear-column
85 @findex picture-clear-line
86   Text is erased instead of deleted and killed.  @key{DEL}
87 (@code{picture-backward-clear-column}) replaces the preceding character
88 with a space rather than removing it.  @kbd{C-d}
89 (@code{picture-clear-column}) does the same in a forward direction.
90 @kbd{C-k} (@code{picture-clear-line}) really kills the contents of lines,
91 but never removes the newlines from a buffer.@refill
92
93 @findex picture-open-line
94   To do actual insertion, you must use special commands.  @kbd{C-o}
95 (@code{picture-open-line}) creates a blank line, but does so after
96 the current line; it never splits a line.  @kbd{C-M-o}, @code{split-line},
97 makes sense in Picture mode, so it remains unchanged.  @key{LFD}
98 (@code{picture-duplicate-line}) inserts another line
99 with the same contents below the current line.@refill
100
101 @kindex C-c C-d (Picture mode)
102 @findex delete-char
103  
104   To actually delete parts of the picture, use @kbd{C-w}, or with
105 @kbd{C-c C-d} (which is defined as @code{delete-char}, as @kbd{C-d} is
106 in other modes), or with one of the picture rectangle commands
107 (@pxref{Rectangles in Picture}).
108
109 @node Insert in Picture, Tabs in Picture, Basic Picture, Picture
110 @section Controlling Motion After Insert
111
112 @findex picture-movement-up
113 @findex picture-movement-down
114 @findex picture-movement-left
115 @findex picture-movement-right
116 @findex picture-movement-nw
117 @findex picture-movement-ne
118 @findex picture-movement-sw
119 @findex picture-movement-se
120 @kindex C-c < (Picture mode)
121 @kindex C-c > (Picture mode)
122 @kindex C-c ^ (Picture mode)
123 @kindex C-c . (Picture mode)
124 @kindex C-c ` (Picture mode)
125 @kindex C-c ' (Picture mode)
126 @kindex C-c / (Picture mode)
127 @kindex C-c \ (Picture mode)
128   Since ``self-inserting'' characters just overwrite and move point in
129 Picture mode, there is no essential restriction on how point should be
130 moved.  Normally point moves right, but you can specify any of the eight
131 orthogonal or diagonal directions for motion after a ``self-inserting''
132 character.  This is useful for drawing lines in the buffer.
133
134 @table @kbd
135 @item C-c <
136 Move left after insertion (@code{picture-movement-left}).
137 @item C-c >
138 Move right after insertion (@code{picture-movement-right}).
139 @item C-c ^
140 Move up after insertion (@code{picture-movement-up}).
141 @item C-c .
142 Move down after insertion (@code{picture-movement-down}).
143 @item C-c `
144 Move up and left (``northwest'') after insertion @*(@code{picture-movement-nw}).
145 @item C-c '
146 Move up and right (``northeast'') after insertion @*
147 (@code{picture-movement-ne}).
148 @item C-c /
149 Move down and left (``southwest'') after insertion
150 @*(@code{picture-movement-sw}).
151 @item C-c \
152 Move down and right (``southeast'') after insertion
153 @*(@code{picture-movement-se}).
154 @end table
155
156 @kindex C-c C-f (Picture mode)
157 @kindex C-c C-b (Picture mode)
158 @findex picture-motion
159 @findex picture-motion-reverse
160   Two motion commands move based on the current Picture insertion
161 direction.  The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
162 same direction as motion after ``insertion'' currently does, while @kbd{C-c
163 C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
164
165 @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
166 @section Picture Mode Tabs
167  
168 @kindex M-TAB
169 @findex picture-tab-search
170 @vindex picture-tab-chars
171   Two kinds of tab-like action are provided in Picture mode.
172 Context-based tabbing is done with @kbd{M-@key{TAB}}
173 (@code{picture-tab-search}).  With no argument, it moves to a point
174 underneath the next ``interesting'' character that follows whitespace in
175 the previous non-blank line.  ``Next'' here means ``appearing at a
176 horizontal position greater than the one point starts out at''.  With an
177 argument, as in @kbd{C-u M-@key{TAB}}, the command moves to the next such
178 interesting character in the current line.  @kbd{M-@key{TAB}} does not
179 change the text; it only moves point.  ``Interesting'' characters are
180 defined by the variable @code{picture-tab-chars}, which contains a string
181 of characters considered interesting.  Its default value is
182 @code{"!-~"}.@refill
183
184 @findex picture-tab
185   @key{TAB} itself runs @code{picture-tab}, which operates based on the
186 current tab stop settings; it is the Picture mode equivalent of
187 @code{tab-to-tab-stop}.  Without arguments it just moves point, but with
188 a numeric argument it clears the text that it moves over.
189
190 @kindex C-c TAB (Picture mode)
191 @findex picture-set-tab-stops
192   The context-based and tab-stop-based forms of tabbing are brought
193 together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}.)
194 This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
195 would consider significant in the current line.  If you use this command
196 with @key{TAB}, you can get the effect of context-based tabbing.  But
197 @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
198
199 @node Rectangles in Picture,, Tabs in Picture, Picture
200 @section Picture Mode Rectangle Commands
201 @cindex rectangle
202
203   Picture mode defines commands for working on rectangular pieces of the
204 text in ways that fit with the quarter-plane model.  The standard rectangle
205 commands may also be useful (@pxref{Rectangles}).
206
207 @table @kbd
208 @item C-c C-k
209 Clear out the region-rectangle (@code{picture-clear-rectangle}).  With
210 argument, kill it.
211 @item C-c C-w @var{r}
212 Similar but save rectangle contents in register @var{r} first
213 (@code{picture-clear-rectangle-to-register}).
214 @item C-c C-y
215 Copy last killed rectangle into the buffer by overwriting, with upper
216 left corner at point (@code{picture-yank-rectangle}).  With argument,
217 insert instead.
218 @item C-c C-x @var{r}
219 Similar, but use the rectangle in register @var{r}@*
220 (@code{picture-yank-rectangle-from-register}).
221 @end table
222
223 @kindex C-c C-k (Picture mode)
224 @kindex C-c C-w (Picture mode)
225 @findex picture-clear-rectangle
226 @findex picture-clear-rectangle-to-register
227   The picture rectangle commands @kbd{C-c C-k}
228 (@code{picture-clear-rectangle}) and @kbd{C-c C-w}
229 (@code{picture-clear-rectangle-to-register}) differ from the standard
230 rectangle commands in that they normally clear the rectangle instead of
231 deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
232 mode.@refill
233
234   However, deletion of rectangles can be useful in Picture mode, so these
235 commands delete the rectangle if given a numeric argument.
236
237 @kindex C-c C-y (Picture mode)
238 @kindex C-c C-x (Picture mode)
239 @findex picture-yank-rectangle
240 @findex picture-yank-rectangle-from-register
241   The Picture mode commands for yanking rectangles differ from the standard
242 ones in overwriting instead of inserting.  This is the same way that
243 Picture mode insertion of other text is different from other modes.
244 @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting) the
245 rectangle that was most recently killed, while @kbd{C-c C-x}
246 (@code{picture-yank-rectangle-from-register}) does for the
247 rectangle found in a specified register.
248
249 Since most region commands in Picture mode operate on rectangles, when you
250 select a region of text with the mouse in Picture mode, it is highlighted
251 as a rectangle.