Commit | Line | Data |
---|---|---|
6f585e44 | 1 | @c This is part of the Emacs manual. |
ba318903 | 2 | @c Copyright (C) 2004-2014 Free Software Foundation, Inc. |
6f585e44 EZ |
3 | @c See file emacs.texi for copying conditions. |
4 | @c | |
c5184807 EZ |
5 | @c This file is included either in emacs-xtra.texi (when producing the |
6 | @c printed version) or in the main Emacs manual (for the on-line version). | |
7 | @node Picture Mode | |
f404f8bc | 8 | @section Editing Pictures |
c5184807 EZ |
9 | @cindex pictures |
10 | @cindex making pictures out of text characters | |
a2baab5c | 11 | @findex picture-mode |
c5184807 EZ |
12 | |
13 | To edit a picture made out of text characters (for example, a picture | |
14 | of the division of a register into fields, as a comment in a program), | |
a2baab5c | 15 | use the command @kbd{M-x picture-mode} to enter Picture mode. |
c5184807 EZ |
16 | |
17 | In Picture mode, editing is based on the @dfn{quarter-plane} model of | |
18 | text, according to which the text characters lie studded on an area that | |
19 | stretches infinitely far to the right and downward. The concept of the end | |
20 | of a line does not exist in this model; the most you can say is where the | |
21 | last nonblank character on the line is found. | |
22 | ||
23 | Of course, Emacs really always considers text as a sequence of | |
24 | characters, and lines really do have ends. But Picture mode replaces | |
25 | the most frequently-used commands with variants that simulate the | |
26 | quarter-plane model of text. They do this by inserting spaces or by | |
27 | converting tabs to spaces. | |
28 | ||
29 | Most of the basic editing commands of Emacs are redefined by Picture mode | |
30 | to do essentially the same thing but in a quarter-plane way. In addition, | |
31 | Picture mode defines various keys starting with the @kbd{C-c} prefix to | |
32 | run special picture editing commands. | |
33 | ||
a2baab5c CY |
34 | One of these keys, @kbd{C-c C-c}, is particularly important. Often |
35 | a picture is part of a larger file that is usually edited in some | |
36 | other major mode. Picture mode records the name of the previous major | |
37 | mode so you can use the @kbd{C-c C-c} command | |
38 | (@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c | |
39 | C-c} also deletes spaces from the ends of lines, unless given a | |
40 | numeric argument. | |
c5184807 EZ |
41 | |
42 | The special commands of Picture mode all work in other modes (provided | |
43 | the @file{picture} library is loaded), but are not bound to keys except | |
44 | in Picture mode. The descriptions below talk of moving ``one column'' | |
45 | and so on, but all the picture mode commands handle numeric arguments as | |
46 | their normal equivalents do. | |
47 | ||
48 | @vindex picture-mode-hook | |
49 | Turning on Picture mode runs the hook @code{picture-mode-hook}. | |
50 | Additional extensions to Picture mode can be found in | |
51 | @file{artist.el}. | |
52 | ||
53 | @menu | |
54 | * Basic Picture:: Basic concepts and simple commands of Picture Mode. | |
55 | * Insert in Picture:: Controlling direction of cursor motion | |
56 | after "self-inserting" characters. | |
57 | * Tabs in Picture:: Various features for tab stops and indentation. | |
58 | * Rectangles in Picture:: Clearing and superimposing rectangles. | |
59 | @end menu | |
60 | ||
61 | @node Basic Picture | |
f404f8bc | 62 | @subsection Basic Editing in Picture Mode |
c5184807 EZ |
63 | |
64 | @findex picture-forward-column | |
65 | @findex picture-backward-column | |
66 | @findex picture-move-down | |
67 | @findex picture-move-up | |
68 | @cindex editing in Picture mode | |
69 | ||
70 | Most keys do the same thing in Picture mode that they usually do, but | |
71 | do it in a quarter-plane style. For example, @kbd{C-f} is rebound to | |
72 | run @code{picture-forward-column}, a command which moves point one | |
73 | column to the right, inserting a space if necessary so that the actual | |
74 | end of the line makes no difference. @kbd{C-b} is rebound to run | |
75 | @code{picture-backward-column}, which always moves point left one | |
76 | column, converting a tab to multiple spaces if necessary. @kbd{C-n} and | |
77 | @kbd{C-p} are rebound to run @code{picture-move-down} and | |
78 | @code{picture-move-up}, which can either insert spaces or convert tabs | |
79 | as necessary to make sure that point stays in exactly the same column. | |
80 | @kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last | |
f9a998c3 GM |
81 | nonblank character on the line. @kbd{C-a} runs |
82 | @code{picture-beginning-of-line}. (The choice of screen model does not | |
83 | affect beginnings of lines; the only extra thing this command does is | |
84 | update the current picture column to 0.) | |
c5184807 EZ |
85 | |
86 | @findex picture-newline | |
87 | Insertion of text is adapted to the quarter-plane screen model | |
32f864b1 EZ |
88 | through the use of Overwrite mode |
89 | @iftex | |
90 | (@pxref{Minor Modes,,, emacs, the Emacs Manual}.) | |
91 | @end iftex | |
92 | @ifnottex | |
93 | (@pxref{Minor Modes}.) | |
94 | @end ifnottex | |
95 | Self-inserting characters replace existing text, column by column, | |
96 | rather than pushing existing text to the right. @key{RET} runs | |
97 | @code{picture-newline}, which just moves to the beginning of the | |
98 | following line so that new text will replace that line. | |
c5184807 EZ |
99 | |
100 | @findex picture-backward-clear-column | |
101 | @findex picture-clear-column | |
102 | @findex picture-clear-line | |
103 | In Picture mode, the commands that normally delete or kill text, | |
104 | instead erase text (replacing it with spaces). @key{DEL} | |
105 | (@code{picture-backward-clear-column}) replaces the preceding | |
106 | character with a space rather than removing it; this moves point | |
107 | backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next | |
108 | character or characters with spaces, but does not move point. (If you | |
109 | want to clear characters to spaces and move forward over them, use | |
110 | @key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the | |
111 | contents of lines, but does not delete the newlines from the buffer. | |
112 | ||
113 | @findex picture-open-line | |
114 | To do actual insertion, you must use special commands. @kbd{C-o} | |
115 | (@code{picture-open-line}) creates a blank line after the current | |
116 | line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes | |
117 | sense in Picture mode, so it is not changed. @kbd{C-j} | |
118 | (@code{picture-duplicate-line}) inserts another line with the same | |
119 | contents below the current line. | |
120 | ||
121 | @kindex C-c C-d @r{(Picture mode)} | |
122 | To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} | |
123 | (which is defined as @code{delete-char}, as @kbd{C-d} is in other | |
124 | modes), or one of the picture rectangle commands (@pxref{Rectangles in | |
125 | Picture}). | |
126 | ||
127 | @node Insert in Picture | |
f404f8bc | 128 | @subsection Controlling Motion after Insert |
c5184807 EZ |
129 | |
130 | @findex picture-movement-up | |
131 | @findex picture-movement-down | |
132 | @findex picture-movement-left | |
133 | @findex picture-movement-right | |
134 | @findex picture-movement-nw | |
135 | @findex picture-movement-ne | |
136 | @findex picture-movement-sw | |
137 | @findex picture-movement-se | |
138 | @kindex C-c < @r{(Picture mode)} | |
139 | @kindex C-c > @r{(Picture mode)} | |
140 | @kindex C-c ^ @r{(Picture mode)} | |
141 | @kindex C-c . @r{(Picture mode)} | |
142 | @kindex C-c ` @r{(Picture mode)} | |
143 | @kindex C-c ' @r{(Picture mode)} | |
144 | @kindex C-c / @r{(Picture mode)} | |
145 | @kindex C-c \ @r{(Picture mode)} | |
146 | Since ``self-inserting'' characters in Picture mode overwrite and move | |
147 | point, there is no essential restriction on how point should be moved. | |
148 | Normally point moves right, but you can specify any of the eight | |
149 | orthogonal or diagonal directions for motion after a ``self-inserting'' | |
150 | character. This is useful for drawing lines in the buffer. | |
151 | ||
152 | @table @kbd | |
153 | @item C-c < | |
119bf2f4 | 154 | @itemx C-c @key{LEFT} |
c5184807 EZ |
155 | Move left after insertion (@code{picture-movement-left}). |
156 | @item C-c > | |
119bf2f4 | 157 | @itemx C-c @key{RIGHT} |
c5184807 EZ |
158 | Move right after insertion (@code{picture-movement-right}). |
159 | @item C-c ^ | |
119bf2f4 | 160 | @itemx C-c @key{UP} |
c5184807 EZ |
161 | Move up after insertion (@code{picture-movement-up}). |
162 | @item C-c . | |
119bf2f4 | 163 | @itemx C-c @key{DOWN} |
c5184807 EZ |
164 | Move down after insertion (@code{picture-movement-down}). |
165 | @item C-c ` | |
d7e9a7f8 | 166 | @itemx C-c @key{Home} |
c5184807 EZ |
167 | Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). |
168 | @item C-c ' | |
b5700de6 | 169 | @itemx C-c @key{prior} |
c5184807 EZ |
170 | Move up and right (``northeast'') after insertion |
171 | (@code{picture-movement-ne}). | |
172 | @item C-c / | |
d7e9a7f8 | 173 | @itemx C-c @key{End} |
c5184807 EZ |
174 | Move down and left (``southwest'') after insertion |
175 | @*(@code{picture-movement-sw}). | |
176 | @item C-c \ | |
b5700de6 | 177 | @itemx C-c @key{next} |
c5184807 EZ |
178 | Move down and right (``southeast'') after insertion |
179 | @*(@code{picture-movement-se}). | |
180 | @end table | |
181 | ||
182 | @kindex C-c C-f @r{(Picture mode)} | |
183 | @kindex C-c C-b @r{(Picture mode)} | |
184 | @findex picture-motion | |
185 | @findex picture-motion-reverse | |
186 | Two motion commands move based on the current Picture insertion | |
187 | direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the | |
188 | same direction as motion after ``insertion'' currently does, while @kbd{C-c | |
189 | C-b} (@code{picture-motion-reverse}) moves in the opposite direction. | |
190 | ||
191 | @node Tabs in Picture | |
f404f8bc | 192 | @subsection Picture Mode Tabs |
c5184807 EZ |
193 | |
194 | @kindex M-TAB @r{(Picture mode)} | |
195 | @findex picture-tab-search | |
196 | @vindex picture-tab-chars | |
197 | Two kinds of tab-like action are provided in Picture mode. Use | |
198 | @kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. | |
199 | With no argument, it moves to a point underneath the next | |
200 | ``interesting'' character that follows whitespace in the previous | |
201 | nonblank line. ``Next'' here means ``appearing at a horizontal position | |
16152b76 | 202 | greater than the one point starts out at''. With an argument, as in |
c5184807 EZ |
203 | @kbd{C-u M-@key{TAB}}, this command moves to the next such interesting |
204 | character in the current line. @kbd{M-@key{TAB}} does not change the | |
205 | text; it only moves point. ``Interesting'' characters are defined by | |
206 | the variable @code{picture-tab-chars}, which should define a set of | |
207 | characters. The syntax for this variable is like the syntax used inside | |
208 | of @samp{[@dots{}]} in a regular expression---but without the @samp{[} | |
209 | and the @samp{]}. Its default value is @code{"!-~"}. | |
210 | ||
211 | @findex picture-tab | |
212 | @key{TAB} itself runs @code{picture-tab}, which operates based on the | |
213 | current tab stop settings; it is the Picture mode equivalent of | |
214 | @code{tab-to-tab-stop}. Normally it just moves point, but with a numeric | |
215 | argument it clears the text that it moves over. | |
216 | ||
217 | @kindex C-c TAB @r{(Picture mode)} | |
218 | @findex picture-set-tab-stops | |
219 | The context-based and tab-stop-based forms of tabbing are brought | |
220 | together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). | |
221 | This command sets the tab stops to the positions which @kbd{M-@key{TAB}} | |
222 | would consider significant in the current line. The use of this command, | |
223 | together with @key{TAB}, can get the effect of context-based tabbing. But | |
224 | @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. | |
225 | ||
226 | It may be convenient to prevent use of actual tab characters in | |
227 | pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing | |
228 | up the picture. You can do this by setting the variable | |
229 | @code{indent-tabs-mode} to @code{nil}. | |
230 | ||
231 | @node Rectangles in Picture | |
f404f8bc | 232 | @subsection Picture Mode Rectangle Commands |
c5184807 EZ |
233 | @cindex rectangles and Picture mode |
234 | @cindex Picture mode and rectangles | |
235 | ||
236 | Picture mode defines commands for working on rectangular pieces of | |
237 | the text in ways that fit with the quarter-plane model. The standard | |
32f864b1 EZ |
238 | rectangle commands may also be useful. |
239 | @iftex | |
240 | @xref{Rectangles,,, emacs, the Emacs Manual}. | |
241 | @end iftex | |
242 | @ifnottex | |
243 | @xref{Rectangles}. | |
244 | @end ifnottex | |
c5184807 EZ |
245 | |
246 | @table @kbd | |
247 | @item C-c C-k | |
248 | Clear out the region-rectangle with spaces | |
2904fd97 LMI |
249 | (@code{picture-clear-rectangle}). With a prefix argument, delete the |
250 | text. | |
c5184807 EZ |
251 | @item C-c C-w @var{r} |
252 | Similar, but save rectangle contents in register @var{r} first | |
253 | (@code{picture-clear-rectangle-to-register}). | |
254 | @item C-c C-y | |
255 | Copy last killed rectangle into the buffer by overwriting, with upper | |
256 | left corner at point (@code{picture-yank-rectangle}). With argument, | |
257 | insert instead. | |
258 | @item C-c C-x @var{r} | |
259 | Similar, but use the rectangle in register @var{r} | |
260 | (@code{picture-yank-rectangle-from-register}). | |
261 | @end table | |
262 | ||
263 | @kindex C-c C-k @r{(Picture mode)} | |
264 | @kindex C-c C-w @r{(Picture mode)} | |
265 | @findex picture-clear-rectangle | |
266 | @findex picture-clear-rectangle-to-register | |
267 | The picture rectangle commands @kbd{C-c C-k} | |
268 | (@code{picture-clear-rectangle}) and @kbd{C-c C-w} | |
269 | (@code{picture-clear-rectangle-to-register}) differ from the standard | |
270 | rectangle commands in that they normally clear the rectangle instead of | |
271 | deleting it; this is analogous with the way @kbd{C-d} is changed in Picture | |
272 | mode. | |
273 | ||
274 | However, deletion of rectangles can be useful in Picture mode, so | |
275 | these commands delete the rectangle if given a numeric argument. | |
276 | @kbd{C-c C-k} either with or without a numeric argument saves the | |
277 | rectangle for @kbd{C-c C-y}. | |
278 | ||
279 | @kindex C-c C-y @r{(Picture mode)} | |
280 | @kindex C-c C-x @r{(Picture mode)} | |
281 | @findex picture-yank-rectangle | |
282 | @findex picture-yank-rectangle-from-register | |
283 | The Picture mode commands for yanking rectangles differ from the | |
284 | standard ones in that they overwrite instead of inserting. This is | |
285 | the same way that Picture mode insertion of other text differs from | |
286 | other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts | |
287 | (by overwriting) the rectangle that was most recently killed, while | |
288 | @kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does | |
289 | likewise for the rectangle found in a specified register. |