InfoMagic Source Code 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / elisp / elisp-21 < prev next >

Wrap

GNU Info File | 1993-05-31 | 47.7 KB | 1,237 lines

This is Info file elisp, produced by Makeinfo-1.55 from the input file elisp.texi. This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for Emacs Version 19. Published by the Free Software Foundation, 675 Massachusetts Avenue, Cambridge, MA 02139 USA Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: elisp, Node: X Frame Parameters, Next: Size And Position, Prev: Initial Parameters, Up: Frame Parameters X Window Frame Parameters ------------------------- Just what parameters a frame has depends on what display mechanism it uses. Here is a table of the parameters of an X window frame: `name' The name of the frame. `left' The screen position of the left edge, in pixels. `top' The screen position of the top edge, in pixels. `height' The height of the frame contents, in pixels. `width' The width of the frame contents, in pixels. `window-id' The number of the X window for the frame. `minibuffer' Whether this frame has its own minibuffer. The value `t' means yes, `nil' means no, `only' means this frame is just a minibuffer, a minibuffer window (in some other frame) means the new frame uses that minibuffer. `font' The name of the font for text in the frame. This is a string. `auto-raise' Whether selecting the frame raises it (non-`nil' means yes). `auto-lower' Whether deselecting the frame lowers it (non-`nil' means yes). `vertical-scroll-bars' Whether the frame has a scroll bar for vertical scrolling (non-`nil' means yes). `horizontal-scroll-bars' Whether the frame has a scroll bar for horizontal scrolling (non-`nil' means yes). (Horizontal scroll bars are not currently implemented.) `icon-type' The type of icon to use for this frame when it is iconified. Non-`nil' specifies a bitmap icon, `nil' a text icon. `foreground-color' The color to use for the inside of a character. We use strings to designate colors; the X server defines the meaningful color names. `background-color' The color to use for the background of text. `mouse-color' The color for the mouse cursor. `cursor-color' The color for the cursor that shows point. `border-color' The color for the border of the frame. `cursor-type' The way to display the cursor. There are two legitimate values: `bar' and `box'. The value `bar' specifies a vertical bar between characters as the cursor. The value `box' specifies an ordinary black box overlaying the character after point; that is the default. `border-width' The width in pixels of the window border. `internal-border-width' The distance in pixels between text and border. `unsplittable' If non-`nil', this frame's window is never split automatically. `visibility' The state of visibility of the frame. There are three possibilities: `nil' for invisible, `t' for visible, and `icon' for iconified. *Note Visibility of Frames::. `menu-bar-lines' The number of lines to allocate at the top of the frame for a menu bar. The default is zero. *Note Menu Bar::. `parent-id' The X Window number of the window that should be the parent of this one. Specifying this lets you create an Emacs window inside some other application's window. (It is not certain this will be implemented; try it and see if it works.) File: elisp, Node: Size And Position, Prev: X Frame Parameters, Up: Frame Parameters Frame Size And Position ----------------------- You can read or change the size and position of a frame using the frame parameters `left', `top', `height' and `width'. When you create a frame, you must specify either both size parameters or neither. Likewise, you must specify either both position parameters or neither. Whatever geometry parameters you don't specify are chosen by the window manager in its usual fashion. Here are some special features for working with sizes and positions: - Function: set-frame-position FRAME LEFT TOP This function sets the position of the top left corner of FRAME--to LEFT and TOP. These arguments are measured in pixels, counting from the top left corner of the screen. - Function: frame-height &optional FRAME - Function: frame-width &optional FRAME These functions return the height and width of FRAME, measured in characters. If you don't supply FRAME, they use the selected frame. - Function: frame-pixel-height &optional FRAME - Function: frame-pixel-width &optional FRAME These functions return the height and width of FRAME, measured in pixels. If you don't supply FRAME, they use the selected frame. - Function: frame-char-height &optional FRAME - Function: frame-char-width &optional FRAME These functions return the height and width, respectively, of a character in FRAME, measured in pixels. The values depend on the choice of font. If you don't supply FRAME, these functions use the selected frame. - Function: set-frame-size FRAME COLS ROWS This function sets the size of FRAME, measured in characters; COLS and ROWS specify the new width and height. To set the size with values measured in pixels, use `modify-frame-parameters' to set the `width' and `height' parameters. *Note X Frame Parameters::. The old-fashioned functions `set-screen-height' and `set-screen-width', which were used to specify the height and width of the screen in Emacs versions that did not support multiple frames, are still usable. They apply to the selected frame. *Note Screen Size::. - Function: x-parse-geometry GEOM The function `x-parse-geometry' converts a standard X windows geometry string to an alist which you can use as part of the argument to `x-create-frame'. The alist describes which parameters were specified in GEOM, and gives the values specified for them. Each element looks like `(PARAMETER . VALUE)'. The possible PARAMETER values are `left', `top', `width', and `height'. (x-geometry "35x70+0-0") => ((width . 35) (height . 70) (left . 0) (top . -1)) File: elisp, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Parameters, Up: Frames Deleting Frames =============== Frames remain potentially visible until you explicitly "delete" them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a frame aside from restoring a saved frame configuration (*note Frame Configurations::.); this is similar to the way windows behave. - Command: delete-frame &optional FRAME This function deletes the frame FRAME. By default, FRAME is the selected frame. - Function: frame-live-p FRAME The function `frame-live-p' returns non-`nil' if the frame FRAME has not been deleted. File: elisp, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames Finding All Frames ================== - Function: frame-list The function `frame-list' returns a list of all the frames that have not been deleted. It is analogous to `buffer-list' for buffers. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of Emacs. - Function: visible-frame-list This function returns a list of just the currently visible frames. - Function: next-frame &optional FRAME MINIBUF The function `next-frame' lets you cycle conveniently through all the frames from an arbitrary starting point. It returns the "next" frame after FRAME in the cycle. If FRAME is omitted or `nil', it defaults to the selected frame. The second argument, MINIBUF, says which frames to consider: `nil' Exclude minibuffer-only frames. a window Consider only the frames using that particular window as their minibuffer. anything else Consider all frames. File: elisp, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames Frames and Windows ================== All the non-minibuffer windows in a frame are arranged in a tree of subdivisions; the root of this tree is available via the function `frame-root-window'. Each window is part of one and only one frame; you can get the frame with `window-frame'. - Function: frame-root-window FRAME This returns the root window of frame FRAME. - Function: window-frame WINDOW This function returns the frame that WINDOW is on. At any time, exactly one window on any frame is "selected within the frame". The significance of this designation is that selecting the frame also selects this window. You can get the frame's current selected window with `frame-selected-window'. - Function: frame-selected-window FRAME This function returns the window on FRAME which is selected within FRAME. Conversely, selecting a window for Emacs with `select-window' also makes that window selected within its frame. *Note Selecting Windows::. File: elisp, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames Minibuffers and Frames ====================== Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. If the frame has a minibuffer, you can get it with `minibuffer-window' (*note Minibuffer Misc::.). However, you can also create a frame with no minibuffer. Such a frame must use the minibuffer window of some other frame. When you create the frame, you can specify explicitly the frame on which to find the minibuffer to use. If you don't, then the minibuffer is found in the frame which is the value of the variable `default-minibuffer-frame'. Its value should be a frame which does have a minibuffer. File: elisp, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames Input Focus =========== At any time, one frame in Emacs is the "selected frame". The selected window always resides on the selected frame. - Function: selected-frame This function returns the selected frame. The X server normally directs keyboard input to the X window that the mouse is in. Some window managers use mouse clicks or keyboard events to "shift the focus" to various X windows, overriding the normal behavior of the server. Lisp programs can switch frames "temporarily" by calling the function `select-frame'. This does not override the window manager; rather, it escapes from the window manager's control until that control is somehow reasserted. - Function: select-frame FRAME This function selects frame FRAME, temporarily disregarding the X Windows focus. The selection of FRAME lasts until the next time the user does something to select a different frame, or until the next time this function is called. Emacs cooperates with the X server and the window managers by arranging to select frames according to what the server and window manager ask for. It does so by generating a special kind of input event, called a "focus" event. The command loop handles a focus event by calling `internal-select-frame'. *Note Focus Events::. - Function: internal-select-frame FRAME This function selects frame FRAME, assuming that the X server focus already points to FRAME. Focus events normally do their job by invoking this command. Don't call it for any other reason. File: elisp, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames Visibility of Frames ==================== A frame may be "visible", "invisible", or "iconified". If it is visible, you can see its contents. If it is iconified, the frame's contents do not appear on the screen, but an icon does. If the frame is invisible, it doesn't show in the screen, not even as an icon. - Command: make-frame-visible &optional FRAME This function makes frame FRAME visible. If you omit FRAME, it makes the selected frame visible. - Command: make-frame-invisible &optional FRAME This function makes frame FRAME invisible. If you omit FRAME, it makes the selected frame invisible. - Command: iconify-frame &optional FRAME This function iconifies frame FRAME. If you omit FRAME, it iconifies the selected frame. - Function: frame-visible-p FRAME This returns the visibility status of frame FRAME. The value is `t' if FRAME is visible, `nil' if it is invisible, and `icon' if it is iconified. The visibility status of a frame is also available as a frame parameter. You can read or change it as such. *Note X Frame Parameters::. File: elisp, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames Raising and Lowering Frames =========================== The X window system uses a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from "highest" to "lowest". Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it. A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. "Raising" a window means moving it "up", to the top of the stack. "Lowering" a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen. You can raise and lower Emacs's X windows with these functions: - Function: raise-frame FRAME This function raises frame FRAME. - Function: lower-frame FRAME This function lowers frame FRAME. You can also specify auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected) for any frame using frame parameters. *Note X Frame Parameters::. File: elisp, Node: Frame Configurations, Next: Mouse Tracking, Prev: Raising and Lowering, Up: Frames Frame Configurations ==================== - Function: current-frame-configuration This function returns a "frame configuration" list which describes the current arrangement of frames, all their properties, and the window configuration of each one. - Function: set-frame-configuration CONFIGURATION This function restores the state of frames described in CONFIGURATION. File: elisp, Node: Mouse Tracking, Next: Mouse Position, Prev: Frame Configurations, Up: Frames Mouse Tracking ============== Sometimes it is useful to "track" the mouse, which means, to display something to indicate where the mouse is and move the indicator as the mouse moves. For efficient mouse tracking, you need a way to wait until the mouse actually moves. The convenient way to track the mouse is to ask for events to represent mouse motion. Then you can wait for motion by waiting for an event. In addition, you can easily handle any other sorts of events that may occur. That is useful, because normally you don't want to track the mouse forever--only until some other event, such as the release of a button. - Special Form: track-mouse BODY... Execute BODY, meanwhile generating input events for mouse motion. The code in BODY can read these events with `read-event' or `read-key-sequence'. *Note Motion Events::, for the format of mouse motion events. The value of `track-mouse' is that of the last form in BODY. The usual purpose of tracking mouse motion is to indicate on the screen the consequences of pushing or releasing a button at the current position. File: elisp, Node: Mouse Position, Next: Pop-Up Menus, Prev: Mouse Tracking, Up: Frames Mouse Position ============== The new functions `mouse-position' and `set-mouse-position' give access to the current position of the mouse. - Function: mouse-position This function returns a description of the position of the mouse. The value looks like `(FRAME X . Y)', where X and Y are integers giving the position in pixels relative to the top left corner of the inside of FRAME. - Function: set-mouse-position FRAME X Y Thus function "warps the mouse" to position X, Y in frame FRAME. The arguments X and Y are integers, giving the position in pixels relative to the top left corner of the inside of FRAME. Warping the mouse means changing the screen position of the mouse as if the user had moved the physical mouse--thus simulating the effect of actual mouse motion. File: elisp, Node: Pop-Up Menus, Next: X Selections, Prev: Mouse Position, Up: Frames Pop-Up Menus ============ - Function: x-popup-menu POSITION MENU This function displays a pop-up menu and returns an indication of what selection the user makes. The argument POSITION specifies where on the screen to put the menu. It can be either a mouse button event (which says to put the menu where the user actuated the button) or a list of this form: ((XOFFSET YOFFSET) WINDOW) where XOFFSET and YOFFSET are positions measured in characters, counting from the top left corner of WINDOW's frame. The argument MENU says what to display in the menu. It can be a keymap or a list of keymaps (*note Menu Keymaps::.). Alternatively, it can have the following form: (TITLE PANE1 PANE2...) where each pane is a list of form (TITLE (LINE ITEM)...) Each LINE should be a string, and each ITEM should be the value to return if that LINE is chosen. File: elisp, Node: X Selections, Next: X Server, Prev: Pop-Up Menus, Up: Frames X Selections ============ The X server records a set of "selections" which permit transfer of data between application programs. The various selections are distinguished by "selection types", represented in Emacs by symbols. X clients including Emacs can read or set the selection for any given type. - Function: x-set-selection TYPE DATA This function sets a "selection" in the X server. It takes two arguments: a selection type TYPE, and the value to assign to it, DATA. If DATA is `nil', it means to clear out the selection. Otherwise, DATA may be a string, a symbol, an integer (or a cons of two integers or list of two integers), or a cons of two markers pointing to the same buffer. In the last case, the selection is considered to be the text between the markers. The data may also be a vector of valid non-vector selection values. Each possible TYPE has its own selection value, which changes independently. The usual values of TYPE are `PRIMARY' and `SECONDARY'; these are symbols with upper-case names, in accord with X Windows conventions. The default is `PRIMARY'. - Function: x-get-selection TYPE DATA-TYPE This function accesses selections set up by Emacs or by other X clients. It takes two optional arguments, TYPE and DATA-TYPE. The default for TYPE, the selection type, is `PRIMARY'. The DATA-TYPE argument specifies the form of data conversion to use, to convert the raw data obtained from another X client into Lisp data. Meaningful values include `TEXT', `STRING', `TARGETS', `LENGTH', `DELETE', `FILE_NAME', `CHARACTER_POSITION', `LINE_NUMBER', `COLUMN_NUMBER', `OWNER_OS', `HOST_NAME', `USER', `CLASS', `NAME', `ATOM', and `INTEGER'. (These are symbols with upper-case names in accord with X conventions.) The default for DATA-TYPE is `STRING'. The X server also has a set of numbered "cut buffers" which can store text or other data being moved between applications. Cut buffers are considered obsolete, but Emacs supports them for the sake of X clients that still use them. - Function: x-get-cut-buffer N This function returns the contents of cut buffer number N. - Function: x-set-cut-buffer STRING This function stores STRING into the first cut buffer (cut buffer 0), moving the other values down through the series of cut buffers, kill-ring-style. File: elisp, Node: X Server, Prev: X Selections, Up: Frames X Server ======== This section describes how to access and change the overall status of the X server Emacs is using. * Menu: * X Connections:: Opening and closing the X server connection. * Resources:: Getting resource values from the server. * Rebinding X Keys:: Telling the server what input to send for each keyboard key. * Server Data:: Getting info about the X server. File: elisp, Node: X Connections, Next: Resources, Up: X Server X Connections ------------- You can close the connection with the X server with the function `x-close-current-connection', and open a new one with `x-open-connection' (perhaps with a different server and display). - Function: x-close-current-connection This function closes the connection to the X server. It deletes all frames, making Emacs effectively inaccessible to the user; therefore, a Lisp program that closes the connection should open another one. - Function: x-open-connection DISPLAY &optional RESOURCE-STRING This function opens a connection to an X server, for use of display DISPLAY. The optional argument RESOURCE-STRING is a string of resource names and values, in the same format used in the `.Xresources' file. The values you specify override the resource values recorded in the X server itself. Here's an example of what this string might look like: "*BorderWidth: 3\n*InternalBorder: 2\n" - Function: x-color-display-p This returns `t' if the connected X display has color, and `nil' otherwise. - Function: x-color-defined-p COLOR This function reports whether a color name is meaningful and supported on the X display Emacs is using. It returns `t' if the display supports that color; otherwise, `nil'. Black-and-white displays support just two colors, `"black"' or `"white"'. Color displays support many other colors. - Function: x-synchronize FLAG The function `x-synchronize' enables or disables synchronous communication with the X server. It enables synchronous communication if FLAG is non-`nil', and disables it if FLAG is `nil'. In synchronous mode, Emacs waits for a response to each X protocol command before doing anything else. This is useful for debugging Emacs, because protocol errors are reported right away, which helps you find the erroneous command. Synchronous mode is not the default because it is much slower. File: elisp, Node: Resources, Next: Rebinding X Keys, Prev: X Connections, Up: X Server Resources --------- - Function: x-get-resource ATTRIBUTE &optional NAME CLASS The function `x-get-resource' retrieves a resource value from the X Windows defaults database. Resources are indexed by a combination of a "key" and a "class". This function searches using a key of the form `INSTANCE.ATTRIBUTE', where INSTANCE is the name under which Emacs was invoked, and uses `Emacs' as the class. The optional arguments COMPONENT and SUBCLASS add to the key and the class, respectively. You must specify both of them or neither. If you specify them, the key is `INSTANCE.COMPONENT.ATTRIBUTE', and the class is `Emacs.SUBCLASS'. File: elisp, Node: Rebinding X Keys, Next: Server Data, Prev: Resources, Up: X Server Rebinding X Server Keys ----------------------- The X server allows each client to specify what sequence of characters each keyboard key should generate, depending on the set of shift keys held down. Emacs has functions to redefine these sequences in the X server. Redefinitions via `x-rebind-key' apply only to Emacs. Other clients using the same X server are not affected. - Function: x-rebind-key KEYSYM MODIFIERS NEWSTRING This function redefines a keyboard key in the X server. KEYSYM is a string which conforms to the X keysym definitions found in `X11/keysymdef.h', but without the prefix `XK_'. MODIFIERS is either `nil', meaning no modifier keys, or a list of names of modifier keys, again using the names from `X11/keysymdef.h' but without the `XK_' prefix. The third argument, NEWSTRING, is the new definition of the key. It is the sequence of characters that the key should produce as input. For example, (x-rebind-key "F1" nil "abc") causes the F1 function key to generate the string `"abc"'. Similarly, (x-rebind-key "BackSpace" (list "Shift" "Control_L" "c-s-BackSpace") makes the BS key send the string `"c-s-BackSpace"' if either the shift key or the left-hand control key is held down. - Function: x-rebind-keys KEYSYM STRINGS This function redefines the complete meaning of a single keyboard key, specifying the behavior for each of the 16 shift masks independently. The argument KEYSYM specifies the key to rebind, as in `x-rebind-key'. The argument STRINGS is a list of 16 elements, one for each possible shift mask value; the Nth element says how to redefine the key KEYCODE with shift mask value N. If element N is a string, it is the new definition for shift mask N. If element N is `nil', the definition for shift mask N is unchanged. File: elisp, Node: Server Data, Prev: Rebinding X Keys, Up: X Server Data about the X Server ----------------------- This section describes functions and a variable that you can use to get information about the capabilities and origin of the X server that Emacs is displaying its frames on. - Function: x-display-screens This function returns the number of screens associated with the current display. - Function: x-server-version This function returns the list of version numbers of the X server in use. - Function: x-server-vendor This function returns the vendor supporting the X server in use. - Function: x-display-pixel-height This function returns the height of this X screen in pixels. - Function: x-display-mm-height This function returns the height of this X screen in millimeters. - Function: x-display-pixel-width This function returns the width of this X screen in pixels. - Function: x-display-mm-width This function returns the width of this X screen in millimeters. - Function: x-display-backing-store This function returns the backing store capability of this screen. Values can be the symbols `always', `when-mapped', or `not-useful'. - Function: x-display-save-under This function returns non-`nil' if this X screen supports the SaveUnder feature. - Function: x-display-planes This function returns the number of planes this display supports. - Function: x-display-visual-class This function returns the visual class for this X screen. The value is one of the symbols `static-gray', `gray-scale', `static-color', `pseudo-color', `true-color', and `direct-color'. - Function: x-display-color-p This function returns `t' if the X screen in use is a color screen. - Function: x-display-color-cells This function returns the number of color cells this X screen supports. - Variable: x-no-window-manager This variable's value is is `t' if no X window manager is in use. File: elisp, Node: Positions, Next: Markers, Prev: Frames, Up: Top Positions ********* A "position" is the index of a character in the text of buffer. More precisely, a position identifies the place between two characters (or before the first character, or after the last character), so we can speak of the character before or after a given position. However, the character after a position is often said to be "at" that position. Positions are usually represented as integers starting from 1, but can also be represented as "markers"--special objects which relocate automatically when text is inserted or deleted so they stay with the surrounding characters. *Note Markers::. * Menu: * Point:: The special position where editing takes place. * Motion:: Changing point. * Excursions:: Temporary motion and buffer changes. * Narrowing:: Restricting editing to a portion of the buffer. File: elisp, Node: Point, Next: Motion, Prev: Positions, Up: Positions Point ===== "Point" is a special buffer position used by many editing commands, including the self-inserting typed characters and text insertion functions. Other commands move point through the text to allow editing and insertion at different places. Like other positions, point designates a place between two characters (or before the first character, or after the last character), rather than a particular character. Many terminals display the cursor over the character that immediately follows point; on such terminals, point is actually before the character on which the cursor sits. The value of point is a number between 1 and the buffer size plus 1. If narrowing is in effect (*note Narrowing::.), then point is constrained to fall within the accessible portion of the buffer (possibly at one end of it). Each buffer has its own value of point, which is independent of the value of point in other buffers. Each window also has a value of point, which is independent of the value of point in other windows on the same buffer. This is why point can have different values in various windows that display the same buffer. When a buffer appears in only one window, the buffer's point and the window's point normally have the same value, so the distinction is rarely important. *Note Window Point::, for more details. - Function: point This function returns the position of point in the current buffer, as an integer. (point) => 175 - Function: point-min This function returns the minimum accessible value of point in the current buffer. This is 1, unless narrowing is in effect, in which case it is the position of the start of the region that you narrowed to. (*Note Narrowing::.) - Function: point-max This function returns the maximum accessible value of point in the current buffer. This is `(1+ (buffer-size))', unless narrowing is in effect, in which case it is the position of the end of the region that you narrowed to. (*Note Narrowing::). - Function: buffer-end FLAG This function returns `(point-min)' if FLAG is less than 1, `(point-max)' otherwise. The argument FLAG must be a number. - Function: buffer-size This function returns the total number of characters in the current buffer. In the absence of any narrowing (*note Narrowing::.), `point-max' returns a value one larger than this. (buffer-size) => 35 (point-max) => 36 - Variable: buffer-saved-size The value of this buffer-local variable is the former length of the current buffer, as of the last time it was read in, saved or auto-saved. File: elisp, Node: Motion, Next: Excursions, Prev: Point, Up: Positions Motion ====== Motion functions change the value of point, either relative to the current value of point, relative to the beginning or end of the buffer, or relative to the edges of the selected window. *Note Point::. * Menu: * Character Motion:: Moving in terms of characters. * Word Motion:: Moving in terms of words. * Buffer End Motion:: Moving to the beginning or end of the buffer. * Text Lines:: Moving in terms of lines of text. * Screen Lines:: Moving in terms of lines as displayed. * Vertical Motion:: Implementation of `next-line' and `previous-line'. * List Motion:: Moving by parsing lists and sexps. * Skipping Characters:: Skipping characters belonging to a certain set. File: elisp, Node: Character Motion, Next: Word Motion, Prev: Motion, Up: Motion Motion by Characters -------------------- These functions move point based on a count of characters. `goto-char' is a fundamental primitive because it is the way to move point to a specified position. - Command: goto-char POSITION This function sets point in the current buffer to the value POSITION. If POSITION is less than 1, then point is set to the beginning of the buffer. If it is greater than the length of the buffer, then point is set to the end of the buffer. If narrowing is in effect, then the position is still measured from the beginning of the buffer, but point cannot be moved outside of the accessible portion. Therefore, if POSITION is too small, point is set to the beginning of the accessible portion of the text; if POSITION is too large, point is set to the end. When this function is called interactively, POSITION is the numeric prefix argument, if provided; otherwise it is read from the minibuffer. `goto-char' returns POSITION. - Command: forward-char &optional COUNT This function moves point forward, towards the end of the buffer, COUNT characters (or backward, towards the beginning of the buffer, if COUNT is negative). If the function attempts to move point past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), an error is signaled with error code `beginning-of-buffer' or `end-of-buffer'. In an interactive call, COUNT is the numeric prefix argument. - Command: backward-char &optional COUNT This function moves point backward, towards the beginning of the buffer, COUNT characters (or forward, towards the end of the buffer, if COUNT is negative). If the function attempts to move point past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), an error is signaled with error code `beginning-of-buffer' or `end-of-buffer'. In an interactive call, COUNT is the numeric prefix argument. File: elisp, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion Motion by Words --------------- These functions for parsing words use the syntax table to decide whether a given character is part of a word. *Note Syntax Tables::. - Command: forward-word COUNT This function moves point forward COUNT words (or backward if COUNT is negative). Normally it returns `t'. If this motion encounters the beginning or end of the buffer, or the limits of the accessible portion when narrowing is in effect, point stops there and the value is `nil'. In an interactive call, COUNT is set to the numeric prefix argument. - Command: backward-word COUNT This function just like `forward-word', except that it moves backward until encountering the front of a word, rather than forward. In an interactive call, COUNT is set to the numeric prefix argument. This function is rarely used in programs, as it is more efficient to call `forward-word' with negative argument. - Variable: words-include-escapes This variable affects the behavior of `forward-word' and everything that uses it. If it is non-`nil', then characters in the "escape" and "character quote" syntax classes count as part of words. Otherwise, they do not. File: elisp, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion Motion to an End of the Buffer ------------------------------ To move point to the beginning of the buffer, write: (goto-char (point-min)) Likewise, to move to the end of the buffer, use: (goto-char (point-max)) Here are two commands which users use to do these things. They are documented here to warn you not to use them in Lisp programs, because they set the mark and display messages in the echo area. - Command: beginning-of-buffer &optional N This function moves point to the beginning of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If N is non-`nil', then it puts point N tenths of the way from the beginning of the buffer. In an interactive call, N is the numeric prefix argument, if provided; otherwise N defaults to `nil'. Don't use this function in Lisp programs! - Command: end-of-buffer &optional N This function moves point to the end of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If N is non-`nil', then it puts point N tenths of the way from the end. In an interactive call, N is the numeric prefix argument, if provided; otherwise N defaults to `nil'. Don't use this function in Lisp programs! File: elisp, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion Motion by Text Lines -------------------- Text lines are portions of the buffer delimited by newline characters, which are regarded as part of the previous line. The first text line begins at the beginning of the buffer, and the last text line ends at the end of the buffer whether or not the last character is a newline. The division of the buffer into text lines is not affected by the width of the window, or by how tabs and control characters are displayed. - Command: goto-line LINE This function moves point to the front of the LINEth line, counting from line 1 at beginning of buffer. If LINE is less than 1, then point is set to the beginning of the buffer. If LINE is greater than the number of lines in the buffer, then point is set to the *end of the last line* of the buffer. If narrowing is in effect, then LINE still counts from the beginning of the buffer, but point cannot go outside the accessible portion. So point is set at the beginning or end of the accessible portion of the text if the line number specifies a position that is inaccessible. The return value of `goto-line' is the difference between LINE and the line number of the line to which point actually was able move (before taking account of any narrowing). Thus, the value is positive if the scan encounters the end of the buffer. In an interactive call, LINE is the numeric prefix argument if one has been provided. Otherwise LINE is read in the minibuffer. - Command: beginning-of-line &optional COUNT This function moves point to the beginning of the current line. With an argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and then to the beginning of the line. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point at the beginning of the last line. No error is signaled. - Command: end-of-line &optional COUNT This function moves point to the end of the current line. With an argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and then to the end of the line. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point at the end of the last line. No error is signaled. - Command: forward-line &optional COUNT This function moves point forward COUNT lines, to the beginning of the line. If COUNT is negative, it moves point -COUNT lines backward, to the beginning of the line. If the beginning or end of the buffer (or of the accessible portion) is encountered before that many lines are found, then point stops at the beginning or end. No error is signaled. `forward-line' returns the difference between COUNT and the number of lines actually moved. If you attempt to move down five lines from the beginning of a buffer that has only three lines, point will positioned at the end of the last line, and the value will be 2. In an interactive call, COUNT is the numeric prefix argument. - Function: count-lines START END This function returns the number of lines between the positions START and END in the current buffer. If START and END are equal, then it returns 0. Otherwise it returns at least 1, even if START and END are on the same line. This is because the text between them, considered in isolation, must contain at least one line unless it is empty. Here is an example of using `count-lines': (defun current-line () "Return the vertical position of point in the selected window. Top line is 0. Counts each text line only once, even if it wraps." (+ (count-lines (window-start) (point)) (if (= (current-column) 0) 1 0) -1)) Also see the functions `bolp' and `eolp' in *Note Near Point::. These functions do not move point, but test whether it is already at the beginning or end of a line. File: elisp, Node: Screen Lines, Next: Vertical Motion, Prev: Text Lines, Up: Motion Motion by Screen Lines ---------------------- The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen lines, which are defined by the way the text appears on the screen. A text line is a single screen line if it is short enough to fit the width of the selected window, but otherwise it may occupy several screen lines. In some cases, text lines are truncated on the screen rather than continued onto additional screen lines. Then `vertical-motion' moves point just like `forward-line'. *Note Truncation::. Because the width of a given string depends on the flags which control the appearance of certain characters, `vertical-motion' will behave differently on a given piece of text found in different buffers. It will even act differently in different windows showing the same buffer, because the width may differ and so may the truncation flag. *Note Usual Display::. - Function: vertical-motion COUNT This function moves point to the start of the screen line COUNT screen lines down from the screen line containing point. If COUNT is negative, it moves up instead. This function returns the number of lines moved. The value may be less in absolute value than COUNT if the beginning or end of the buffer was reached. - Command: move-to-window-line COUNT This function moves point with respect to the text currently displayed in the selected window. Point is moved to the beginning of the screen line COUNT screen lines from the top of the window. If COUNT is negative, point moves either to the beginning of the line -COUNT lines from the bottom or else to the last line of the buffer if the buffer ends above the specified screen position. If COUNT is `nil', then point moves to the beginning of the line in the middle of the window. If the absolute value of COUNT is greater than the size of the window, then point moves to the place which would appear on that screen line if the window were tall enough. This will probably cause the next redisplay to scroll to bring that location onto the screen. In an interactive call, COUNT is the numeric prefix argument. The value returned is the window line number, with the top line in the window numbered 0. File: elisp, Node: Vertical Motion, Next: List Motion, Prev: Screen Lines, Up: Motion The User-Level Vertical Motion Commands --------------------------------------- A goal column is useful if you want to edit text such as a table in which you want to move point to a certain column on each line. The goal column affects the vertical text line motion commands, `next-line' and `previous-line'. *Note Basic Editing Commands: (emacs)Basic. - User Option: goal-column This variable holds an explicitly specified goal column for vertical line motion commands. If it is an integer, it specifies a column, and these commands try to move to that column on each line. If it is `nil', then the commands set their own goal columns. Any other value is invalid. - Variable: temporary-goal-column This variable holds the temporary goal column during a sequence of consecutive vertical line motion commands. It is overridden by `goal-column' if that is non-`nil'. It is set each time a vertical motion command is invoked, unless the previous command was also a vertical motion command. - User Option: track-eol This variable controls how the vertical line motion commands operate when starting at the end of a line. If `track-eol' is non-`nil', then vertical motion starting at the end of a line will keep to the ends of lines. This means moving to the end of each line moved onto. The value of `track-eol' has no effect if point is not at the end of a line when the first vertical motion command is given. `track-eol' has its effect by causing `temporary-goal-column' to be set to 9999 instead of to the current column. - Command: set-goal-column UNSET This command sets the variable `goal-column' to specify a permanent goal column for the vertical line motion commands. If UNSET is `nil', then `goal-column' is set to the current column of point. If UNSET is non-`nil', then `goal-column' is set to `nil'. This function is intended for interactive use; and in an interactive call, UNSET is the raw prefix argument. File: elisp, Node: List Motion, Next: Skipping Characters, Prev: Vertical Motion, Up: Motion Moving over Balanced Expressions -------------------------------- Here are several functions concerned with balanced-parenthesis expressions (also called "sexps" in connection with moving across them in Emacs). The syntax table controls how these functions interpret various characters; see *Note Syntax Tables::. *Note Parsing Expressions::, for lower-level primitives for scanning sexps or parts of sexps. For user-level commands, see *Note Lists and Sexps: (emacs)Lists and Sexps. - Command: forward-list ARG Move forward across ARG balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) - Command: backward-list ARG Move backward across ARG balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) - Command: up-list ARG Move forward out of ARG levels of parentheses. A negative argument means move backward but still to a less deep spot. - Command: down-list ARG Move forward down ARG levels of parentheses. A negative argument means move backward but still go down ARG level. - Command: forward-sexp ARG Move forward across ARG balanced expressions. Balanced expressions include both those delimited by parentheses and other kinds, such as words and string constants. For example, ---------- Buffer: foo ---------- (concat-!- "foo " (car x) y z) ---------- Buffer: foo ---------- (forward-sexp 3) => nil ---------- Buffer: foo ---------- (concat "foo " (car x) y-!- z) ---------- Buffer: foo ---------- - Command: backward-sexp ARG Move backward across ARG balanced expressions.