1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
58 - Function: frame-list
59 The function `frame-list' returns a list of all the frames that
60 have not been deleted. It is analogous to `buffer-list' for
61 buffers. The list that you get is newly created, so modifying the
62 list doesn't have any effect on the internals of XEmacs.
64 - Function: device-frame-list &optional DEVICE
65 This function returns a list of all frames on DEVICE. If DEVICE
66 is `nil', the selected device will be used.
68 - Function: visible-frame-list &optional DEVICE
69 This function returns a list of just the currently visible frames.
70 If DEVICE is specified only frames on that device will be returned.
71 *Note Visibility of Frames::. (TTY frames always count as
72 "visible", even though only the selected one is actually
75 - Function: next-frame &optional FRAME MINIBUF
76 The function `next-frame' lets you cycle conveniently through all
77 the frames from an arbitrary starting point. It returns the "next"
78 frame after FRAME in the cycle. If FRAME is omitted or `nil', it
79 defaults to the selected frame.
81 The second argument, MINIBUF, says which frames to consider:
84 Exclude minibuffer-only frames.
87 Consider all visible frames.
90 Consider all visible or iconified frames.
93 Consider only the frames using that particular window as their
97 Include all visible frames.
100 Include all visible and iconified frames.
105 - Function: previous-frame &optional FRAME MINIBUF
106 Like `next-frame', but cycles through all frames in the opposite
109 See also `next-window' and `previous-window', in *Note Cyclic Window
113 File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
118 Each window is part of one and only one frame; you can get the frame
121 - Function: frame-root-window &optional FRAME
122 This returns the root window of frame FRAME. FRAME defaults to
123 the selected frame if not specified.
125 - Function: window-frame &optional WINDOW
126 This function returns the frame that WINDOW is on. WINDOW
127 defaults to the selected window if omitted.
129 All the non-minibuffer windows in a frame are arranged in a cyclic
130 order. The order runs from the frame's top window, which is at the
131 upper left corner, down and to the right, until it reaches the window at
132 the lower right corner (always the minibuffer window, if the frame has
133 one), and then it moves back to the top.
135 - Function: frame-top-window FRAME
136 This returns the topmost, leftmost window of frame FRAME.
138 At any time, exactly one window on any frame is "selected within the
139 frame". The significance of this designation is that selecting the
140 frame also selects this window. You can get the frame's current
141 selected window with `frame-selected-window'.
143 - Function: frame-selected-window &optional FRAME
144 This function returns the window on FRAME that is selected within
145 FRAME. FRAME defaults to the selected frame if not specified.
147 Conversely, selecting a window for XEmacs with `select-window' also
148 makes that window selected within its frame. *Note Selecting Windows::.
150 Another function that (usually) returns one of the windows in a
151 frame is `minibuffer-window'. *Note Minibuffer Misc::.
154 File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
156 Minibuffers and Frames
157 ======================
159 Normally, each frame has its own minibuffer window at the bottom,
160 which is used whenever that frame is selected. If the frame has a
161 minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
164 However, you can also create a frame with no minibuffer. Such a
165 frame must use the minibuffer window of some other frame. When you
166 create the frame, you can specify explicitly the minibuffer window to
167 use (in some other frame). If you don't, then the minibuffer is found
168 in the frame which is the value of the variable
169 `default-minibuffer-frame'. Its value should be a frame which does
172 - Variable: default-minibuffer-frame
173 This variable specifies the frame to use for the minibuffer
177 File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
182 At any time, one frame in XEmacs is the "selected frame". The
183 selected window always resides on the selected frame. As the focus
184 moves from device to device, the selected frame on each device is
185 remembered and restored when the focus moves back to that device.
187 - Function: selected-frame &optional DEVICE
188 This function returns the selected frame on DEVICE. If DEVICE is
189 not specified, the selected device will be used. If no frames
190 exist on the device, `nil' is returned.
192 The X server normally directs keyboard input to the X window that the
193 mouse is in. Some window managers use mouse clicks or keyboard events
194 to "shift the focus" to various X windows, overriding the normal
195 behavior of the server.
197 Lisp programs can switch frames "temporarily" by calling the
198 function `select-frame'. This does not override the window manager;
199 rather, it escapes from the window manager's control until that control
200 is somehow reasserted.
202 When using a text-only terminal, there is no window manager;
203 therefore, `select-frame' is the only way to switch frames, and the
204 effect lasts until overridden by a subsequent call to `select-frame'.
205 Only the selected terminal frame is actually displayed on the terminal.
206 Each terminal screen except for the initial one has a number, and the
207 number of the selected frame appears in the mode line after the word
208 `XEmacs' (*note Modeline Variables::.).
210 - Function: select-frame FRAME
211 This function selects frame FRAME, temporarily disregarding the
212 focus of the X server if any. The selection of FRAME lasts until
213 the next time the user does something to select a different frame,
214 or until the next time this function is called.
216 Note that `select-frame' does not actually cause the window-system
217 focus to be set to this frame, or the `select-frame-hook' or
218 `deselect-frame-hook' to be run, until the next time that XEmacs is
219 waiting for an event.
221 Also note that when the variable `focus-follows-mouse' is
222 non-`nil', the frame selection is temporary and is reverted when
223 the current command terminates, much like the buffer selected by
224 `set-buffer'. In order to effect a permanent focus change use
227 - Function: focus-frame FRAME
228 This function selects FRAME and gives it the window system focus.
229 The operation of `focus-frame' is not affected by the value of
230 `focus-follows-mouse'.
232 - Macro: save-selected-frame FORMS...
233 This macro records the selected frame, executes FORMS in sequence,
234 then restores the earlier selected frame. The value returned is
235 the value of the last form.
237 - Macro: with-selected-frame FRAME FORMS...
238 This macro records the selected frame, then selects FRAME and
239 executes FORMS in sequence. After the last form is finished, the
240 earlier selected frame is restored. The value returned is the
241 value of the last form.
244 File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
249 An X window frame may be "visible", "invisible", or "iconified". If
250 it is visible, you can see its contents. If it is iconified, the
251 frame's contents do not appear on the screen, but an icon does. If the
252 frame is invisible, it doesn't show on the screen, not even as an icon.
254 Visibility is meaningless for TTY frames, since only the selected
255 one is actually displayed in any case.
257 - Command: make-frame-visible &optional FRAME
258 This function makes frame FRAME visible. If you omit FRAME, it
259 makes the selected frame visible.
261 - Command: make-frame-invisible &optional FRAME
262 This function makes frame FRAME invisible.
264 - Command: iconify-frame &optional FRAME
265 This function iconifies frame FRAME.
267 - Command: deiconify-frame &optional FRAME
268 This function de-iconifies frame FRAME. Under X, this is
269 equivalent to `make-frame-visible'.
271 - Function: frame-visible-p FRAME
272 This returns whether FRAME is currently "visible" (actually in use
273 for display). A frame that is not visible is not updated, and, if
274 it works through a window system, may not show at all.
276 - Function: frame-iconified-p FRAME
277 This returns whether FRAME is iconified. Not all window managers
278 use icons; some merely unmap the window, so this function is not
279 the inverse of `frame-visible-p'. It is possible for a frame to
280 not be visible and not be iconified either. However, if the frame
281 is iconified, it will not be visible. (Under FSF Emacs, the
282 functionality of this function is obtained through
285 - Function: frame-totally-visible-p FRAME
286 This returns whether FRAME is not obscured by any other X windows.
287 On TTY frames, this is the same as `frame-visible-p'.
290 File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
292 Raising and Lowering Frames
293 ===========================
295 The X Window System uses a desktop metaphor. Part of this metaphor
296 is the idea that windows are stacked in a notional third dimension
297 perpendicular to the screen surface, and thus ordered from "highest" to
298 "lowest". Where two windows overlap, the one higher up covers the one
299 underneath. Even a window at the bottom of the stack can be seen if no
300 other window overlaps it.
302 A window's place in this ordering is not fixed; in fact, users tend
303 to change the order frequently. "Raising" a window means moving it
304 "up", to the top of the stack. "Lowering" a window means moving it to
305 the bottom of the stack. This motion is in the notional third
306 dimension only, and does not change the position of the window on the
309 You can raise and lower XEmacs's X windows with these functions:
311 - Command: raise-frame &optional FRAME
312 This function raises frame FRAME.
314 - Command: lower-frame &optional FRAME
315 This function lowers frame FRAME.
317 You can also specify auto-raise (raising automatically when a frame
318 is selected) or auto-lower (lowering automatically when it is
319 deselected). Under X, most ICCCM-compliant window managers will have
320 an option to do this for you, but the following variables are provided
321 in case you're using a broken WM. (Under FSF Emacs, the same
322 functionality is provided through the `auto-raise' and `auto-lower'
325 - Variable: auto-raise-frame
326 This variable's value is `t' if frames will be raised to the top
329 - Variable: auto-lower-frame
330 This variable's value is `t' if frames will be lowered to the
331 bottom when no longer selected.
333 Auto-raising and auto-lowering is implemented through functions
334 attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
335 Hooks::.). Under normal circumstances, you should not call these
338 - Function: default-select-frame-hook
339 This hook function implements the `auto-raise-frame' variable; it
340 is for use as the value of `select-frame-hook'.
342 - Function: default-deselect-frame-hook
343 This hook function implements the `auto-lower-frame' variable; it
344 is for use as the value of `deselect-frame-hook'.
347 File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
352 A "frame configuration" records the current arrangement of frames,
353 all their properties, and the window configuration of each one.
355 - Function: current-frame-configuration
356 This function returns a frame configuration list that describes
357 the current arrangement of frames and their contents.
359 - Function: set-frame-configuration CONFIGURATION
360 This function restores the state of frames described in
364 File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames
366 Hooks for Customizing Frame Behavior
367 ====================================
369 XEmacs provides many hooks that are called at various times during a
370 frame's lifetime. *Note Hooks::.
372 - Variable: create-frame-hook
373 This hook is called each time a frame is created. The functions
374 are called with one argument, the newly-created frame.
376 - Variable: delete-frame-hook
377 This hook is called each time a frame is deleted. The functions
378 are called with one argument, the about-to-be-deleted frame.
380 - Variable: select-frame-hook
381 This is a normal hook that is run just after a frame is selected.
382 The function `default-select-frame-hook', which implements
383 auto-raising (*note Raising and Lowering::.), is normally attached
386 Note that calling `select-frame' does not necessarily set the
387 focus: The actual window-system focus will not be changed until
388 the next time that XEmacs is waiting for an event, and even then,
389 the window manager may refuse the focus-change request.
391 - Variable: deselect-frame-hook
392 This is a normal hook that is run just before a frame is deselected
393 (and another frame is selected). The function
394 `default-deselect-frame-hook', which implements auto-lowering
395 (*note Raising and Lowering::.), is normally attached to this hook.
397 - Variable: map-frame-hook
398 This hook is called each time a frame is mapped (i.e. made
399 visible). The functions are called with one argument, the newly
402 - Variable: unmap-frame-hook
403 This hook is called each time a frame is unmapped (i.e. made
404 invisible or iconified). The functions are called with one
405 argument, the newly unmapped frame.
408 File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top
413 A "console" is an object representing a single input connection to
414 XEmacs, such as an X display or a TTY connection. It is possible for
415 XEmacs to have frames on multiple consoles at once (even on
416 heterogeneous types - you can simultaneously have a frame on an X
417 display and a TTY connection). Normally, there is only one console in
420 A "device" is an object representing a single output device, such as
421 a particular screen on an X display. (Usually there is exactly one
422 device per X console connection, but there may be more than one if you
423 have a multi-headed X display. For TTY connections, there is always
424 exactly one device per console.)
426 Each device has one or more "frames" in which text can be displayed.
427 For X displays and the like, a frame corresponds to the normal
428 window-system concept of a window. Frames can overlap, be displayed at
429 various locations within the display, be resized, etc. For TTY, only
430 one frame can be displayed at a time, and it occupies the entire TTY
433 However, you can still define multiple frames and switch between
434 them. Their contents are entirely separate from each other. These
435 sorts of frames resemble the "virtual console" capability provided
436 under Linux or the multiple screens provided by the multiplexing program
439 When you start up XEmacs, an initial console and device are created
440 to receive input and display frames on. This will either be an X
441 display or a TTY connection, depending on what mode you started XEmacs
442 in (this is determined by the `DISPLAY' environment variable, the
443 `-nw', `-t' and `-display' command-line options, etc.).
445 You can connect to other X displays and TTY connections by creating
446 new console objects, and to other X screens on an existing display by
447 creating new device objects, as described below. Many functions (for
448 example the frame-creation functions) take an optional device argument
449 specifying which device the function pertains to. If the argument is
450 omitted, it defaults to the selected device (see below).
452 - Function: consolep OBJECT
453 This returns non-`nil' if OBJECT is a console.
455 - Function: devicep OBJECT
456 This returns non-`nil' if OBJECT is a device.
460 * Basic Console Functions:: Functions for working with consoles.
461 * Basic Device Functions:: Functions for working with devices.
462 * Console Types and Device Classes::
463 I/O and color characteristics.
464 * Connecting to a Console or Device::
465 * The Selected Console and Device::
466 * Console and Device I/O:: Controlling input and output.
469 File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices
471 Basic Console Functions
472 =======================
474 - Function: console-list
475 This function returns a list of all existing consoles.
477 - Function: console-device-list &optional CONSOLE
478 This function returns a list of all devices on CONSOLE. If
479 CONSOLE is `nil', the selected console will be used.
482 File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices
484 Basic Device Functions
485 ======================
487 - Function: device-list
488 This function returns a list of all existing devices.
490 - Function: device-or-frame-p OBJECT
491 This function returns non-`nil' if OBJECT is a device or frame.
492 This function is useful because devices and frames are similar in
493 many respects and many functions can operate on either one.
495 - Function: device-frame-list DEVICE
496 This function returns a list of all frames on DEVICE.
498 - Function: frame-device FRAME
499 This function returns the device that FRAME is on.
502 File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices
504 Console Types and Device Classes
505 ================================
507 Every device is of a particular "type", which describes how the
508 connection to that device is made and how the device operates, and a
509 particular "class", which describes other characteristics of the device
510 (currently, the color capabilities of the device).
512 The currently-defined device types are
515 A connection to an X display (such as `willow:0').
518 A connection to a tty (such as `/dev/ttyp3').
521 A stdio connection. This describes a device for which input and
522 output is only possible in a stream-like fashion, such as when
523 XEmacs in running in batch mode. The very first device created by
524 XEmacs is a terminal device and is used to print out messages of
525 various sorts (for example, the help message when you use the
526 `-help' command-line option).
528 The currently-defined device classes are
533 A grayscale device (a device that can display multiple shades of
537 A device that can only display two colors (e.g. black and white).
539 - Function: device-type DEVICE
540 This function returns the type of DEVICE. This is a symbol whose
541 name is one of the device types mentioned above.
543 - Function: device-or-frame-type DEVICE-OR-FRAME
544 This function returns the type of DEVICE-OR-FRAME.
546 - Function: device-class DEVICE
547 This function returns the class (color behavior) of DEVICE. This
548 is a symbol whose name is one of the device classes mentioned
551 - Function: valid-device-type-p DEVICE-TYPE
552 This function returns whether DEVICE-TYPE (which should be a
553 symbol) species a valid device type.
555 - Function: valid-device-class-p DEVICE-CLASS
556 This function returns whether DEVICE-CLASS (which should be a
557 symbol) species a valid device class.
559 - Variable: terminal-device
560 This variable holds the initial terminal device object, which
561 represents XEmacs's stdout.
564 File: lispref.info, Node: Connecting to a Console or Device, Next: The Selected Console and Device, Prev: Console Types and Device Classes, Up: Consoles and Devices
566 Connecting to a Console or Device
567 =================================
569 - Function: make-device &optional TYPE DEVICE-DATA
570 This function creates a new device.
572 The following two functions create devices of specific types and are
573 written in terms of `make-device'.
575 - Function: make-tty-device &optional TTY TERMINAL-TYPE
576 This function creates a new tty device on TTY. This also creates
577 the tty's first frame. TTY should be a string giving the name of
578 a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
579 returned by the `tty' command issued from the Unix shell. A value
580 of `nil' means use the stdin and stdout as passed to XEmacs from
581 the shell. If TERMINAL-TYPE is non-`nil', it should be a string
582 specifying the type of the terminal attached to the specified tty.
583 If it is `nil', the terminal type will be inferred from the
584 `TERM' environment variable.
586 - Function: make-x-device &optional DISPLAY ARGV-LIST
587 This function creates a new device connected to DISPLAY. Optional
588 argument ARGV-LIST is a list of strings describing command line
591 - Function: delete-device DEVICE
592 This function deletes DEVICE, permanently eliminating it from use.
593 This disconnects XEmacs's connection to the device.
595 - Variable: create-device-hook
596 This variable, if non-`nil', should contain a list of functions,
597 which are called when a device is created.
599 - Variable: delete-device-hook
600 This variable, if non-`nil', should contain a list of functions,
601 which are called when a device is deleted.
603 - Function: console-live-p OBJECT
604 This function returns non-`nil' if OBJECT is a console that has
607 - Function: device-live-p OBJECT
608 This function returns non-`nil' if OBJECT is a device that has not
611 - Function: device-x-display DEVICE
612 This function returns the X display which DEVICE is connected to,
613 if DEVICE is an X device.
616 File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices
618 The Selected Console and Device
619 ===============================
621 - Function: select-console CONSOLE
622 This function selects the console CONSOLE. Subsequent editing
623 commands apply to its selected device, selected frame, and selected
624 window. The selection of CONSOLE lasts until the next time the
625 user does something to select a different console, or until the
626 next time this function is called.
628 - Function: selected-console
629 This function returns the console which is currently active.
631 - Function: select-device DEVICE
632 This function selects the device DEVICE.
634 - Function: selected-device &optional CONSOLE
635 This function returns the device which is currently active. If
636 optional CONSOLE is non-`nil', this function returns the device
637 that would be currently active if CONSOLE were the selected
641 File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
643 Console and Device I/O
644 ======================
646 - Function: console-disable-input CONSOLE
647 This function disables input on console CONSOLE.
649 - Function: console-enable-input CONSOLE
650 This function enables input on console CONSOLE.
652 Each device has a "baud rate" value associated with it. On most
653 systems, changing this value will affect the amount of padding and
654 other strategic decisions made during redisplay.
656 - Function: device-baud-rate &optional DEVICE
657 This function returns the output baud rate of DEVICE.
659 - Function: set-device-baud-rate DEVICE RATE
660 This function sets the output baud rate of DEVICE to RATE.
663 File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
668 A "position" is the index of a character in the text of a buffer.
669 More precisely, a position identifies the place between two characters
670 (or before the first character, or after the last character), so we can
671 speak of the character before or after a given position. However, we
672 often speak of the character "at" a position, meaning the character
675 Positions are usually represented as integers starting from 1, but
676 can also be represented as "markers"--special objects that relocate
677 automatically when text is inserted or deleted so they stay with the
678 surrounding characters. *Note Markers::.
682 * Point:: The special position where editing takes place.
683 * Motion:: Changing point.
684 * Excursions:: Temporary motion and buffer changes.
685 * Narrowing:: Restricting editing to a portion of the buffer.
688 File: lispref.info, Node: Point, Next: Motion, Up: Positions
693 "Point" is a special buffer position used by many editing commands,
694 including the self-inserting typed characters and text insertion
695 functions. Other commands move point through the text to allow editing
696 and insertion at different places.
698 Like other positions, point designates a place between two characters
699 (or before the first character, or after the last character), rather
700 than a particular character. Usually terminals display the cursor over
701 the character that immediately follows point; point is actually before
702 the character on which the cursor sits.
704 The value of point is a number between 1 and the buffer size plus 1.
705 If narrowing is in effect (*note Narrowing::.), then point is
706 constrained to fall within the accessible portion of the buffer
707 (possibly at one end of it).
709 Each buffer has its own value of point, which is independent of the
710 value of point in other buffers. Each window also has a value of point,
711 which is independent of the value of point in other windows on the same
712 buffer. This is why point can have different values in various windows
713 that display the same buffer. When a buffer appears in only one window,
714 the buffer's point and the window's point normally have the same value,
715 so the distinction is rarely important. *Note Window Point::, for more
718 - Function: point &optional BUFFER
719 This function returns the value of point in BUFFER, as an integer.
720 BUFFER defaults to the current buffer if omitted.
725 - Function: point-min &optional BUFFER
726 This function returns the minimum accessible value of point in
727 BUFFER. This is normally 1, but if narrowing is in effect, it is
728 the position of the start of the region that you narrowed to.
729 (*Note Narrowing::.) BUFFER defaults to the current buffer if
732 - Function: point-max &optional BUFFER
733 This function returns the maximum accessible value of point in
734 BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
735 in effect, in which case it is the position of the end of the
736 region that you narrowed to. (*note Narrowing::.). BUFFER
737 defaults to the current buffer if omitted.
739 - Function: buffer-end FLAG &optional BUFFER
740 This function returns `(point-min buffer)' if FLAG is less than 1,
741 `(point-max buffer)' otherwise. The argument FLAG must be a
742 number. BUFFER defaults to the current buffer if omitted.
744 - Function: buffer-size &optional BUFFER
745 This function returns the total number of characters in BUFFER.
746 In the absence of any narrowing (*note Narrowing::.), `point-max'
747 returns a value one larger than this. BUFFER defaults to the
748 current buffer if omitted.
755 - Variable: buffer-saved-size
756 The value of this buffer-local variable is the former length of the
757 current buffer, as of the last time it was read in, saved or
761 File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
766 Motion functions change the value of point, either relative to the
767 current value of point, relative to the beginning or end of the buffer,
768 or relative to the edges of the selected window. *Note Point::.
772 * Character Motion:: Moving in terms of characters.
773 * Word Motion:: Moving in terms of words.
774 * Buffer End Motion:: Moving to the beginning or end of the buffer.
775 * Text Lines:: Moving in terms of lines of text.
776 * Screen Lines:: Moving in terms of lines as displayed.
777 * List Motion:: Moving by parsing lists and sexps.
778 * Skipping Characters:: Skipping characters belonging to a certain set.
781 File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
786 These functions move point based on a count of characters.
787 `goto-char' is the fundamental primitive; the other functions use that.
789 - Command: goto-char POSITION &optional BUFFER
790 This function sets point in `buffer' to the value POSITION. If
791 POSITION is less than 1, it moves point to the beginning of the
792 buffer. If POSITION is greater than the length of the buffer, it
793 moves point to the end. BUFFER defaults to the current buffer if
796 If narrowing is in effect, POSITION still counts from the
797 beginning of the buffer, but point cannot go outside the accessible
798 portion. If POSITION is out of range, `goto-char' moves point to
799 the beginning or the end of the accessible portion.
801 When this function is called interactively, POSITION is the
802 numeric prefix argument, if provided; otherwise it is read from the
805 `goto-char' returns POSITION.
807 - Command: forward-char &optional COUNT BUFFER
808 This function moves point COUNT characters forward, towards the
809 end of the buffer (or backward, towards the beginning of the
810 buffer, if COUNT is negative). If the function attempts to move
811 point past the beginning or end of the buffer (or the limits of
812 the accessible portion, when narrowing is in effect), an error is
813 signaled with error code `beginning-of-buffer' or `end-of-buffer'.
814 BUFFER defaults to the current buffer if omitted.
816 In an interactive call, COUNT is the numeric prefix argument.
818 - Command: backward-char &optional COUNT BUFFER
819 This function moves point COUNT characters backward, towards the
820 beginning of the buffer (or forward, towards the end of the
821 buffer, if COUNT is negative). If the function attempts to move
822 point past the beginning or end of the buffer (or the limits of
823 the accessible portion, when narrowing is in effect), an error is
824 signaled with error code `beginning-of-buffer' or `end-of-buffer'.
825 BUFFER defaults to the current buffer if omitted.
827 In an interactive call, COUNT is the numeric prefix argument.
830 File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
835 These functions for parsing words use the syntax table to decide
836 whether a given character is part of a word. *Note Syntax Tables::.
838 - Command: forward-word COUNT &optional BUFFER
839 This function moves point forward COUNT words (or backward if
840 COUNT is negative). Normally it returns `t'. If this motion
841 encounters the beginning or end of the buffer, or the limits of the
842 accessible portion when narrowing is in effect, point stops there
843 and the value is `nil'. BUFFER defaults to the current buffer if
846 In an interactive call, COUNT is set to the numeric prefix
849 - Command: backward-word COUNT &optional BUFFER
850 This function is just like `forward-word', except that it moves
851 backward until encountering the front of a word, rather than
852 forward. BUFFER defaults to the current buffer if omitted.
854 In an interactive call, COUNT is set to the numeric prefix
857 This function is rarely used in programs, as it is more efficient
858 to call `forward-word' with a negative argument.
860 - Variable: words-include-escapes
861 This variable affects the behavior of `forward-word' and everything
862 that uses it. If it is non-`nil', then characters in the "escape"
863 and "character quote" syntax classes count as part of words.
864 Otherwise, they do not.
867 File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
869 Motion to an End of the Buffer
870 ------------------------------
872 To move point to the beginning of the buffer, write:
874 (goto-char (point-min))
876 Likewise, to move to the end of the buffer, use:
878 (goto-char (point-max))
880 Here are two commands that users use to do these things. They are
881 documented here to warn you not to use them in Lisp programs, because
882 they set the mark and display messages in the echo area.
884 - Command: beginning-of-buffer &optional N
885 This function moves point to the beginning of the buffer (or the
886 limits of the accessible portion, when narrowing is in effect),
887 setting the mark at the previous position. If N is non-`nil',
888 then it puts point N tenths of the way from the beginning of the
891 In an interactive call, N is the numeric prefix argument, if
892 provided; otherwise N defaults to `nil'.
894 Don't use this function in Lisp programs!
896 - Command: end-of-buffer &optional N
897 This function moves point to the end of the buffer (or the limits
898 of the accessible portion, when narrowing is in effect), setting
899 the mark at the previous position. If N is non-`nil', then it puts
900 point N tenths of the way from the end of the buffer.
902 In an interactive call, N is the numeric prefix argument, if
903 provided; otherwise N defaults to `nil'.
905 Don't use this function in Lisp programs!
908 File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
913 Text lines are portions of the buffer delimited by newline
914 characters, which are regarded as part of the previous line. The first
915 text line begins at the beginning of the buffer, and the last text line
916 ends at the end of the buffer whether or not the last character is a
917 newline. The division of the buffer into text lines is not affected by
918 the width of the window, by line continuation in display, or by how
919 tabs and control characters are displayed.
921 - Command: goto-line LINE
922 This function moves point to the front of the LINEth line,
923 counting from line 1 at beginning of the buffer. If LINE is less
924 than 1, it moves point to the beginning of the buffer. If LINE is
925 greater than the number of lines in the buffer, it moves point to
926 the end of the buffer--that is, the *end of the last line* of the
927 buffer. This is the only case in which `goto-line' does not
928 necessarily move to the beginning of a line.
930 If narrowing is in effect, then LINE still counts from the
931 beginning of the buffer, but point cannot go outside the accessible
932 portion. So `goto-line' moves point to the beginning or end of the
933 accessible portion, if the line number specifies an inaccessible
936 The return value of `goto-line' is the difference between LINE and
937 the line number of the line to which point actually was able to
938 move (in the full buffer, before taking account of narrowing).
939 Thus, the value is positive if the scan encounters the real end of
940 the buffer. The value is zero if scan encounters the end of the
941 accessible portion but not the real end of the buffer.
943 In an interactive call, LINE is the numeric prefix argument if one
944 has been provided. Otherwise LINE is read in the minibuffer.
946 - Command: beginning-of-line &optional COUNT BUFFER
947 This function moves point to the beginning of the current line.
948 With an argument COUNT not `nil' or 1, it moves forward COUNT-1
949 lines and then to the beginning of the line. BUFFER defaults to
950 the current buffer if omitted.
952 If this function reaches the end of the buffer (or of the
953 accessible portion, if narrowing is in effect), it positions point
954 there. No error is signaled.
956 - Command: end-of-line &optional COUNT BUFFER
957 This function moves point to the end of the current line. With an
958 argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
959 then to the end of the line. BUFFER defaults to the current
962 If this function reaches the end of the buffer (or of the
963 accessible portion, if narrowing is in effect), it positions point
964 there. No error is signaled.
966 - Command: forward-line &optional COUNT BUFFER
967 This function moves point forward COUNT lines, to the beginning of
968 the line. If COUNT is negative, it moves point -COUNT lines
969 backward, to the beginning of a line. If COUNT is zero, it moves
970 point to the beginning of the current line. BUFFER defaults to
971 the current buffer if omitted.
973 If `forward-line' encounters the beginning or end of the buffer (or
974 of the accessible portion) before finding that many lines, it sets
975 point there. No error is signaled.
977 `forward-line' returns the difference between COUNT and the number
978 of lines actually moved. If you attempt to move down five lines
979 from the beginning of a buffer that has only three lines, point
980 stops at the end of the last line, and the value will be 2.
982 In an interactive call, COUNT is the numeric prefix argument.
984 - Function: count-lines START END
985 This function returns the number of lines between the positions
986 START and END in the current buffer. If START and END are equal,
987 then it returns 0. Otherwise it returns at least 1, even if START
988 and END are on the same line. This is because the text between
989 them, considered in isolation, must contain at least one line
992 Here is an example of using `count-lines':
994 (defun current-line ()
995 "Return the vertical position of point..."
996 (+ (count-lines (window-start) (point))
997 (if (= (current-column) 0) 1 0)
1000 Also see the functions `bolp' and `eolp' in *Note Near Point::.
1001 These functions do not move point, but test whether it is already at the
1002 beginning or end of a line.
1005 File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
1007 Motion by Screen Lines
1008 ----------------------
1010 The line functions in the previous section count text lines,
1011 delimited only by newline characters. By contrast, these functions
1012 count screen lines, which are defined by the way the text appears on
1013 the screen. A text line is a single screen line if it is short enough
1014 to fit the width of the selected window, but otherwise it may occupy
1015 several screen lines.
1017 In some cases, text lines are truncated on the screen rather than
1018 continued onto additional screen lines. In these cases,
1019 `vertical-motion' moves point much like `forward-line'. *Note
1022 Because the width of a given string depends on the flags that control
1023 the appearance of certain characters, `vertical-motion' behaves
1024 differently, for a given piece of text, depending on the buffer it is
1025 in, and even on the selected window (because the width, the truncation
1026 flag, and display table may vary between windows). *Note Usual
1029 These functions scan text to determine where screen lines break, and
1030 thus take time proportional to the distance scanned. If you intend to
1031 use them heavily, Emacs provides caches which may improve the
1032 performance of your code. *Note cache-long-line-scans: Text Lines.
1034 - Function: vertical-motion COUNT &optional WINDOW PIXELS
1035 This function moves point to the start of the frame line COUNT
1036 frame lines down from the frame line containing point. If COUNT
1037 is negative, it moves up instead. The optional second argument
1038 WINDOW may be used to specify a window other than the selected
1039 window in which to perform the motion.
1041 Normally, `vertical-motion' returns the number of lines moved. The
1042 value may be less in absolute value than COUNT if the beginning or
1043 end of the buffer was reached. If the optional third argument,
1044 PIXELS is non-`nil', the vertical pixel height of the motion which
1045 took place is returned instead of the actual number of lines
1046 moved. A motion of zero lines returns the height of the current
1049 Note that `vertical-motion' sets WINDOW's buffer's point, not
1050 WINDOW's point. (This differs from FSF Emacs, which buggily always
1051 sets current buffer's point, regardless of WINDOW.)
1053 - Function: vertical-motion-pixels COUNT &optional WINDOW HOW
1054 This function moves point to the start of the frame line PIXELS
1055 vertical pixels down from the frame line containing point, or up if
1056 PIXELS is negative. The optional second argument WINDOW is the
1057 window to move in, and defaults to the selected window. The
1058 optional third argument HOW specifies the stopping condition. A
1059 negative integer indicates that the motion should be no more than
1060 PIXELS. A positive value indicates that the motion should be at
1061 least PIXELS. Any other value indicates that the motion should be
1062 as close as possible to PIXELS.
1064 - Command: move-to-window-line COUNT &optional WINDOW
1065 This function moves point with respect to the text currently
1066 displayed in WINDOW, which defaults to the selected window. It
1067 moves point to the beginning of the screen line COUNT screen lines
1068 from the top of the window. If COUNT is negative, that specifies a
1069 position -COUNT lines from the bottom (or the last line of the
1070 buffer, if the buffer ends above the specified screen position).
1072 If COUNT is `nil', then point moves to the beginning of the line
1073 in the middle of the window. If the absolute value of COUNT is
1074 greater than the size of the window, then point moves to the place
1075 that would appear on that screen line if the window were tall
1076 enough. This will probably cause the next redisplay to scroll to
1077 bring that location onto the screen.
1079 In an interactive call, COUNT is the numeric prefix argument.
1081 The value returned is the window line number point has moved to,
1082 with the top line in the window numbered 0.
1085 File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
1087 Moving over Balanced Expressions
1088 --------------------------------
1090 Here are several functions concerned with balanced-parenthesis
1091 expressions (also called "sexps" in connection with moving across them
1092 in XEmacs). The syntax table controls how these functions interpret
1093 various characters; see *Note Syntax Tables::. *Note Parsing
1094 Expressions::, for lower-level primitives for scanning sexps or parts of
1095 sexps. For user-level commands, see *Note Lists and Sexps:
1096 (emacs)Lists and Sexps.
1098 - Command: forward-list &optional ARG
1099 This function moves forward across ARG balanced groups of
1100 parentheses. (Other syntactic entities such as words or paired
1101 string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
1102 is negative, move backward across that many groups of parentheses.
1104 - Command: backward-list &optional ARG
1105 This function moves backward across ARG balanced groups of
1106 parentheses. (Other syntactic entities such as words or paired
1107 string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
1108 is negative, move forward across that many groups of parentheses.
1110 - Command: up-list ARG
1111 This function moves forward out of ARG levels of parentheses. A
1112 negative argument means move backward but still to a less deep
1115 - Command: down-list ARG
1116 This function moves forward into ARG levels of parentheses. A
1117 negative argument means move backward but still go deeper in
1118 parentheses (-ARG levels).
1120 - Command: forward-sexp &optional ARG
1121 This function moves forward across ARG balanced expressions.
1122 Balanced expressions include both those delimited by parentheses
1123 and other kinds, such as words and string constants. ARG defaults
1124 to 1 if omitted. If ARG is negative, move backward across that
1125 many balanced expressions. For example,
1127 ---------- Buffer: foo ----------
1128 (concat-!- "foo " (car x) y z)
1129 ---------- Buffer: foo ----------
1134 ---------- Buffer: foo ----------
1135 (concat "foo " (car x) y-!- z)
1136 ---------- Buffer: foo ----------
1138 - Command: backward-sexp &optional ARG
1139 This function moves backward across ARG balanced expressions. ARG
1140 defaults to 1 if omitted. If ARG is negative, move forward across
1141 that many balanced expressions.
1143 - Command: beginning-of-defun &optional ARG
1144 This function moves back to the ARGth beginning of a defun. If
1145 ARG is negative, this actually moves forward, but it still moves
1146 to the beginning of a defun, not to the end of one. ARG defaults
1149 - Command: end-of-defun &optional ARG
1150 This function moves forward to the ARGth end of a defun. If ARG
1151 is negative, this actually moves backward, but it still moves to
1152 the end of a defun, not to the beginning of one. ARG defaults to
1155 - User Option: defun-prompt-regexp
1156 If non-`nil', this variable holds a regular expression that
1157 specifies what text can appear before the open-parenthesis that
1158 starts a defun. That is to say, a defun begins on a line that
1159 starts with a match for this regular expression, followed by a
1160 character with open-parenthesis syntax.
1163 File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
1168 The following two functions move point over a specified set of
1169 characters. For example, they are often used to skip whitespace. For
1170 related functions, see *Note Motion and Syntax::.
1172 - Function: skip-chars-forward CHARACTER-SET &optional LIMIT BUFFER
1173 This function moves point in BUFFER forward, skipping over a given
1174 set of characters. It examines the character following point,
1175 then advances point if the character matches CHARACTER-SET. This
1176 continues until it reaches a character that does not match. The
1177 function returns `nil'. BUFFER defaults to the current buffer if
1180 The argument CHARACTER-SET is like the inside of a `[...]' in a
1181 regular expression except that `]' is never special and `\' quotes
1182 `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
1183 stopping before the first non-letter, and `"^a-zA-Z'" skips
1184 non-letters stopping before the first letter. *Note Regular
1187 If LIMIT is supplied (it must be a number or a marker), it
1188 specifies the maximum position in the buffer that point can be
1189 skipped to. Point will stop at or before LIMIT.
1191 In the following example, point is initially located directly
1192 before the `T'. After the form is evaluated, point is located at
1193 the end of that line (between the `t' of `hat' and the newline).
1194 The function skips all letters and spaces, but not newlines.
1196 ---------- Buffer: foo ----------
1197 I read "-!-The cat in the hat
1199 ---------- Buffer: foo ----------
1201 (skip-chars-forward "a-zA-Z ")
1204 ---------- Buffer: foo ----------
1205 I read "The cat in the hat-!-
1207 ---------- Buffer: foo ----------
1209 - Function: skip-chars-backward CHARACTER-SET &optional LIMIT BUFFER
1210 This function moves point backward, skipping characters that match
1211 CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
1212 except for the direction of motion.
projects / chise / xemacs-chise.git.1 / blob