24. Editing Pictures

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 edit-picture to enter Picture mode.

In Picture mode, editing is based on the 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 C-c prefix to run special picture editing commands.

One of these keys, 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. M-x edit-picture records the name of the previous major mode. You can then use the C-c C-c command (picture-mode-exit) to restore that mode. 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 ‘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.

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

24.1 Basic Editing in Picture Mode

Most keys do the same thing in Picture mode that they usually do, but do it in a quarter-plane style. For example, C-f is rebound to run 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. C-b is rebound to run picture-backward-column, which always moves point left one column, converting a tab to multiple spaces if necessary. C-n and C-p are rebound to run picture-move-down and picture-move-up, which can either insert spaces or convert tabs as necessary to make sure that point stays in exactly the same column. C-e runs picture-end-of-line, which moves to after the last non-blank character on the line. There was no need to change C-a, as the choice of screen model does not affect beginnings of lines.

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

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

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

To actually delete parts of the picture, use C-w, or with C-c C-d (which is defined as delete-char, as C-d is in other modes), or with one of the picture rectangle commands (see section Picture Mode Rectangle Commands).

24.2 Controlling Motion After Insert

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.

C-c <

Move left after insertion (picture-movement-left).

C-c >

Move right after insertion (picture-movement-right).

C-c ^

Move up after insertion (picture-movement-up).

C-c .

Move down after insertion (picture-movement-down).

C-c `

Move up and left (“northwest”) after insertion
(picture-movement-nw).

C-c '

Move up and right (“northeast”) after insertion
(picture-movement-ne).

C-c /

Move down and left (“southwest”) after insertion
(picture-movement-sw).

C-c \

Move down and right (“southeast”) after insertion
(picture-movement-se).

Two motion commands move based on the current Picture insertion direction. The command C-c C-f (picture-motion) moves in the same direction as motion after “insertion” currently does, while C-c C-b (picture-motion-reverse) moves in the opposite direction.

24.3 Picture Mode Tabs

Two kinds of tab-like action are provided in Picture mode. Context-based tabbing is done with M-<TAB> (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 C-u M-<TAB>, the command moves to the next such interesting character in the current line. M-<TAB> does not change the text; it only moves point. “Interesting” characters are defined by the variable picture-tab-chars, which contains a string of characters considered interesting. Its default value is "!-~".

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

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

24.4 Picture Mode Rectangle Commands

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 (see section Rectangles).

C-c C-k

Clear out the region-rectangle (picture-clear-rectangle). With argument, kill it.

C-c C-w r

Similar but save rectangle contents in register r first (picture-clear-rectangle-to-register).

C-c C-y

Copy last killed rectangle into the buffer by overwriting, with upper left corner at point (picture-yank-rectangle). With argument, insert instead.

C-c C-x r

Similar, but use the rectangle in register r
(picture-yank-rectangle-from-register).

The picture rectangle commands C-c C-k (picture-clear-rectangle) and C-c C-w (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 C-d is changed in Picture mode.

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

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. C-c C-y (picture-yank-rectangle) inserts (by overwriting) the rectangle that was most recently killed, while C-c C-x (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.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.