This is Info file elisp, produced by Makeinfo version 1.68 from the input file elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This version is the edition 2.5 of the GNU Emacs Lisp Reference Manual. It corresponds to Emacs Version 20.3 Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 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. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and 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 the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: elisp, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames Visibility of Frames ==================== A window 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 on the screen, not even as an icon. Visibility is meaningless for terminal frames, since only the selected one is actually displayed in any case. - 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 Window Frame Parameters::. The user can iconify and deiconify frames with the window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. *Note Misc Events::.  File: elisp, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames Raising and Lowering Frames =========================== Most window systems use 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 frame Windows with these functions: - Command: raise-frame &optional FRAME This function raises frame FRAME (default, the selected frame). - Command: lower-frame &optional FRAME This function lowers frame FRAME (default, the selected frame). - User Option: minibuffer-auto-raise If this is non-`nil', activation of the minibuffer raises the frame that the minibuffer window is in. You can also enable 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 Window Frame Parameters::.  File: elisp, Node: Frame Configurations, Next: Mouse Tracking, Prev: Raising and Lowering, Up: Frames Frame Configurations ==================== A "frame configuration" records the current arrangement of frames, all their properties, and the window configuration of each one. (*Note Window Configurations::.) - Function: current-frame-configuration This function returns a frame configuration list that describes the current arrangement of frames and their contents. - 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... This special form executes BODY, with generation of mouse motion events enabled. Typically BODY would use `read-event' to read the motion events and modify the display accordingly. *Note Motion Events::, for the format of mouse motion events. The value of `track-mouse' is that of the last form in BODY. You should design BODY to return when it sees the up-event that indicates the release of the button, or whatever kind of event means it is time to stop tracking. 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. In many cases, you can avoid the need to track the mouse by using the `mouse-face' text property (*note Special Properties::.). That works at a much lower level and runs more smoothly than Lisp-level mouse tracking.  File: elisp, Node: Mouse Position, Next: Pop-Up Menus, Prev: Mouse Tracking, Up: Frames Mouse Position ============== The 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 characters relative to the top left corner of the inside of FRAME. - Function: set-mouse-position FRAME X Y This function "warps the mouse" to position X, Y in frame FRAME. The arguments X and Y are integers, giving the position in characters relative to the top left corner of the inside of FRAME. If FRAME is not visible, this function does nothing. The return value is not significant. - Function: mouse-pixel-position This function is like `mouse-position' except that it returns coordinates in units of pixels rather than units of characters. - Function: set-mouse-pixel-position FRAME X Y This function warps the mouse like `set-mouse-position' except that X and Y are in units of pixels rather than units of characters. These coordinates are not required to be within the frame. If FRAME is not visible, this function does nothing. The return value is not significant.  File: elisp, Node: Pop-Up Menus, Next: Dialog Boxes, Prev: Mouse Position, Up: Frames Pop-Up Menus ============ When using a window system, a Lisp program can pop up a menu so that the user can choose an alternative with the mouse. - 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 coordinates, measured in pixels, counting from the top left corner of WINDOW's frame. If POSITION is `t', it means to use the current mouse position. If POSITION is `nil', it means to precompute the key binding equivalents for the keymaps specified in MENU, without actually displaying or popping up the menu. 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. *Usage note:* Don't use `x-popup-menu' to display a menu if you could do the job with a prefix key defined with a menu keymap. If you use a menu keymap to implement a menu, `C-h c' and `C-h a' can see the individual items in that menu and provide help for them. If instead you implement the menu by defining a command that calls `x-popup-menu', the help facilities cannot know what happens inside that command, so they cannot give any help for the menu's items. The menu bar mechanism, which lets you switch between submenus by moving the mouse, cannot look within the definition of a command to see that it calls `x-popup-menu'. Therefore, if you try to implement a submenu using `x-popup-menu', it cannot work with the menu bar in an integrated fashion. This is why all menu bar submenus are implemented with menu keymaps within the parent menu, and never with `x-popup-menu'. *Note Menu Bar::, If you want a menu bar submenu to have contents that vary, you should still use a menu keymap to implement it. To make the contents vary, add a hook function to `menu-bar-update-hook' to update the contents of the menu keymap as necessary.  File: elisp, Node: Dialog Boxes, Next: Pointer Shapes, Prev: Pop-Up Menus, Up: Frames Dialog Boxes ============ A dialog box is a variant of a pop-up menu--it looks a little different, it always appears in the center of a frame, and it has just one level and one pane. The main use of dialog boxes is for asking questions that the user can answer with "yes", "no", and a few other alternatives. The functions `y-or-n-p' and `yes-or-no-p' use dialog boxes instead of the keyboard, when called from commands invoked by mouse clicks. - Function: x-popup-dialog POSITION CONTENTS This function displays a pop-up dialog box and returns an indication of what selection the user makes. The argument CONTENTS specifies the alternatives to offer; it has this format: (TITLE (STRING . VALUE)...) which looks like the list that specifies a single pane for `x-popup-menu'. The return value is VALUE from the chosen alternative. An element of the list may be just a string instead of a cons cell `(STRING . VALUE)'. That makes a box that cannot be selected. If `nil' appears in the list, it separates the left-hand items from the right-hand items; items that precede the `nil' appear on the left, and items that follow the `nil' appear on the right. If you don't include a `nil' in the list, then approximately half the items appear on each side. Dialog boxes always appear in the center of a frame; the argument POSITION specifies which frame. The possible values are as in `x-popup-menu', but the precise coordinates don't matter; only the frame matters. In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the frame.  File: elisp, Node: Pointer Shapes, Next: Window System Selections, Prev: Dialog Boxes, Up: Frames Pointer Shapes ============== These variables specify which shape to use for the mouse pointer in various situations, when using the X Window System: `x-pointer-shape' This variable specifies the pointer shape to use ordinarily in the Emacs frame. `x-sensitive-text-pointer-shape' This variable specifies the pointer shape to use when the mouse is over mouse-sensitive text. These variables affect newly created frames. They do not normally affect existing frames; however, if you set the mouse color of a frame, that also updates its pointer shapes based on the current values of these variables. *Note Window Frame Parameters::. The values you can use, to specify either of these pointer shapes, are defined in the file `lisp/term/x-win.el'. Use `M-x apropos x-pointer ' to see a list of them.  File: elisp, Node: Window System Selections, Next: Font Names, Prev: Pointer Shapes, Up: Frames Window System 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), an overlay, or a cons of two markers pointing to the same buffer. An overlay or a pair of markers stands for text in the overlay or between the markers. The argument 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 Window System conventions. The default is `PRIMARY'. - Function: x-get-selection &optional 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, much like the way successive kills in Emacs move down the kill ring. - Variable: selection-coding-system This variable specifies the coding system to use when reading and writing a selections, the clipboard, or a cut buffer. *Note Coding Systems::. The default is `compound-text'.  File: elisp, Node: Font Names, Next: Fontsets, Prev: Window System Selections, Up: Frames Looking up Font Names ===================== - Function: x-list-font PATTERN &optional FACE FRAME MAXIMUM This function returns a list of available font names that match PATTERN. If the optional arguments FACE and FRAME are specified, then the list is limited to fonts that are the same size as FACE currently is on FRAME. The argument PATTERN should be a string, perhaps with wildcard characters: the `*' character matches any substring, and the `?' character matches any single character. Pattern matching of font names ignores case. If you specify FACE and FRAME, FACE should be a face name (a symbol) and FRAME should be a frame. The optional argument MAXIMUM sets a limit on how many fonts to return. If this is non-`nil', then the return value is truncated after the first MAXIMUM matching fonts. Specifying a small value for MAXIMUM can make this function much faster, in cases where many fonts match the pattern.  File: elisp, Node: Fontsets, Next: Color Names, Prev: Font Names, Up: Frames Fontsets ======== A "fontset" is a list of fonts, each assigned to a range of character codes. An individual font cannot display the whole range of characters that Emacs supports, but a fontset can. Fontsets have names, just as fonts do, and you can use a fontset name in place of a font name when you specify the "font" for a frame or a face. Here is information about defining a fontset under Lisp program control. - Function: create-fontset-from-fontset-spec FONTSET-SPEC &optional STYLE-VARIANT-P NOERROR This function defines a new fontset according to the specification string FONTSET-SPEC. The string should have this format: FONTPATTERN, [CHARSETNAME:FONTNAME]... Whitespace characters before and after the commas are ignored. The first part of the string, FONTPATTERN, should have the form of a standard X font name, except that the last two fields should be `fontset-ALIAS'. The new fontset has two names, one long and one short. The long name is FONTPATTERN in its entirety. The short name is `fontset-ALIAS'. You can refer to the fontset by either name. If a fontset with the same name already exists, an error is signaled, unless NOERROR is non-`nil', in which case this function does nothing. If optional argument STYLE-VARIANT-P is non-`nil', that says to create bold, italic and bold-italic variants of the fontset as well. These variant fontsets do not have a short name, only a long one, which is made by altering FONTPATTERN to indicate the bold or italic status. The specification string also says which fonts to use in the fontset. See below for the details. The construct `CHARSET:FONT' specifies which font to use (in this fontset) for one particular character set. Here, CHARSET is the name of a character set, and FONT is the font to use for that character set. You can use this construct any number of times in the specification string. For the remaining character sets, those that you don't specify explicitly, Emacs chooses a font based on FONTPATTERN: it replaces `fontset-ALIAS' with a value that names one character set. For the ASCII character set, `fontset-ALIAS' is replaced with `ISO8859-1'. In addition, when several consecutive fields are wildcards, Emacs collapses them into a single wildcard. This is to prevent use of auto-scaled fonts. Fonts made by scaling larger fonts are not usable for editing, and scaling a smaller font is not useful because it is better to use the smaller font in its own size, which Emacs does. Thus if FONTPATTERN is this, -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 the font specification for ASCII characters would be this: -*-fixed-medium-r-normal-*-24-*-ISO8859-1 and the font specification for Chinese GB2312 characters would be this: -*-fixed-medium-r-normal-*-24-*-gb2312*-* You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that have `song ti' or `fangsong ti' in the FAMILY field. In such a case, `Fontset-N' can be specified as below: Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* Then, the font specifications for all but Chinese GB2312 characters have `fixed' in the FAMILY field, and the font specification for Chinese GB2312 characters has a wild card `*' in the FAMILY field.  File: elisp, Node: Color Names, Next: Resources, Prev: Fontsets, Up: Frames Color Names =========== - Function: x-color-defined-p COLOR &optional FRAME This function reports whether a color name is meaningful. It returns `t' if so; otherwise, `nil'. The argument FRAME says which frame's display to ask about; if FRAME is omitted or `nil', the selected frame is used. Note that this does not tell you whether the display you are using really supports that color. You can ask for any defined color on any kind of display, and you will get some result--that is how the X server works. Here's an approximate way to test whether your display supports the color COLOR: (defun x-color-supported-p (color &optional frame) (and (x-color-defined-p color frame) (or (x-display-color-p frame) (member color '("black" "white")) (and (> (x-display-planes frame) 1) (equal color "gray"))))) - Function: x-color-values COLOR &optional FRAME This function returns a value that describes what COLOR should ideally look like. If COLOR is defined, the value is a list of three integers, which give the amount of red, the amount of green, and the amount of blue. Each integer ranges in principle from 0 to 65535, but in practice no value seems to be above 65280. If COLOR is not defined, the value is `nil'. (x-color-values "black") => (0 0 0) (x-color-values "white") => (65280 65280 65280) (x-color-values "red") => (65280 0 0) (x-color-values "pink") => (65280 49152 51968) (x-color-values "hungry") => nil The color values are returned for FRAME's display. If FRAME is omitted or `nil', the information is returned for the selected frame's display.  File: elisp, Node: Resources, Next: Server Data, Prev: Color Names, Up: Frames X Resources =========== - Function: x-get-resource ATTRIBUTE CLASS &optional COMPONENT SUBCLASS 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 using `Emacs.CLASS' 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.CLASS.SUBCLASS'. - Variable: x-resource-class This variable specifies the application name that `x-get-resource' should look up. The default value is `"Emacs"'. You can examine X resources for application names other than "Emacs" by binding this variable to some other string, around a call to `x-get-resource'. *Note X Resources: (emacs)Resources X.  File: elisp, Node: Server Data, Prev: Resources, Up: Frames Data about the X Server ======================= This section describes functions you can use to get information about the capabilities and origin of an X display that Emacs is using. Each of these functions lets you specify the display you are interested in: the DISPLAY argument can be either a display name, or a frame (meaning use the display that frame is on). If you omit the DISPLAY argument, or specify `nil', that means to use the selected frame's display. - Function: x-display-screens &optional DISPLAY This function returns the number of screens associated with the display. - Function: x-server-version &optional DISPLAY This function returns the list of version numbers of the X server running the display. - Function: x-server-vendor &optional DISPLAY This function returns the vendor that provided the X server software. - Function: x-display-pixel-height &optional DISPLAY This function returns the height of the screen in pixels. - Function: x-display-mm-height &optional DISPLAY This function returns the height of the screen in millimeters. - Function: x-display-pixel-width &optional DISPLAY This function returns the width of the screen in pixels. - Function: x-display-mm-width &optional DISPLAY This function returns the width of the screen in millimeters. - Function: x-display-backing-store &optional DISPLAY This function returns the backing store capability of the screen. Values can be the symbols `always', `when-mapped', or `not-useful'. - Function: x-display-save-under &optional DISPLAY This function returns non-`nil' if the display supports the SaveUnder feature. - Function: x-display-planes &optional DISPLAY This function returns the number of planes the display supports. - Function: x-display-visual-class &optional DISPLAY This function returns the visual class for the screen. The value is one of the symbols `static-gray', `gray-scale', `static-color', `pseudo-color', `true-color', and `direct-color'. - Function: x-display-grayscale-p &optional DISPLAY This function returns `t' if the screen can display shades of gray. - Function: x-display-color-p &optional DISPLAY This function returns `t' if the screen is a color screen. - Function: x-display-color-cells &optional DISPLAY This function returns the number of color cells the screen supports.  File: elisp, Node: Positions, Next: Markers, Prev: Frames, Up: Top Positions ********* A "position" is the index of a character in the text of a 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, we often speak of the character "at" a position, meaning the character after that position. Positions are usually represented as integers starting from 1, but can also be represented as "markers"--special objects that 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, 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. Usually terminals display the cursor over the character that immediately follows point; 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 value 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 normally 1, but if narrowing is in effect, 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  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. * 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, Up: Motion Motion by Characters -------------------- These functions move point based on a count of characters. `goto-char' is the fundamental primitive; the other functions use that. - Command: goto-char POSITION This function sets point in the current buffer to the value POSITION. If POSITION is less than 1, it moves point to the beginning of the buffer. If POSITION is greater than the length of the buffer, it moves point to the end. If narrowing is in effect, POSITION still counts from the beginning of the buffer, but point cannot go outside the accessible portion. If POSITION is out of range, `goto-char' moves point to the beginning or the end of the accessible portion. 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 COUNT characters forward, towards the end of the buffer (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 COUNT characters backward, towards the beginning of the buffer (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). "Moving one word" means moving until point crosses a word-constituent character and then encounters a word-separator character (or the boundary of the accessible part of the buffer). If it is possible to move COUNT words, without being stopped by the buffer boundary (except perhaps after the last word), the value is `t'. Otherwise, the return value is `nil' and point stops at the buffer boundary. In an interactive call, COUNT is set to the numeric prefix argument. - Command: backward-word COUNT This function is 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 a 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 that 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'. *Warning:* 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 of the buffer. In an interactive call, N is the numeric prefix argument, if provided; otherwise N defaults to `nil'. *Warning:* 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, by line continuation in display, 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 the buffer. If LINE is less than 1, it moves point to the beginning of the buffer. If LINE is greater than the number of lines in the buffer, it moves point to the end of the buffer--that is, the *end of the last line* of the buffer. This is the only case in which `goto-line' does not necessarily move to the beginning of a line. If narrowing is in effect, then LINE still counts from the beginning of the buffer, but point cannot go outside the accessible portion. So `goto-line' moves point to the beginning or end of the accessible portion, if the line number specifies an inaccessible position. The return value of `goto-line' is the difference between LINE and the line number of the line to which point actually was able to move (in the full buffer, before taking account of narrowing). Thus, the value is positive if the scan encounters the real end of the buffer before finding the specified line. The value is zero if scan encounters the end of the accessible portion but not the real 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 there. 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 there. 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 a line. If COUNT is zero, it moves point to the beginning of the current line. If `forward-line' encounters the beginning or end of the buffer (or of the accessible portion) before finding that many lines, it sets point there. 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 stops 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..." (+ (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: List 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. In these cases, `vertical-motion' moves point much like `forward-line'. *Note Truncation::. Because the width of a given string depends on the flags that control the appearance of certain characters, `vertical-motion' behaves differently, for a given piece of text, depending on the buffer it is in, and even on the selected window (because the width, the truncation flag, and display table may vary between windows). *Note Usual Display::. These functions scan text to determine where screen lines break, and thus take time proportional to the distance scanned. If you intend to use them heavily, Emacs provides caches which may improve the performance of your code. *Note cache-long-line-scans: Truncation. - Function: vertical-motion COUNT &optional WINDOW 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. `vertical-motion' returns the number of screen lines over which it moved point. The value may be less in absolute value than COUNT if the beginning or end of the buffer was reached. The window WINDOW is used for obtaining parameters such as the width, the horizontal scrolling, and the display table. But `vertical-motion' always operates on the current buffer, even if WINDOW currently displays some other buffer. - Command: move-to-window-line COUNT This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen line COUNT screen lines from the top of the window. If COUNT is negative, that specifies a position -COUNT lines from the bottom (or 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 that 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 point has moved to, with the top line in the window numbered 0. - Function: compute-motion FROM FROMPOS TO TOPOS WIDTH OFFSETS WINDOW This function scans the current buffer, calculating screen positions. It scans the buffer forward from position FROM, assuming that is at screen coordinates FROMPOS, to position TO or coordinates TOPOS, whichever comes first. It returns the ending buffer position and screen coordinates. The coordinate arguments FROMPOS and TOPOS are cons cells of the form `(HPOS . VPOS)'. The argument WIDTH is the number of columns available to display text; this affects handling of continuation lines. Use the value returned by `window-width' for the window of your choice; normally, use `(window-width WINDOW)'. The argument OFFSETS is either `nil' or a cons cell of the form `(HSCROLL . TAB-OFFSET)'. Here HSCROLL is the number of columns not being displayed at the left margin; most callers get this by calling `window-hscroll'. Meanwhile, TAB-OFFSET is the offset between column numbers on the screen and column numbers in the buffer. This can be nonzero in a continuation line, when the previous screen lines' widths do not add up to a multiple of `tab-width'. It is always zero in a non-continuation line. The window WINDOW serves only to specify which display table to use. `compute-motion' always operates on the current buffer, regardless of what buffer is displayed in WINDOW. The return value is a list of five elements: (POS VPOS HPOS PREVHPOS CONTIN) Here POS is the buffer position where the scan stopped, VPOS is the vertical screen position, and HPOS is the horizontal screen position. The result PREVHPOS is the horizontal position one character back from POS. The result CONTIN is `t' if the last line was continued after (or within) the previous character. For example, to find the buffer position of column COL of screen line LINE of a certain window, pass the window's display start location as FROM and the window's upper-left coordinates as FROMPOS. Pass the buffer's `(point-max)' as TO, to limit the scan to the end of the accessible portion of the buffer, and pass LINE and COL as TOPOS. Here's a function that does this: (defun coordinates-of-position (col line) (car (compute-motion (window-start) '(0 . 0) (point-max) (cons col line) (window-width) (cons (window-hscroll) 0) (selected-window)))) When you use `compute-motion' for the minibuffer, you need to use `minibuffer-prompt-width' to get the horizontal position of the beginning of the first screen line. *Note Minibuffer Misc::.  File: elisp, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, 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 Commands: (emacs)Lists Commands. - Command: forward-list ARG This function moves forward across ARG balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) - Command: backward-list ARG This function moves backward across ARG balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) - Command: up-list ARG This function moves forward out of ARG levels of parentheses. A negative argument means move backward but still to a less deep spot. - Command: down-list ARG This function moves forward into ARG levels of parentheses. A negative argument means move backward but still go deeper in parentheses (-ARG levels). - Command: forward-sexp ARG This function moves 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 This function moves backward across ARG balanced expressions. - Command: beginning-of-defun ARG This function moves back to the ARGth beginning of a defun. If ARG is negative, this actually moves forward, but it still moves to the beginning of a defun, not to the end of one. - Command: end-of-defun ARG This function moves forward to the ARGth end of a defun. If ARG is negative, this actually moves backward, but it still moves to the end of a defun, not to the beginning of one. - User Option: defun-prompt-regexp If non-`nil', this variable holds a regular expression that specifies what text can appear before the open-parenthesis that starts a defun. That is to say, a defun begins on a line that starts with a match for this regular expression, followed by a character with open-parenthesis syntax.