1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
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 which-frames which-devices
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 defaults to the selected
81 The second argument, WHICH-FRAMES, says which frames to consider:
84 Consider only frames that are visible.
87 Consider only frames that are iconic.
90 Consider only frames that are invisible (this is different
94 Consider frames that are visible or iconic.
97 Consider frames that are invisible or iconic.
100 Consider all frames except minibuffer-only ones.
103 Like `visible' but omits minibuffer-only frames.
106 Like `iconic' but omits minibuffer-only frames.
109 Like `invisible' but omits minibuffer-only frames.
111 `visible-iconic-nomini'
112 Like `visible-iconic' but omits minibuffer-only frames.
114 `invisible-iconic-nomini'
115 Like `invisible-iconic' but omits minibuffer-only frames.
118 Identical to `nomini'.
121 Consider only the window WINDOW's frame and any frame now
122 using WINDOW as the minibuffer.
127 The optional argument WHICH-DEVICES further clarifies on which
128 devices to search for frames as specified by WHICH-FRAMES.
131 Consider all devices on the selected console.
134 Consider only the one device DEVICE.
137 Consider all devices on CONSOLE.
140 Consider all devices with device type DEVICE-TYPE.
143 Consider all devices on window system consoles.
146 Consider all devices without restriction.
148 - Function: previous-frame &optional frame which-frames which-devices
149 Like `next-frame', but cycles through all frames in the opposite
152 See also `next-window' and `previous-window', in *Note Cyclic Window
156 File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
161 Each window is part of one and only one frame; you can get the frame
164 - Function: frame-root-window &optional frame
165 This returns the root window of frame FRAME. FRAME defaults to
166 the selected frame if not specified.
168 - Function: window-frame &optional window
169 This function returns the frame that WINDOW is on. WINDOW
170 defaults to the selected window if omitted.
172 All the non-minibuffer windows in a frame are arranged in a cyclic
173 order. The order runs from the frame's top window, which is at the
174 upper left corner, down and to the right, until it reaches the window at
175 the lower right corner (always the minibuffer window, if the frame has
176 one), and then it moves back to the top.
178 - Function: frame-highest-window &optional frame position
179 This function returns the topmost, leftmost window of frame FRAME
180 at position POSITION.
182 If omitted, FRAME defaults to the currently selected frame.
184 POSITION is used to distinguish between multiple windows that abut
185 the top of the frame: 0 means the leftmost window abutting the top
186 of the frame, 1 the next-leftmost, etc. POSITION can also be less
187 than zero: -1 means the rightmost window abutting the top of the
188 frame, -2 the next-rightmost, etc. If omitted, POSITION defaults
189 to 0, i.e. the leftmost highest window. If there is no window at
190 the given POSITION, `nil' is returned.
192 The following three functions work similarly.
194 - Function: frame-lowest-window &optional frame position
195 This function returns the lowest window on FRAME which is at
198 - Function: frame-leftmost-window &optional frame position
199 This function returns the leftmost window on FRAME which is at
202 - Function: frame-rightmost-window &optional frame position
203 This function returns the rightmost window on FRAME which is at
206 At any time, exactly one window on any frame is "selected within the
207 frame". The significance of this designation is that selecting the
208 frame also selects this window. You can get the frame's current
209 selected window with `frame-selected-window'.
211 - Function: frame-selected-window &optional frame
212 This function returns the window on FRAME that is selected within
213 FRAME. FRAME defaults to the selected frame if not specified.
215 Conversely, selecting a window for XEmacs with `select-window' also
216 makes that window selected within its frame. *Note Selecting Windows::.
218 Another function that (usually) returns one of the windows in a
219 frame is `minibuffer-window'. *Note Minibuffer Misc::.
222 File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
224 Minibuffers and Frames
225 ======================
227 Normally, each frame has its own minibuffer window at the bottom,
228 which is used whenever that frame is selected. If the frame has a
229 minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
232 However, you can also create a frame with no minibuffer. Such a
233 frame must use the minibuffer window of some other frame. When you
234 create the frame, you can specify explicitly the minibuffer window to
235 use (in some other frame). If you don't, then the minibuffer is found
236 in the frame which is the value of the variable
237 `default-minibuffer-frame'. Its value should be a frame which does
240 - Variable: default-minibuffer-frame
241 This variable specifies the frame to use for the minibuffer
245 File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
250 At any time, one frame in XEmacs is the "selected frame". The
251 selected window always resides on the selected frame. As the focus
252 moves from device to device, the selected frame on each device is
253 remembered and restored when the focus moves back to that device.
255 - Function: selected-frame &optional device
256 This function returns the selected frame on DEVICE. If DEVICE is
257 not specified, the selected device will be used. If no frames
258 exist on the device, `nil' is returned.
260 The X server normally directs keyboard input to the X window that the
261 mouse is in. Some window managers use mouse clicks or keyboard events
262 to "shift the focus" to various X windows, overriding the normal
263 behavior of the server.
265 Lisp programs can switch frames "temporarily" by calling the
266 function `select-frame'. This does not override the window manager;
267 rather, it escapes from the window manager's control until that control
268 is somehow reasserted.
270 When using a text-only terminal, there is no window manager;
271 therefore, `select-frame' is the only way to switch frames, and the
272 effect lasts until overridden by a subsequent call to `select-frame'.
273 Only the selected terminal frame is actually displayed on the terminal.
274 Each terminal screen except for the initial one has a number, and the
275 number of the selected frame appears in the mode line after the word
276 `XEmacs' (*note Modeline Variables::).
278 - Function: select-frame frame
279 This function selects frame FRAME, temporarily disregarding the
280 focus of the X server if any. The selection of FRAME lasts until
281 the next time the user does something to select a different frame,
282 or until the next time this function is called.
284 Note that `select-frame' does not actually cause the window-system
285 focus to be set to this frame, or the `select-frame-hook' or
286 `deselect-frame-hook' to be run, until the next time that XEmacs is
287 waiting for an event.
289 Also note that when the variable `focus-follows-mouse' is
290 non-`nil', the frame selection is temporary and is reverted when
291 the current command terminates, much like the buffer selected by
292 `set-buffer'. In order to effect a permanent focus change use
295 - Function: focus-frame frame
296 This function selects FRAME and gives it the window system focus.
297 The operation of `focus-frame' is not affected by the value of
298 `focus-follows-mouse'.
300 - Special Form: save-selected-frame forms...
301 This special form records the selected frame, executes FORMS in
302 sequence, then restores the earlier selected frame. The value
303 returned is the value of the last form.
305 - Special Form: with-selected-frame frame forms...
306 This special form records the selected frame, then selects FRAME
307 and executes FORMS in sequence. After the last form is finished,
308 the earlier selected frame is restored. The value returned is the
309 value of the last form.
312 File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
317 An frame on a window system may be "visible", "invisible", or
318 "iconified". If it is visible, you can see its contents. If it is
319 iconified, the frame's contents do not appear on the screen, but an icon
320 does. If the frame is invisible, it doesn't show on the screen, not
323 Visibility is meaningless for TTY frames, since only the selected
324 one is actually displayed in any case.
326 - Function: make-frame-visible &optional frame
327 This function makes frame FRAME visible. If you omit FRAME, it
328 makes the selected frame visible.
330 - Function: make-frame-invisible &optional frame force
331 This function makes frame FRAME invisible.
333 - Command: iconify-frame &optional frame
334 This function iconifies frame FRAME.
336 - Function: Command deiconify-frame &optional frame
337 This function de-iconifies frame FRAME. Under a window system,
338 this is equivalent to `make-frame-visible'.
340 - Function: frame-visible-p &optional frame
341 This returns whether FRAME is currently "visible" (actually in use
342 for display). A frame that is not visible is not updated, and, if
343 it works through a window system, may not show at all.
345 - Function: frame-iconified-p &optional frame
346 This returns whether FRAME is iconified. Not all window managers
347 use icons; some merely unmap the window, so this function is not
348 the inverse of `frame-visible-p'. It is possible for a frame to
349 not be visible and not be iconified either. However, if the frame
350 is iconified, it will not be visible. (Under FSF Emacs, the
351 functionality of this function is obtained through
354 - Function: frame-totally-visible-p &optional frame
355 This returns whether FRAME is not obscured by any other X windows.
356 On TTY frames, this is the same as `frame-visible-p'.
359 File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
361 Raising and Lowering Frames
362 ===========================
364 The X Window System uses a desktop metaphor. Part of this metaphor
365 is the idea that windows are stacked in a notional third dimension
366 perpendicular to the screen surface, and thus ordered from "highest" to
367 "lowest". Where two windows overlap, the one higher up covers the one
368 underneath. Even a window at the bottom of the stack can be seen if no
369 other window overlaps it.
371 A window's place in this ordering is not fixed; in fact, users tend
372 to change the order frequently. "Raising" a window means moving it
373 "up", to the top of the stack. "Lowering" a window means moving it to
374 the bottom of the stack. This motion is in the notional third
375 dimension only, and does not change the position of the window on the
378 You can raise and lower XEmacs's X windows with these functions:
380 - Command: raise-frame &optional frame
381 This function raises frame FRAME.
383 - Command: lower-frame &optional frame
384 This function lowers frame FRAME.
386 You can also specify auto-raise (raising automatically when a frame
387 is selected) or auto-lower (lowering automatically when it is
388 deselected). Under X, most ICCCM-compliant window managers will have
389 an option to do this for you, but the following variables are provided
390 in case you're using a broken WM. (Under FSF Emacs, the same
391 functionality is provided through the `auto-raise' and `auto-lower'
394 - Variable: auto-raise-frame
395 This variable's value is `t' if frames will be raised to the top
398 - Variable: auto-lower-frame
399 This variable's value is `t' if frames will be lowered to the
400 bottom when no longer selected.
402 Auto-raising and auto-lowering is implemented through functions
403 attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
404 Hooks::). Under normal circumstances, you should not call these
407 - Function: default-select-frame-hook
408 This hook function implements the `auto-raise-frame' variable; it
409 is for use as the value of `select-frame-hook'.
411 - Function: default-deselect-frame-hook
412 This hook function implements the `auto-lower-frame' variable; it
413 is for use as the value of `deselect-frame-hook'.
416 File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
421 A "frame configuration" records the current arrangement of frames,
422 all their properties, and the window configuration of each one.
424 - Function: current-frame-configuration
425 This function returns a frame configuration list that describes
426 the current arrangement of frames and their contents.
428 - Function: set-frame-configuration configuration &optional nodelete
429 This function restores the state of frames described by
430 CONFIGURATION, which should be the return value from a previous
431 call to `current-frame-configuration'.
433 Each frame listed in CONFIGURATION has its position, size, window
434 configuration, and other properties set as specified in
437 Ordinarily, this function deletes all existing frames not listed in
438 CONFIGURATION. But if optional second argument NODELETE is
439 non-`nil', the unwanted frames are iconified instead.
442 File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames
444 Hooks for Customizing Frame Behavior
445 ====================================
447 XEmacs provides many hooks that are called at various times during a
448 frame's lifetime. *Note Hooks::.
450 - Variable: create-frame-hook
451 This hook is called each time a frame is created. The functions
452 are called with one argument, the newly-created frame.
454 - Variable: delete-frame-hook
455 This hook is called each time a frame is deleted. The functions
456 are called with one argument, the about-to-be-deleted frame.
458 - Variable: select-frame-hook
459 This is a normal hook that is run just after a frame is selected.
460 The function `default-select-frame-hook', which implements
461 auto-raising (*note Raising and Lowering::), is normally attached
464 Note that calling `select-frame' does not necessarily set the
465 focus: The actual window-system focus will not be changed until
466 the next time that XEmacs is waiting for an event, and even then,
467 the window manager may refuse the focus-change request.
469 - Variable: deselect-frame-hook
470 This is a normal hook that is run just before a frame is deselected
471 (and another frame is selected). The function
472 `default-deselect-frame-hook', which implements auto-lowering
473 (*note Raising and Lowering::), is normally attached to this hook.
475 - Variable: map-frame-hook
476 This hook is called each time a frame is mapped (i.e. made
477 visible). The functions are called with one argument, the newly
480 - Variable: unmap-frame-hook
481 This hook is called each time a frame is unmapped (i.e. made
482 invisible or iconified). The functions are called with one
483 argument, the newly unmapped frame.
486 File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top
491 A "console" is an object representing a single input connection to
492 XEmacs, such as an X display or a TTY connection. It is possible for
493 XEmacs to have frames on multiple consoles at once (even on
494 heterogeneous types--you can simultaneously have a frame on an X
495 display and a TTY connection). Normally, there is only one console in
498 A "device" is an object representing a single output device, such as
499 a particular screen on an X display. (Usually there is exactly one
500 device per X console connection, but there may be more than one if you
501 have a multi-headed X display. For TTY connections, there is always
502 exactly one device per console.)
504 Each device has one or more "frames" in which text can be displayed.
505 For X displays and the like, a frame corresponds to the normal
506 window-system concept of a window. Frames can overlap, be displayed at
507 various locations within the display, be resized, etc. For TTY, only
508 one frame can be displayed at a time, and it occupies the entire TTY
511 However, you can still define multiple frames and switch between
512 them. Their contents are entirely separate from each other. These
513 sorts of frames resemble the "virtual console" capability provided
514 under Linux or the multiple screens provided by the multiplexing program
517 When you start up XEmacs, an initial console and device are created
518 to receive input and display frames on. This will either be an X
519 display or a TTY connection, depending on what mode you started XEmacs
520 in (this is determined by the `DISPLAY' environment variable, the
521 `-nw', `-t' and `-display' command-line options, etc.).
523 You can connect to other X displays and TTY connections by creating
524 new console objects, and to other X screens on an existing display by
525 creating new device objects, as described below. Many functions (for
526 example the frame-creation functions) take an optional device argument
527 specifying which device the function pertains to. If the argument is
528 omitted, it defaults to the selected device (see below).
530 - Function: consolep object
531 This returns non-`nil' if OBJECT is a console.
533 - Function: devicep object
534 This returns non-`nil' if OBJECT is a device.
538 * Basic Console Functions:: Functions for working with consoles.
539 * Basic Device Functions:: Functions for working with devices.
540 * Console Types and Device Classes::
541 I/O and color characteristics.
542 * Connecting to a Console or Device::
543 * The Selected Console and Device::
544 * Console and Device I/O:: Controlling input and output.
547 File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices
549 Basic Console Functions
550 =======================
552 - Function: console-list
553 This function returns a list of all existing consoles.
555 - Function: console-device-list &optional console
556 This function returns a list of all devices on CONSOLE. If
557 CONSOLE is `nil', the selected console will be used.
560 File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices
562 Basic Device Functions
563 ======================
565 - Function: device-list
566 This function returns a list of all existing devices.
568 - Function: device-or-frame-p object
569 This function returns non-`nil' if OBJECT is a device or frame.
570 This function is useful because devices and frames are similar in
571 many respects and many functions can operate on either one.
573 - Function: device-frame-list &optional device
574 This function returns a list of all frames on DEVICE. DEVICE
575 defaults to the currently selected device.
577 - Function: frame-device &optional frame
578 This function returns the device that FRAME is on. FRAME defaults
579 to the currently selected frame.
582 File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices
584 Console Types and Device Classes
585 ================================
587 Every device is of a particular "type", which describes how the
588 connection to that device is made and how the device operates, and a
589 particular "class", which describes other characteristics of the device
590 (currently, the color capabilities of the device).
592 The currently-defined device types are
595 A connection to an X display (such as `willow:0').
598 A connection to a tty (such as `/dev/ttyp3').
601 A stdio connection. This describes a device for which input and
602 output is only possible in a stream-like fashion, such as when
603 XEmacs in running in batch mode. The very first device created by
604 XEmacs is a terminal device and is used to print out messages of
605 various sorts (for example, the help message when you use the
606 `-help' command-line option).
608 The currently-defined device classes are
613 A grayscale device (a device that can display multiple shades of
617 A device that can only display two colors (e.g. black and white).
619 - Function: device-type &optional device
620 This function returns the type of DEVICE. This is a symbol whose
621 name is one of the device types mentioned above. DEVICE defaults
622 to the selected device.
624 - Function: device-or-frame-type device-or-frame
625 This function returns the type of DEVICE-OR-FRAME.
627 - Function: device-class &optional device
628 This function returns the class (color behavior) of DEVICE. This
629 is a symbol whose name is one of the device classes mentioned
632 - Function: valid-device-type-p device-type
633 This function returns whether DEVICE-TYPE (which should be a
634 symbol) specifies a valid device type.
636 - Function: valid-device-class-p device-class
637 This function returns whether DEVICE-CLASS (which should be a
638 symbol) specifies a valid device class.
640 - Variable: terminal-device
641 This variable holds the initial terminal device object, which
642 represents XEmacs's stdout.
645 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
647 Connecting to a Console or Device
648 =================================
650 - Function: make-device type connection &optional props
651 This function creates a new device.
653 The following two functions create devices of specific types and are
654 written in terms of `make-device'.
656 - Function: make-tty-device &optional tty terminal-type
657 This function creates a new tty device on TTY. This also creates
658 the tty's first frame. TTY should be a string giving the name of
659 a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
660 returned by the `tty' command issued from the Unix shell. A value
661 of `nil' means use the stdin and stdout as passed to XEmacs from
662 the shell. If TERMINAL-TYPE is non-`nil', it should be a string
663 specifying the type of the terminal attached to the specified tty.
664 If it is `nil', the terminal type will be inferred from the
665 `TERM' environment variable.
667 - Function: make-x-device &optional display argv-list
668 This function creates a new device connected to DISPLAY. Optional
669 argument ARGV-LIST is a list of strings describing command line
672 - Function: delete-device device &optional force
673 This function deletes DEVICE, permanently eliminating it from use.
674 This disconnects XEmacs's connection to the device.
676 - Variable: create-device-hook
677 This variable, if non-`nil', should contain a list of functions,
678 which are called when a device is created.
680 - Variable: delete-device-hook
681 This variable, if non-`nil', should contain a list of functions,
682 which are called when a device is deleted.
684 - Function: console-live-p object
685 This function returns non-`nil' if OBJECT is a console that has
688 - Function: device-live-p object
689 This function returns non-`nil' if OBJECT is a device that has not
692 - Function: device-x-display device
693 This function returns the X display which DEVICE is connected to,
694 if DEVICE is an X device.
697 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
699 The Selected Console and Device
700 ===============================
702 - Function: select-console console
703 This function selects the console CONSOLE. Subsequent editing
704 commands apply to its selected device, selected frame, and selected
705 window. The selection of CONSOLE lasts until the next time the
706 user does something to select a different console, or until the
707 next time this function is called.
709 - Function: selected-console
710 This function returns the console which is currently active.
712 - Function: select-device device
713 This function selects the device DEVICE.
715 - Function: selected-device &optional console
716 This function returns the device which is currently active. If
717 optional CONSOLE is non-`nil', this function returns the device
718 that would be currently active if CONSOLE were the selected
722 File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
724 Console and Device I/O
725 ======================
727 - Function: console-disable-input console
728 This function disables input on console CONSOLE.
730 - Function: console-enable-input console
731 This function enables input on console CONSOLE.
733 Each device has a "baud rate" value associated with it. On most
734 systems, changing this value will affect the amount of padding and
735 other strategic decisions made during redisplay.
737 - Function: device-baud-rate &optional device
738 This function returns the output baud rate of DEVICE.
740 - Function: set-device-baud-rate device rate
741 This function sets the output baud rate of DEVICE to RATE.
744 File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
749 A "position" is the index of a character in the text of a buffer.
750 More precisely, a position identifies the place between two characters
751 (or before the first character, or after the last character), so we can
752 speak of the character before or after a given position. However, we
753 often speak of the character "at" a position, meaning the character
756 Positions are usually represented as integers starting from 1, but
757 can also be represented as "markers"--special objects that relocate
758 automatically when text is inserted or deleted so they stay with the
759 surrounding characters. *Note Markers::.
763 * Point:: The special position where editing takes place.
764 * Motion:: Changing point.
765 * Excursions:: Temporary motion and buffer changes.
766 * Narrowing:: Restricting editing to a portion of the buffer.
769 File: lispref.info, Node: Point, Next: Motion, Up: Positions
774 "Point" is a special buffer position used by many editing commands,
775 including the self-inserting typed characters and text insertion
776 functions. Other commands move point through the text to allow editing
777 and insertion at different places.
779 Like other positions, point designates a place between two characters
780 (or before the first character, or after the last character), rather
781 than a particular character. Usually terminals display the cursor over
782 the character that immediately follows point; point is actually before
783 the character on which the cursor sits.
785 The value of point is a number between 1 and the buffer size plus 1.
786 If narrowing is in effect (*note Narrowing::), then point is constrained
787 to fall within the accessible portion of the buffer (possibly at one end
790 Each buffer has its own value of point, which is independent of the
791 value of point in other buffers. Each window also has a value of point,
792 which is independent of the value of point in other windows on the same
793 buffer. This is why point can have different values in various windows
794 that display the same buffer. When a buffer appears in only one window,
795 the buffer's point and the window's point normally have the same value,
796 so the distinction is rarely important. *Note Window Point::, for more
799 - Function: point &optional buffer
800 This function returns the value of point in BUFFER, as an integer.
801 BUFFER defaults to the current buffer if omitted.
806 - Function: point-min &optional buffer
807 This function returns the minimum accessible value of point in
808 BUFFER. This is normally 1, but if narrowing is in effect, it is
809 the position of the start of the region that you narrowed to.
810 (*Note Narrowing::.) BUFFER defaults to the current buffer if
813 - Function: point-max &optional buffer
814 This function returns the maximum accessible value of point in
815 BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
816 in effect, in which case it is the position of the end of the
817 region that you narrowed to. (*note Narrowing::). BUFFER defaults
818 to the current buffer if omitted.
820 - Function: buffer-end flag &optional buffer
821 This function returns `(point-min buffer)' if FLAG is less than 1,
822 `(point-max buffer)' otherwise. The argument FLAG must be a
823 number. BUFFER defaults to the current buffer if omitted.
825 - Function: buffer-size &optional buffer
826 This function returns the total number of characters in BUFFER.
827 In the absence of any narrowing (*note Narrowing::), `point-max'
828 returns a value one larger than this. BUFFER defaults to the
829 current buffer if omitted.
836 - Variable: buffer-saved-size
837 The value of this buffer-local variable is the former length of the
838 current buffer, as of the last time it was read in, saved or
842 File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
847 Motion functions change the value of point, either relative to the
848 current value of point, relative to the beginning or end of the buffer,
849 or relative to the edges of the selected window. *Note Point::.
853 * Character Motion:: Moving in terms of characters.
854 * Word Motion:: Moving in terms of words.
855 * Buffer End Motion:: Moving to the beginning or end of the buffer.
856 * Text Lines:: Moving in terms of lines of text.
857 * Screen Lines:: Moving in terms of lines as displayed.
858 * List Motion:: Moving by parsing lists and sexps.
859 * Skipping Characters:: Skipping characters belonging to a certain set.
862 File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
867 These functions move point based on a count of characters.
868 `goto-char' is the fundamental primitive; the other functions use that.
870 - Command: goto-char position &optional buffer
871 This function sets point in `buffer' to the value POSITION. If
872 POSITION is less than 1, it moves point to the beginning of the
873 buffer. If POSITION is greater than the length of the buffer, it
874 moves point to the end. BUFFER defaults to the current buffer if
877 If narrowing is in effect, POSITION still counts from the
878 beginning of the buffer, but point cannot go outside the accessible
879 portion. If POSITION is out of range, `goto-char' moves point to
880 the beginning or the end of the accessible portion.
882 When this function is called interactively, POSITION is the
883 numeric prefix argument, if provided; otherwise it is read from the
886 `goto-char' returns POSITION.
888 - Command: forward-char &optional count buffer
889 This function moves point COUNT characters forward, towards the
890 end of the buffer (or backward, towards the beginning of the
891 buffer, if COUNT is negative). If the function attempts to move
892 point past the beginning or end of the buffer (or the limits of
893 the accessible portion, when narrowing is in effect), an error is
894 signaled with error code `beginning-of-buffer' or `end-of-buffer'.
895 BUFFER defaults to the current buffer if omitted.
897 In an interactive call, COUNT is the numeric prefix argument.
899 - Command: backward-char &optional count buffer
900 This function moves point COUNT characters backward, towards the
901 beginning of the buffer (or forward, towards the end of the
902 buffer, if COUNT is negative). If the function attempts to move
903 point past the beginning or end of the buffer (or the limits of
904 the accessible portion, when narrowing is in effect), an error is
905 signaled with error code `beginning-of-buffer' or `end-of-buffer'.
906 BUFFER defaults to the current buffer if omitted.
908 In an interactive call, COUNT is the numeric prefix argument.
911 File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
916 These functions for parsing words use the syntax table to decide
917 whether a given character is part of a word. *Note Syntax Tables::.
919 - Command: forward-word &optional count buffer
920 This function moves point forward COUNT words (or backward if
921 COUNT is negative). Normally it returns `t'. If this motion
922 encounters the beginning or end of the buffer, or the limits of the
923 accessible portion when narrowing is in effect, point stops there
924 and the value is `nil'.
926 COUNT defaults to `1' and BUFFER defaults to the current buffer.
928 In an interactive call, COUNT is set to the numeric prefix
931 - Command: backward-word &optional count buffer
932 This function is just like `forward-word', except that it moves
933 backward until encountering the front of a word, rather than
934 forward. BUFFER defaults to the current buffer if omitted.
936 In an interactive call, COUNT is set to the numeric prefix
939 - Variable: words-include-escapes
940 This variable affects the behavior of `forward-word' and everything
941 that uses it. If it is non-`nil', then characters in the "escape"
942 and "character quote" syntax classes count as part of words.
943 Otherwise, they do not.
946 File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
948 Motion to an End of the Buffer
949 ------------------------------
951 To move point to the beginning of the buffer, write:
953 (goto-char (point-min))
955 Likewise, to move to the end of the buffer, use:
957 (goto-char (point-max))
959 Here are two commands that users use to do these things. They are
960 documented here to warn you not to use them in Lisp programs, because
961 they set the mark and display messages in the echo area.
963 - Command: beginning-of-buffer &optional count
964 This function moves point to the beginning of the buffer (or the
965 limits of the accessible portion, when narrowing is in effect),
966 setting the mark at the previous position. If COUNT is non-`nil',
967 then it puts point COUNT tenths of the way from the beginning of
970 In an interactive call, COUNT is the numeric prefix argument, if
971 provided; otherwise COUNT defaults to `nil'.
973 Don't use this function in Lisp programs!
975 - Command: end-of-buffer &optional count
976 This function moves point to the end of the buffer (or the limits
977 of the accessible portion, when narrowing is in effect), setting
978 the mark at the previous position. If COUNT is non-`nil', then it
979 puts point COUNT tenths of the way from the end of the buffer.
981 In an interactive call, COUNT is the numeric prefix argument, if
982 provided; otherwise COUNT defaults to `nil'.
984 Don't use this function in Lisp programs!
987 File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
992 Text lines are portions of the buffer delimited by newline
993 characters, which are regarded as part of the previous line. The first
994 text line begins at the beginning of the buffer, and the last text line
995 ends at the end of the buffer whether or not the last character is a
996 newline. The division of the buffer into text lines is not affected by
997 the width of the window, by line continuation in display, or by how
998 tabs and control characters are displayed.
1000 - Command: goto-line line
1001 This function moves point to the front of the LINEth line,
1002 counting from line 1 at beginning of the buffer. If LINE is less
1003 than 1, it moves point to the beginning of the buffer. If LINE is
1004 greater than the number of lines in the buffer, it moves point to
1005 the end of the buffer--that is, the _end of the last line_ of the
1006 buffer. This is the only case in which `goto-line' does not
1007 necessarily move to the beginning of a line.
1009 If narrowing is in effect, then LINE still counts from the
1010 beginning of the buffer, but point cannot go outside the accessible
1011 portion. So `goto-line' moves point to the beginning or end of the
1012 accessible portion, if the line number specifies an inaccessible
1015 The return value of `goto-line' is the difference between LINE and
1016 the line number of the line to which point actually was able to
1017 move (in the full buffer, before taking account of narrowing).
1018 Thus, the value is positive if the scan encounters the real end of
1019 the buffer. The value is zero if scan encounters the end of the
1020 accessible portion but not the real end of the buffer.
1022 In an interactive call, LINE is the numeric prefix argument if one
1023 has been provided. Otherwise LINE is read in the minibuffer.
1025 - Command: beginning-of-line &optional count buffer
1026 This function moves point to the beginning of the current line.
1027 With an argument COUNT not `nil' or 1, it moves forward COUNT-1
1028 lines and then to the beginning of the line. BUFFER defaults to
1029 the current buffer if omitted.
1031 If this function reaches the end of the buffer (or of the
1032 accessible portion, if narrowing is in effect), it positions point
1033 there. No error is signaled.
1035 - Command: end-of-line &optional count buffer
1036 This function moves point to the end of the current line. With an
1037 argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
1038 then to the end of the line. BUFFER defaults to the current
1041 If this function reaches the end of the buffer (or of the
1042 accessible portion, if narrowing is in effect), it positions point
1043 there. No error is signaled.
1045 - Command: forward-line &optional count buffer
1046 This function moves point forward COUNT lines, to the beginning of
1047 the line. If COUNT is negative, it moves point -COUNT lines
1048 backward, to the beginning of a line. If COUNT is zero, it moves
1049 point to the beginning of the current line. BUFFER defaults to
1050 the current buffer if omitted.
1052 If `forward-line' encounters the beginning or end of the buffer (or
1053 of the accessible portion) before finding that many lines, it sets
1054 point there. No error is signaled.
1056 `forward-line' returns the difference between COUNT and the number
1057 of lines actually moved. If you attempt to move down five lines
1058 from the beginning of a buffer that has only three lines, point
1059 stops at the end of the last line, and the value will be 2.
1061 In an interactive call, COUNT is the numeric prefix argument.
1063 - Function: count-lines start end &optional ignore-invisible-lines-flag
1064 This function returns the number of lines between the positions
1065 START and END in the current buffer. If START and END are equal,
1066 then it returns 0. Otherwise it returns at least 1, even if START
1067 and END are on the same line. This is because the text between
1068 them, considered in isolation, must contain at least one line
1071 With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines
1072 collapsed with selective-display are excluded from the line count.
1074 *Note:* The expression to return the current line number is not
1077 (1+ (count-lines 1 (point-at-bol)))
1079 Here is an example of using `count-lines':
1081 (defun current-line ()
1082 "Return the vertical position of point..."
1083 (+ (count-lines (window-start) (point))
1084 (if (= (current-column) 0) 1 0)
1087 Also see the functions `bolp' and `eolp' in *Note Near Point::.
1088 These functions do not move point, but test whether it is already at the
1089 beginning or end of a line.
1092 File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
1094 Motion by Screen Lines
1095 ----------------------
1097 The line functions in the previous section count text lines,
1098 delimited only by newline characters. By contrast, these functions
1099 count screen lines, which are defined by the way the text appears on
1100 the screen. A text line is a single screen line if it is short enough
1101 to fit the width of the selected window, but otherwise it may occupy
1102 several screen lines.
1104 In some cases, text lines are truncated on the screen rather than
1105 continued onto additional screen lines. In these cases,
1106 `vertical-motion' moves point much like `forward-line'. *Note
1109 Because the width of a given string depends on the flags that control
1110 the appearance of certain characters, `vertical-motion' behaves
1111 differently, for a given piece of text, depending on the buffer it is
1112 in, and even on the selected window (because the width, the truncation
1113 flag, and display table may vary between windows). *Note Usual
1116 These functions scan text to determine where screen lines break, and
1117 thus take time proportional to the distance scanned. If you intend to
1118 use them heavily, Emacs provides caches which may improve the
1119 performance of your code. *Note cache-long-line-scans: Text Lines.
1121 - Function: vertical-motion count &optional window pixels
1122 This function moves point to the start of the frame line COUNT
1123 frame lines down from the frame line containing point. If COUNT
1124 is negative, it moves up instead. The optional second argument
1125 WINDOW may be used to specify a window other than the selected
1126 window in which to perform the motion.
1128 Normally, `vertical-motion' returns the number of lines moved. The
1129 value may be less in absolute value than COUNT if the beginning or
1130 end of the buffer was reached. If the optional third argument,
1131 PIXELS is non-`nil', the vertical pixel height of the motion which
1132 took place is returned instead of the actual number of lines
1133 moved. A motion of zero lines returns the height of the current
1136 Note that `vertical-motion' sets WINDOW's buffer's point, not
1137 WINDOW's point. (This differs from FSF Emacs, which buggily always
1138 sets current buffer's point, regardless of WINDOW.)
1140 - Function: vertical-motion-pixels count &optional window how
1141 This function moves point to the start of the frame line PIXELS
1142 vertical pixels down from the frame line containing point, or up if
1143 PIXELS is negative. The optional second argument WINDOW is the
1144 window to move in, and defaults to the selected window. The
1145 optional third argument HOW specifies the stopping condition. A
1146 negative integer indicates that the motion should be no more than
1147 PIXELS. A positive value indicates that the motion should be at
1148 least PIXELS. Any other value indicates that the motion should be
1149 as close as possible to PIXELS.
1151 - Command: move-to-window-line count &optional window
1152 This function moves point with respect to the text currently
1153 displayed in WINDOW, which defaults to the selected window. It
1154 moves point to the beginning of the screen line COUNT screen lines
1155 from the top of the window. If COUNT is negative, that specifies a
1156 position -COUNT lines from the bottom (or the last line of the
1157 buffer, if the buffer ends above the specified screen position).
1159 If COUNT is `nil', then point moves to the beginning of the line
1160 in the middle of the window. If the absolute value of COUNT is
1161 greater than the size of the window, then point moves to the place
1162 that would appear on that screen line if the window were tall
1163 enough. This will probably cause the next redisplay to scroll to
1164 bring that location onto the screen.
1166 In an interactive call, COUNT is the numeric prefix argument.
1168 The value returned is the window line number point has moved to,
1169 with the top line in the window numbered 0.
1172 File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
1174 Moving over Balanced Expressions
1175 --------------------------------
1177 Here are several functions concerned with balanced-parenthesis
1178 expressions (also called "sexps" in connection with moving across them
1179 in XEmacs). The syntax table controls how these functions interpret
1180 various characters; see *Note Syntax Tables::. *Note Parsing
1181 Expressions::, for lower-level primitives for scanning sexps or parts of
1182 sexps. For user-level commands, see *Note Lists and Sexps:
1183 (xemacs)Lists and Sexps.
1185 - Command: forward-list &optional arg
1186 This function moves forward across ARG balanced groups of
1187 parentheses. (Other syntactic entities such as words or paired
1188 string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
1189 is negative, move backward across that many groups of parentheses.
1191 - Command: backward-list &optional count
1192 This function moves backward across COUNT balanced groups of
1193 parentheses. (Other syntactic entities such as words or paired
1194 string quotes are ignored.) COUNT defaults to 1 if omitted. If
1195 COUNT is negative, move forward across that many groups of
1198 - Command: up-list &optional count
1199 This function moves forward out of COUNT levels of parentheses. A
1200 negative argument means move backward but still to a less deep
1203 - Command: down-list &optional count
1204 This function moves forward into COUNT levels of parentheses. A
1205 negative argument means move backward but still go deeper in
1206 parentheses (-COUNT levels).
1208 - Command: forward-sexp &optional count
1209 This function moves forward across COUNT balanced expressions.
1210 Balanced expressions include both those delimited by parentheses
1211 and other kinds, such as words and string constants. COUNT
1212 defaults to 1 if omitted. If COUNT is negative, move backward
1213 across that many balanced expressions. For example,
1215 ---------- Buffer: foo ----------
1216 (concat-!- "foo " (car x) y z)
1217 ---------- Buffer: foo ----------
1222 ---------- Buffer: foo ----------
1223 (concat "foo " (car x) y-!- z)
1224 ---------- Buffer: foo ----------
1226 - Command: backward-sexp &optional count
1227 This function moves backward across COUNT balanced expressions.
1228 COUNT defaults to 1 if omitted. If COUNT is negative, move
1229 forward across that many balanced expressions.
1231 - Command: beginning-of-defun &optional count
1232 This function moves back to the COUNTth beginning of a defun. If
1233 COUNT is negative, this actually moves forward, but it still moves
1234 to the beginning of a defun, not to the end of one. COUNT
1235 defaults to 1 if omitted.
1237 - Command: end-of-defun &optional count
1238 This function moves forward to the COUNTth end of a defun. If
1239 COUNT is negative, this actually moves backward, but it still
1240 moves to the end of a defun, not to the beginning of one. COUNT
1241 defaults to 1 if omitted.
1243 - User Option: defun-prompt-regexp
1244 If non-`nil', this variable holds a regular expression that
1245 specifies what text can appear before the open-parenthesis that
1246 starts a defun. That is to say, a defun begins on a line that
1247 starts with a match for this regular expression, followed by a
1248 character with open-parenthesis syntax.
projects / chise / xemacs-chise.git- / blob