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