-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
-
-Excursions
-==========
-
- It is often useful to move point "temporarily" within a localized
-portion of the program, or to switch buffers temporarily. This is
-called an "excursion", and it is done with the `save-excursion' special
-form. This construct saves the current buffer and its values of point
-and the mark so they can be restored after the completion of the
-excursion.
-
- The forms for saving and restoring the configuration of windows are
-described elsewhere (see *Note Window Configurations:: and *note Frame
-Configurations::.).
-
- - Special Form: save-excursion FORMS...
- The `save-excursion' special form saves the identity of the current
- buffer and the values of point and the mark in it, evaluates
- FORMS, and finally restores the buffer and its saved values of
- point and the mark. All three saved values are restored even in
- case of an abnormal exit via `throw' or error (*note Nonlocal
- Exits::.).
-
- The `save-excursion' special form is the standard way to switch
- buffers or move point within one part of a program and avoid
- affecting the rest of the program. It is used more than 500 times
- in the Lisp sources of XEmacs.
-
- `save-excursion' does not save the values of point and the mark for
- other buffers, so changes in other buffers remain in effect after
- `save-excursion' exits.
-
- Likewise, `save-excursion' does not restore window-buffer
- correspondences altered by functions such as `switch-to-buffer'.
- One way to restore these correspondences, and the selected window,
- is to use `save-window-excursion' inside `save-excursion' (*note
- Window Configurations::.).
-
- The value returned by `save-excursion' is the result of the last of
- FORMS, or `nil' if no FORMS are given.
-
- (save-excursion
- FORMS)
- ==
- (let ((old-buf (current-buffer))
- (old-pnt (point-marker))
- (old-mark (copy-marker (mark-marker))))
- (unwind-protect
- (progn FORMS)
- (set-buffer old-buf)
- (goto-char old-pnt)
- (set-marker (mark-marker) old-mark)))
-
- - Special Form: save-current-buffer FORMS...
- This special form is similar to `save-excursion' but it only saves
- and restores the current buffer. Beginning with XEmacs 20.3,
- `save-current-buffer' is a primitive.
-
- - Special Form: with-current-buffer BUFFER FORMS...
- This special form evaluates FORMS with BUFFER as the current
- buffer. It returns the value of the last form.
-
- - Special Form: with-temp-file FILE FORMS...
- This special form creates a new buffer, evaluates FORMS there, and
- writes the buffer to FILE. It returns the value of the last form
- evaluated.
-
- - Special Form: save-selected-window FORMS...
- This special form is similar to `save-excursion' but it saves and
- restores the selected window and nothing else.
+File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
+
+Finding All Frames
+==================
+
+ - Function: frame-list
+ The function `frame-list' returns a list of all the frames that
+ have not been deleted. It is analogous to `buffer-list' for
+ buffers. The list that you get is newly created, so modifying the
+ list doesn't have any effect on the internals of XEmacs.
+
+ - Function: device-frame-list &optional device
+ This function returns a list of all frames on DEVICE. If DEVICE
+ is `nil', the selected device will be used.
+
+ - Function: visible-frame-list &optional device
+ This function returns a list of just the currently visible frames.
+ If DEVICE is specified only frames on that device will be returned.
+ *Note Visibility of Frames::. (TTY frames always count as
+ "visible", even though only the selected one is actually
+ displayed.)
+
+ - Function: next-frame &optional frame which-frames which-devices
+ The function `next-frame' lets you cycle conveniently through all
+ the frames from an arbitrary starting point. It returns the "next"
+ frame after FRAME in the cycle. If FRAME defaults to the selected
+ frame.
+
+ The second argument, WHICH-FRAMES, says which frames to consider:
+
+ `visible'
+ Consider only frames that are visible.
+
+ `iconic'
+ Consider only frames that are iconic.
+
+ `invisible'
+ Consider only frames that are invisible (this is different
+ from iconic).
+
+ `visible-iconic'
+ Consider frames that are visible or iconic.
+
+ `invisible-iconic'
+ Consider frames that are invisible or iconic.
+
+ `nomini'
+ Consider all frames except minibuffer-only ones.
+
+ `visible-nomini'
+ Like `visible' but omits minibuffer-only frames.
+
+ `iconic-nomini'
+ Like `iconic' but omits minibuffer-only frames.
+
+ `invisible-nomini'
+ Like `invisible' but omits minibuffer-only frames.
+
+ `visible-iconic-nomini'
+ Like `visible-iconic' but omits minibuffer-only frames.
+
+ `invisible-iconic-nomini'
+ Like `invisible-iconic' but omits minibuffer-only frames.
+
+ `nil'
+ Identical to `nomini'.
+
+ WINDOW
+ Consider only the window WINDOW's frame and any frame now
+ using WINDOW as the minibuffer.
+
+ any other value
+ Consider all frames.
+
+ The optional argument WHICH-DEVICES further clarifies on which
+ devices to search for frames as specified by WHICH-FRAMES.
+
+ `nil'
+ Consider all devices on the selected console.
+
+ DEVICE
+ Consider only the one device DEVICE.
+
+ CONSOLE
+ Consider all devices on CONSOLE.
+
+ DEVICE-TYPE
+ Consider all devices with device type DEVICE-TYPE.
+
+ `window-system'
+ Consider all devices on window system consoles.
+
+ anything else
+ Consider all devices without restriction.
+
+ - Function: previous-frame &optional frame which-frames which-devices
+ Like `next-frame', but cycles through all frames in the opposite
+ direction.
+
+ See also `next-window' and `previous-window', in *Note Cyclic Window
+Ordering::.
\1f
-File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
+File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
-Narrowing
-=========
+Frames and Windows
+==================
- "Narrowing" means limiting the text addressable by XEmacs editing
-commands to a limited range of characters in a buffer. The text that
-remains addressable is called the "accessible portion" of the buffer.
+ Each window is part of one and only one frame; you can get the frame
+with `window-frame'.
- Narrowing is specified with two buffer positions which become the
-beginning and end of the accessible portion. For most editing commands
-and most Emacs primitives, these positions replace the values of the
-beginning and end of the buffer. While narrowing is in effect, no text
-outside the accessible portion is displayed, and point cannot move
-outside the accessible portion.
+ - Function: frame-root-window &optional frame
+ This returns the root window of frame FRAME. FRAME defaults to
+ the selected frame if not specified.
- Values such as positions or line numbers, which usually count from
-the beginning of the buffer, do so despite narrowing, but the functions
-which use them refuse to operate on text that is inaccessible.
+ - Function: window-frame &optional window
+ This function returns the frame that WINDOW is on. WINDOW
+ defaults to the selected window if omitted.
- The commands for saving buffers are unaffected by narrowing; they
-save the entire buffer regardless of any narrowing.
+ All the non-minibuffer windows in a frame are arranged in a cyclic
+order. The order runs from the frame's top window, which is at the
+upper left corner, down and to the right, until it reaches the window at
+the lower right corner (always the minibuffer window, if the frame has
+one), and then it moves back to the top.
- - Command: narrow-to-region START END &optional BUFFER
- This function sets the accessible portion of BUFFER to start at
- START and end at END. Both arguments should be character
- positions. BUFFER defaults to the current buffer if omitted.
+ - Function: frame-highest-window &optional frame position
+ This function returns the topmost, leftmost window of frame FRAME
+ at position POSITION.
- In an interactive call, START and END are set to the bounds of the
- current region (point and the mark, with the smallest first).
+ If omitted, FRAME defaults to the currently selected frame.
- - Command: narrow-to-page &optional MOVE-COUNT
- This function sets the accessible portion of the current buffer to
- include just the current page. An optional first argument
- MOVE-COUNT non-`nil' means to move forward or backward by
- MOVE-COUNT pages and then narrow. The variable `page-delimiter'
- specifies where pages start and end (*note Standard Regexps::.).
+ POSITION is used to distinguish between multiple windows that abut
+ the top of the frame: 0 means the leftmost window abutting the top
+ of the frame, 1 the next-leftmost, etc. POSITION can also be less
+ than zero: -1 means the rightmost window abutting the top of the
+ frame, -2 the next-rightmost, etc. If omitted, POSITION defaults
+ to 0, i.e. the leftmost highest window. If there is no window at
+ the given POSITION, `nil' is returned.
- In an interactive call, MOVE-COUNT is set to the numeric prefix
- argument.
+ The following three functions work similarly.
- - Command: widen &optional BUFFER
- This function cancels any narrowing in BUFFER, so that the entire
- contents are accessible. This is called "widening". It is
- equivalent to the following expression:
+ - Function: frame-lowest-window &optional frame position
+ This function returns the lowest window on FRAME which is at
+ POSITION.
- (narrow-to-region 1 (1+ (buffer-size)))
+ - Function: frame-leftmost-window &optional frame position
+ This function returns the leftmost window on FRAME which is at
+ POSITION.
- BUFFER defaults to the current buffer if omitted.
+ - Function: frame-rightmost-window &optional frame position
+ This function returns the rightmost window on FRAME which is at
+ POSITION.
- - Special Form: save-restriction BODY...
- This special form saves the current bounds of the accessible
- portion, evaluates the BODY forms, and finally restores the saved
- bounds, thus restoring the same state of narrowing (or absence
- thereof) formerly in effect. The state of narrowing is restored
- even in the event of an abnormal exit via `throw' or error (*note
- Nonlocal Exits::.). Therefore, this construct is a clean way to
- narrow a buffer temporarily.
-
- The value returned by `save-restriction' is that returned by the
- last form in BODY, or `nil' if no body forms were given.
-
- *Caution:* it is easy to make a mistake when using the
- `save-restriction' construct. Read the entire description here
- before you try it.
-
- If BODY changes the current buffer, `save-restriction' still
- restores the restrictions on the original buffer (the buffer whose
- restrictions it saved from), but it does not restore the identity
- of the current buffer.
-
- `save-restriction' does *not* restore point and the mark; use
- `save-excursion' for that. If you use both `save-restriction' and
- `save-excursion' together, `save-excursion' should come first (on
- the outside). Otherwise, the old point value would be restored
- with temporary narrowing still in effect. If the old point value
- were outside the limits of the temporary narrowing, this would
- fail to restore it accurately.
-
- The `save-restriction' special form records the values of the
- beginning and end of the accessible portion as distances from the
- beginning and end of the buffer. In other words, it records the
- amount of inaccessible text before and after the accessible
- portion.
-
- This method yields correct results if BODY does further narrowing.
- However, `save-restriction' can become confused if the body widens
- and then make changes outside the range of the saved narrowing.
- When this is what you want to do, `save-restriction' is not the
- right tool for the job. Here is what you must use instead:
-
- (let ((beg (point-min-marker))
- (end (point-max-marker)))
- (unwind-protect
- (progn BODY)
- (save-excursion
- (set-buffer (marker-buffer beg))
- (narrow-to-region beg end))))
-
- Here is a simple example of correct use of `save-restriction':
+ At any time, exactly one window on any frame is "selected within the
+frame". The significance of this designation is that selecting the
+frame also selects this window. You can get the frame's current
+selected window with `frame-selected-window'.
- ---------- Buffer: foo ----------
- This is the contents of foo
- This is the contents of foo
- This is the contents of foo-!-
- ---------- Buffer: foo ----------
-
- (save-excursion
- (save-restriction
- (goto-char 1)
- (forward-line 2)
- (narrow-to-region 1 (point))
- (goto-char (point-min))
- (replace-string "foo" "bar")))
-
- ---------- Buffer: foo ----------
- This is the contents of bar
- This is the contents of bar
- This is the contents of foo-!-
- ---------- Buffer: foo ----------
+ - Function: frame-selected-window &optional frame
+ This function returns the window on FRAME that is selected within
+ FRAME. FRAME defaults to the selected frame if not specified.
+
+ Conversely, selecting a window for XEmacs with `select-window' also
+makes that window selected within its frame. *Note Selecting Windows::.
+
+ Another function that (usually) returns one of the windows in a
+frame is `minibuffer-window'. *Note Minibuffer Misc::.
\1f
-File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
+File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
-Markers
-*******
+Minibuffers and Frames
+======================
- A "marker" is a Lisp object used to specify a position in a buffer
-relative to the surrounding text. A marker changes its offset from the
-beginning of the buffer automatically whenever text is inserted or
-deleted, so that it stays with the two characters on either side of it.
+ Normally, each frame has its own minibuffer window at the bottom,
+which is used whenever that frame is selected. If the frame has a
+minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
+Misc::).
-* Menu:
+ However, you can also create a frame with no minibuffer. Such a
+frame must use the minibuffer window of some other frame. When you
+create the frame, you can specify explicitly the minibuffer window to
+use (in some other frame). If you don't, then the minibuffer is found
+in the frame which is the value of the variable
+`default-minibuffer-frame'. Its value should be a frame which does
+have a minibuffer.
-* Overview of Markers:: The components of a marker, and how it relocates.
-* Predicates on Markers:: Testing whether an object is a marker.
-* Creating Markers:: Making empty markers or markers at certain places.
-* Information from Markers:: Finding the marker's buffer or character position.
-* Changing Markers:: Moving the marker to a new buffer or position.
-* The Mark:: How "the mark" is implemented with a marker.
-* The Region:: How to access "the region".
+ - Variable: default-minibuffer-frame
+ This variable specifies the frame to use for the minibuffer
+ window, by default.
\1f
-File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
-
-Overview of Markers
-===================
-
- A marker specifies a buffer and a position in that buffer. The
-marker can be used to represent a position in the functions that
-require one, just as an integer could be used. *Note Positions::, for
-a complete description of positions.
-
- A marker has two attributes: the marker position, and the marker
-buffer. The marker position is an integer that is equivalent (at a
-given time) to the marker as a position in that buffer. But the
-marker's position value can change often during the life of the marker.
-Insertion and deletion of text in the buffer relocate the marker. The
-idea is that a marker positioned between two characters remains between
-those two characters despite insertion and deletion elsewhere in the
-buffer. Relocation changes the integer equivalent of the marker.
-
- Deleting text around a marker's position leaves the marker between
-the characters immediately before and after the deleted text. Inserting
-text at the position of a marker normally leaves the marker in front of
-the new text--unless it is inserted with `insert-before-markers' (*note
-Insertion::.).
-
- Insertion and deletion in a buffer must check all the markers and
-relocate them if necessary. This slows processing in a buffer with a
-large number of markers. For this reason, it is a good idea to make a
-marker point nowhere if you are sure you don't need it any more.
-Unreferenced markers are garbage collected eventually, but until then
-will continue to use time if they do point somewhere.
-
- Because it is common to perform arithmetic operations on a marker
-position, most of the arithmetic operations (including `+' and `-')
-accept markers as arguments. In such cases, the marker stands for its
-current position.
-
- Note that you can use extents to achieve the same functionality, and
-more, as markers. (Markers were defined before extents, which is why
-they both continue to exist.) A zero-length extent with the
-`detachable' property removed is almost identical to a marker. (*Note
-Extent Endpoints::, for more information on zero-length extents.)
-
- In particular:
-
- * In order to get marker-like behavior in a zero-length extent, the
- `detachable' property must be removed (otherwise, the extent will
- disappear when text near it is deleted) and exactly one endpoint
- must be closed (if both endpoints are closed, the extent will
- expand to contain text inserted where it is located).
-
- * If a zero-length extent has the `end-open' property but not the
- `start-open' property (this is the default), text inserted at the
- extent's location causes the extent to move forward, just like a
- marker.
-
- * If a zero-length extent has the `start-open' property but not the
- `end-open' property, text inserted at the extent's location causes
- the extent to remain before the text, like what happens to markers
- when `insert-before-markers' is used.
-
- * Markers end up after or before inserted text depending on whether
- `insert' or `insert-before-markers' was called. These functions
- do not affect zero-length extents differently; instead, the
- presence or absence of the `start-open' and `end-open' extent
- properties determines this, as just described.
-
- * Markers are automatically removed from a buffer when they are no
- longer in use. Extents remain around until explicitly removed
- from a buffer.
-
- * Many functions are provided for listing the extents in a buffer or
- in a region of a buffer. No such functions exist for markers.
-
- Here are examples of creating markers, setting markers, and moving
-point to markers:
-
- ;; Make a new marker that initially does not point anywhere:
- (setq m1 (make-marker))
- => #<marker in no buffer>
-
- ;; Set `m1' to point between the 99th and 100th characters
- ;; in the current buffer:
- (set-marker m1 100)
- => #<marker at 100 in markers.texi>
-
- ;; Now insert one character at the beginning of the buffer:
- (goto-char (point-min))
- => 1
- (insert "Q")
- => nil
-
- ;; `m1' is updated appropriately.
- m1
- => #<marker at 101 in markers.texi>
-
- ;; Two markers that point to the same position
- ;; are not `eq', but they are `equal'.
- (setq m2 (copy-marker m1))
- => #<marker at 101 in markers.texi>
- (eq m1 m2)
- => nil
- (equal m1 m2)
- => t
-
- ;; When you are finished using a marker, make it point nowhere.
- (set-marker m1 nil)
- => #<marker in no buffer>
+File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
+
+Input Focus
+===========
+
+ At any time, one frame in XEmacs is the "selected frame". The
+selected window always resides on the selected frame. As the focus
+moves from device to device, the selected frame on each device is
+remembered and restored when the focus moves back to that device.
+
+ - Function: selected-frame &optional device
+ This function returns the selected frame on DEVICE. If DEVICE is
+ not specified, the selected device will be used. If no frames
+ exist on the device, `nil' is returned.
+
+ The X server normally directs keyboard input to the X window that the
+mouse is in. Some window managers use mouse clicks or keyboard events
+to "shift the focus" to various X windows, overriding the normal
+behavior of the server.
+
+ Lisp programs can switch frames "temporarily" by calling the
+function `select-frame'. This does not override the window manager;
+rather, it escapes from the window manager's control until that control
+is somehow reasserted.
+
+ When using a text-only terminal, there is no window manager;
+therefore, `select-frame' is the only way to switch frames, and the
+effect lasts until overridden by a subsequent call to `select-frame'.
+Only the selected terminal frame is actually displayed on the terminal.
+Each terminal screen except for the initial one has a number, and the
+number of the selected frame appears in the mode line after the word
+`XEmacs' (*note Modeline Variables::).
+
+ - Function: select-frame frame
+ This function selects frame FRAME, temporarily disregarding the
+ focus of the X server if any. The selection of FRAME lasts until
+ the next time the user does something to select a different frame,
+ or until the next time this function is called.
+
+ Note that `select-frame' does not actually cause the window-system
+ focus to be set to this frame, or the `select-frame-hook' or
+ `deselect-frame-hook' to be run, until the next time that XEmacs is
+ waiting for an event.
+
+ Also note that when the variable `focus-follows-mouse' is
+ non-`nil', the frame selection is temporary and is reverted when
+ the current command terminates, much like the buffer selected by
+ `set-buffer'. In order to effect a permanent focus change use
+ `focus-frame'.
+
+ - Function: focus-frame frame
+ This function selects FRAME and gives it the window system focus.
+ The operation of `focus-frame' is not affected by the value of
+ `focus-follows-mouse'.
+
+ - Special Form: save-selected-frame forms...
+ This special form records the selected frame, executes FORMS in
+ sequence, then restores the earlier selected frame. The value
+ returned is the value of the last form.
+
+ - Special Form: with-selected-frame frame forms...
+ This special form records the selected frame, then selects FRAME
+ and executes FORMS in sequence. After the last form is finished,
+ the earlier selected frame is restored. The value returned is the
+ value of the last form.
\1f
-File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
+File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
+
+Visibility of Frames
+====================
-Predicates on Markers
-=====================
+ An frame on a window system may be "visible", "invisible", or
+"iconified". If it is visible, you can see its contents. If it is
+iconified, the frame's contents do not appear on the screen, but an icon
+does. If the frame is invisible, it doesn't show on the screen, not
+even as an icon.
- You can test an object to see whether it is a marker, or whether it
-is either an integer or a marker or either an integer, a character, or a
-marker. The latter tests are useful in connection with the arithmetic
-functions that work with any of markers, integers, or characters.
+ Visibility is meaningless for TTY frames, since only the selected
+one is actually displayed in any case.
- - Function: markerp OBJECT
- This function returns `t' if OBJECT is a marker, `nil' otherwise.
- Note that integers are not markers, even though many functions
- will accept either a marker or an integer.
+ - Function: make-frame-visible &optional frame
+ This function makes frame FRAME visible. If you omit FRAME, it
+ makes the selected frame visible.
- - Function: integer-or-marker-p OBJECT
- This function returns `t' if OBJECT is an integer or a marker,
- `nil' otherwise.
+ - Function: make-frame-invisible &optional frame force
+ This function makes frame FRAME invisible.
- - Function: integer-char-or-marker-p OBJECT
- This function returns `t' if OBJECT is an integer, a character, or
- a marker, `nil' otherwise.
+ - Command: iconify-frame &optional frame
+ This function iconifies frame FRAME.
- - Function: number-or-marker-p OBJECT
- This function returns `t' if OBJECT is a number (either kind) or a
- marker, `nil' otherwise.
+ - Function: Command deiconify-frame &optional frame
+ This function de-iconifies frame FRAME. Under a window system,
+ this is equivalent to `make-frame-visible'.
- - Function: number-char-or-marker-p OBJECT
- This function returns `t' if OBJECT is a number (either kind), a
- character, or a marker, `nil' otherwise.
+ - Function: frame-visible-p &optional frame
+ This returns whether FRAME is currently "visible" (actually in use
+ for display). A frame that is not visible is not updated, and, if
+ it works through a window system, may not show at all.
+
+ - Function: frame-iconified-p &optional frame
+ This returns whether FRAME is iconified. Not all window managers
+ use icons; some merely unmap the window, so this function is not
+ the inverse of `frame-visible-p'. It is possible for a frame to
+ not be visible and not be iconified either. However, if the frame
+ is iconified, it will not be visible. (Under FSF Emacs, the
+ functionality of this function is obtained through
+ `frame-visible-p'.)
+
+ - Function: frame-totally-visible-p &optional frame
+ This returns whether FRAME is not obscured by any other X windows.
+ On TTY frames, this is the same as `frame-visible-p'.
\1f
-File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
-
-Functions That Create Markers
-=============================
-
- When you create a new marker, you can make it point nowhere, or point
-to the present position of point, or to the beginning or end of the
-accessible portion of the buffer, or to the same place as another given
-marker.
-
- - Function: make-marker
- This functions returns a newly created marker that does not point
- anywhere.
-
- (make-marker)
- => #<marker in no buffer>
-
- - Function: point-marker &optional DONT-COPY-P BUFFER
- This function returns a marker that points to the present position
- of point in BUFFER, which defaults to the current buffer. *Note
- Point::. For an example, see `copy-marker', below.
-
- Internally, a marker corresponding to point is always maintained.
- Normally the marker returned by `point-marker' is a copy; you may
- modify it with reckless abandon. However, if optional argument
- DONT-COPY-P is non-`nil', then the real point-marker is returned;
- modifying the position of this marker will move point. It is
- illegal to change the buffer of it, or make it point nowhere.
-
- - Function: point-min-marker &optional BUFFER
- This function returns a new marker that points to the beginning of
- the accessible portion of BUFFER, which defaults to the current
- buffer. This will be the beginning of the buffer unless narrowing
- is in effect. *Note Narrowing::.
-
- - Function: point-max-marker &optional BUFFER
- This function returns a new marker that points to the end of the
- accessible portion of BUFFER, which defaults to the current
- buffer. This will be the end of the buffer unless narrowing is in
- effect. *Note Narrowing::.
-
- Here are examples of this function and `point-min-marker', shown in
- a buffer containing a version of the source file for the text of
- this chapter.
-
- (point-min-marker)
- => #<marker at 1 in markers.texi>
- (point-max-marker)
- => #<marker at 15573 in markers.texi>
-
- (narrow-to-region 100 200)
- => nil
- (point-min-marker)
- => #<marker at 100 in markers.texi>
- (point-max-marker)
- => #<marker at 200 in markers.texi>
-
- - Function: copy-marker MARKER-OR-INTEGER
- If passed a marker as its argument, `copy-marker' returns a new
- marker that points to the same place and the same buffer as does
- MARKER-OR-INTEGER. If passed an integer as its argument,
- `copy-marker' returns a new marker that points to position
- MARKER-OR-INTEGER in the current buffer.
-
- If passed an integer argument less than 1, `copy-marker' returns a
- new marker that points to the beginning of the current buffer. If
- passed an integer argument greater than the length of the buffer,
- `copy-marker' returns a new marker that points to the end of the
- buffer.
-
- An error is signaled if MARKER is neither a marker nor an integer.
-
- (setq p (point-marker))
- => #<marker at 2139 in markers.texi>
-
- (setq q (copy-marker p))
- => #<marker at 2139 in markers.texi>
-
- (eq p q)
- => nil
-
- (equal p q)
- => t
-
- (point)
- => 2139
-
- (set-marker p 3000)
- => #<marker at 3000 in markers.texi>
-
- (point)
- => 2139
-
- (setq p (point-marker t))
- => #<marker at 2139 in markers.texi>
-
- (set-marker p 3000)
- => #<marker at 3000 in markers.texi>
-
- (point)
- => 3000
-
- (copy-marker 0)
- => #<marker at 1 in markers.texi>
-
- (copy-marker 20000)
- => #<marker at 7572 in markers.texi>
+File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
+
+Raising and Lowering Frames
+===========================
+
+ The X Window System uses a desktop metaphor. Part of this metaphor
+is the idea that windows are stacked in a notional third dimension
+perpendicular to the screen surface, and thus ordered from "highest" to
+"lowest". Where two windows overlap, the one higher up covers the one
+underneath. Even a window at the bottom of the stack can be seen if no
+other window overlaps it.
+
+ A window's place in this ordering is not fixed; in fact, users tend
+to change the order frequently. "Raising" a window means moving it
+"up", to the top of the stack. "Lowering" a window means moving it to
+the bottom of the stack. This motion is in the notional third
+dimension only, and does not change the position of the window on the
+screen.
+
+ You can raise and lower XEmacs's X windows with these functions:
+
+ - Command: raise-frame &optional frame
+ This function raises frame FRAME.
+
+ - Command: lower-frame &optional frame
+ This function lowers frame FRAME.
+
+ You can also specify auto-raise (raising automatically when a frame
+is selected) or auto-lower (lowering automatically when it is
+deselected). Under X, most ICCCM-compliant window managers will have
+an option to do this for you, but the following variables are provided
+in case you're using a broken WM. (Under FSF Emacs, the same
+functionality is provided through the `auto-raise' and `auto-lower'
+frame properties.)
+
+ - Variable: auto-raise-frame
+ This variable's value is `t' if frames will be raised to the top
+ when selected.
+
+ - Variable: auto-lower-frame
+ This variable's value is `t' if frames will be lowered to the
+ bottom when no longer selected.
+
+ Auto-raising and auto-lowering is implemented through functions
+attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
+Hooks::). Under normal circumstances, you should not call these
+functions directly.
+
+ - Function: default-select-frame-hook
+ This hook function implements the `auto-raise-frame' variable; it
+ is for use as the value of `select-frame-hook'.
+
+ - Function: default-deselect-frame-hook
+ This hook function implements the `auto-lower-frame' variable; it
+ is for use as the value of `deselect-frame-hook'.
\1f
-File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
+File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
-Information from Markers
-========================
+Frame Configurations
+====================
- This section describes the functions for accessing the components of
-a marker object.
+ A "frame configuration" records the current arrangement of frames,
+all their properties, and the window configuration of each one.
- - Function: marker-position MARKER
- This function returns the position that MARKER points to, or `nil'
- if it points nowhere.
+ - Function: current-frame-configuration
+ This function returns a frame configuration list that describes
+ the current arrangement of frames and their contents.
- - Function: marker-buffer MARKER
- This function returns the buffer that MARKER points into, or `nil'
- if it points nowhere.
+ - Function: set-frame-configuration configuration &optional nodelete
+ This function restores the state of frames described by
+ CONFIGURATION, which should be the return value from a previous
+ call to `current-frame-configuration'.
- (setq m (make-marker))
- => #<marker in no buffer>
- (marker-position m)
- => nil
- (marker-buffer m)
- => nil
-
- (set-marker m 3770 (current-buffer))
- => #<marker at 3770 in markers.texi>
- (marker-buffer m)
- => #<buffer markers.texi>
- (marker-position m)
- => 3770
+ Each frame listed in CONFIGURATION has its position, size, window
+ configuration, and other properties set as specified in
+ CONFIGURATION.
- Two distinct markers are considered `equal' (even though not `eq')
-to each other if they have the same position and buffer, or if they
-both point nowhere.
+ Ordinarily, this function deletes all existing frames not listed in
+ CONFIGURATION. But if optional second argument NODELETE is
+ non-`nil', the unwanted frames are iconified instead.
\1f
-File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
+File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames
+
+Hooks for Customizing Frame Behavior
+====================================
-Changing Marker Positions
-=========================
+ XEmacs provides many hooks that are called at various times during a
+frame's lifetime. *Note Hooks::.
- This section describes how to change the position of an existing
-marker. When you do this, be sure you know whether the marker is used
-outside of your program, and, if so, what effects will result from
-moving it--otherwise, confusing things may happen in other parts of
-Emacs.
+ - Variable: create-frame-hook
+ This hook is called each time a frame is created. The functions
+ are called with one argument, the newly-created frame.
- - Function: set-marker MARKER POSITION &optional BUFFER
- This function moves MARKER to POSITION in BUFFER. If BUFFER is
- not provided, it defaults to the current buffer.
+ - Variable: delete-frame-hook
+ This hook is called each time a frame is deleted. The functions
+ are called with one argument, the about-to-be-deleted frame.
- If POSITION is less than 1, `set-marker' moves MARKER to the
- beginning of the buffer. If POSITION is greater than the size of
- the buffer, `set-marker' moves marker to the end of the buffer.
- If POSITION is `nil' or a marker that points nowhere, then MARKER
- is set to point nowhere.
+ - Variable: select-frame-hook
+ This is a normal hook that is run just after a frame is selected.
+ The function `default-select-frame-hook', which implements
+ auto-raising (*note Raising and Lowering::), is normally attached
+ to this hook.
- The value returned is MARKER.
+ Note that calling `select-frame' does not necessarily set the
+ focus: The actual window-system focus will not be changed until
+ the next time that XEmacs is waiting for an event, and even then,
+ the window manager may refuse the focus-change request.
- (setq m (point-marker))
- => #<marker at 4714 in markers.texi>
- (set-marker m 55)
- => #<marker at 55 in markers.texi>
- (setq b (get-buffer "foo"))
- => #<buffer foo>
- (set-marker m 0 b)
- => #<marker at 1 in foo>
+ - Variable: deselect-frame-hook
+ This is a normal hook that is run just before a frame is deselected
+ (and another frame is selected). The function
+ `default-deselect-frame-hook', which implements auto-lowering
+ (*note Raising and Lowering::), is normally attached to this hook.
- - Function: move-marker MARKER POSITION &optional BUFFER
- This is another name for `set-marker'.
+ - Variable: map-frame-hook
+ This hook is called each time a frame is mapped (i.e. made
+ visible). The functions are called with one argument, the newly
+ mapped frame.
+
+ - Variable: unmap-frame-hook
+ This hook is called each time a frame is unmapped (i.e. made
+ invisible or iconified). The functions are called with one
+ argument, the newly unmapped frame.
\1f
-File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
-
-The Mark
-========
-
- One special marker in each buffer is designated "the mark". It
-records a position for the user for the sake of commands such as `C-w'
-and `C-x <TAB>'. Lisp programs should set the mark only to values that
-have a potential use to the user, and never for their own internal
-purposes. For example, the `replace-regexp' command sets the mark to
-the value of point before doing any replacements, because this enables
-the user to move back there conveniently after the replace is finished.
-
- Once the mark "exists" in a buffer, it normally never ceases to
-exist. However, it may become "inactive", and usually does so after
-each command (other than simple motion commands and some commands that
-explicitly activate the mark). When the mark is active, the region
-between point and the mark is called the "active region" and is
-highlighted specially.
-
- Many commands are designed so that when called interactively they
-operate on the text between point and the mark. Such commands work
-only when an active region exists, i.e. when the mark is active. (The
-reason for this is to prevent you from accidentally deleting or
-changing large chunks of your text.) If you are writing such a command,
-don't examine the mark directly; instead, use `interactive' with the
-`r' specification. This provides the values of point and the mark as
-arguments to the command in an interactive call, but permits other Lisp
-programs to specify arguments explicitly, and automatically signals an
-error if the command is called interactively when no active region
-exists. *Note Interactive Codes::.
-
- Each buffer has its own value of the mark that is independent of the
-value of the mark in other buffers. (When a buffer is created, the mark
-exists but does not point anywhere. We consider this state as "the
-absence of a mark in that buffer.") However, only one active region can
-exist at a time. Activating the mark in one buffer automatically
-deactivates an active mark in any other buffer. Note that the user can
-explicitly activate a mark at any time by using the command
-`activate-region' (normally bound to `M-C-z') or by using the command
-`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
-side effect of activating the mark.
-
- Some people do not like active regions, so they disable this behavior
-by setting the variable `zmacs-regions' to `nil'. This makes the mark
-always active (except when a buffer is just created and the mark points
-nowhere), and turns off the highlighting of the region between point
-and the mark. Commands that explicitly retrieve the value of the mark
-should make sure that they behave correctly and consistently
-irrespective of the setting of `zmacs-regions'; some primitives are
-provided to ensure this behavior.
-
- In addition to the mark, each buffer has a "mark ring" which is a
-list of markers containing previous values of the mark. When editing
-commands change the mark, they should normally save the old value of the
-mark on the mark ring. The variable `mark-ring-max' specifies the
-maximum number of entries in the mark ring; once the list becomes this
-long, adding a new element deletes the last element.
-
- - Function: mark &optional FORCE BUFFER
- This function returns BUFFER's mark position as an integer.
- BUFFER defaults to the current buffer if omitted.
+File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top
+
+Consoles and Devices
+********************
+
+ A "console" is an object representing a single input connection to
+XEmacs, such as an X display or a TTY connection. It is possible for
+XEmacs to have frames on multiple consoles at once (even on
+heterogeneous types--you can simultaneously have a frame on an X
+display and a TTY connection). Normally, there is only one console in
+existence.
+
+ A "device" is an object representing a single output device, such as
+a particular screen on an X display. (Usually there is exactly one
+device per X console connection, but there may be more than one if you
+have a multi-headed X display. For TTY connections, there is always
+exactly one device per console.)
+
+ Each device has one or more "frames" in which text can be displayed.
+For X displays and the like, a frame corresponds to the normal
+window-system concept of a window. Frames can overlap, be displayed at
+various locations within the display, be resized, etc. For TTY, only
+one frame can be displayed at a time, and it occupies the entire TTY
+display area.
+
+ However, you can still define multiple frames and switch between
+them. Their contents are entirely separate from each other. These
+sorts of frames resemble the "virtual console" capability provided
+under Linux or the multiple screens provided by the multiplexing program
+`screen' under Unix.
+
+ When you start up XEmacs, an initial console and device are created
+to receive input and display frames on. This will either be an X
+display or a TTY connection, depending on what mode you started XEmacs
+in (this is determined by the `DISPLAY' environment variable, the
+`-nw', `-t' and `-display' command-line options, etc.).
+
+ You can connect to other X displays and TTY connections by creating
+new console objects, and to other X screens on an existing display by
+creating new device objects, as described below. Many functions (for
+example the frame-creation functions) take an optional device argument
+specifying which device the function pertains to. If the argument is
+omitted, it defaults to the selected device (see below).
+
+ - Function: consolep object
+ This returns non-`nil' if OBJECT is a console.
+
+ - Function: devicep object
+ This returns non-`nil' if OBJECT is a device.
+
+* Menu:
- If the mark is inactive, `mark' normally returns `nil'. However,
- if FORCE is non-`nil', then `mark' returns the mark position
- anyway--or `nil', if the mark is not yet set for the buffer.
-
- (Remember that if ZMACS-REGIONS is `nil', the mark is always
- active as long as it exists, and the FORCE argument will have no
- effect.)
-
- If you are using this in an editing command, you are most likely
- making a mistake; see the documentation of `set-mark' below.
-
- - Function: mark-marker INACTIVE-P BUFFER
- This function returns BUFFER's mark. BUFFER defaults to the
- current buffer if omitted. This is the very marker that records
- the mark location inside XEmacs, not a copy. Therefore, changing
- this marker's position will directly affect the position of the
- mark. Don't do it unless that is the effect you want.
-
- If the mark is inactive, `mark-marker' normally returns `nil'.
- However, if FORCE is non-`nil', then `mark-marker' returns the
- mark anyway.
- (setq m (mark-marker))
- => #<marker at 3420 in markers.texi>
- (set-marker m 100)
- => #<marker at 100 in markers.texi>
- (mark-marker)
- => #<marker at 100 in markers.texi>
-
- Like any marker, this marker can be set to point at any buffer you
- like. We don't recommend that you make it point at any buffer
- other than the one of which it is the mark. If you do, it will
- yield perfectly consistent, but rather odd, results.
-
- - Function: set-mark POSITION &optional BUFFER
- This function sets `buffer''s mark to POSITION, and activates the
- mark. BUFFER defaults to the current buffer if omitted. The old
- value of the mark is *not* pushed onto the mark ring.
-
- *Please note:* Use this function only if you want the user to see
- that the mark has moved, and you want the previous mark position to
- be lost. Normally, when a new mark is set, the old one should go
- on the `mark-ring'. For this reason, most applications should use
- `push-mark' and `pop-mark', not `set-mark'.
-
- Novice XEmacs Lisp programmers often try to use the mark for the
- wrong purposes. The mark saves a location for the user's
- convenience. An editing command should not alter the mark unless
- altering the mark is part of the user-level functionality of the
- command. (And, in that case, this effect should be documented.)
- To remember a location for internal use in the Lisp program, store
- it in a Lisp variable. For example:
-
- (let ((beg (point)))
- (forward-line 1)
- (delete-region beg (point))).
-
- - Command: exchange-point-and-mark &optional DONT-ACTIVATE-REGION
- This function exchanges the positions of point and the mark. It
- is intended for interactive use. The mark is also activated
- unless DONT-ACTIVATE-REGION is non-`nil'.
-
- - Function: push-mark &optional POSITION NOMSG ACTIVATE BUFFER
- This function sets BUFFER's mark to POSITION, and pushes a copy of
- the previous mark onto `mark-ring'. BUFFER defaults to the
- current buffer if omitted. If POSITION is `nil', then the value
- of point is used. `push-mark' returns `nil'.
-
- If the last global mark pushed was not in BUFFER, also push
- POSITION on the global mark ring (see below).
-
- The function `push-mark' normally *does not* activate the mark.
- To do that, specify `t' for the argument ACTIVATE.
-
- A `Mark set' message is displayed unless NOMSG is non-`nil'.
-
- - Function: pop-mark
- This function pops off the top element of `mark-ring' and makes
- that mark become the buffer's actual mark. This does not move
- point in the buffer, and it does nothing if `mark-ring' is empty.
- It deactivates the mark.
-
- The return value is not meaningful.
-
- - Variable: mark-ring
- The value of this buffer-local variable is the list of saved former
- marks of the current buffer, most recent first.
-
- mark-ring
- => (#<marker at 11050 in markers.texi>
- #<marker at 10832 in markers.texi>
- ...)
-
- - User Option: mark-ring-max
- The value of this variable is the maximum size of `mark-ring'. If
- more marks than this are pushed onto the `mark-ring', `push-mark'
- discards an old mark when it adds a new one.
-
- In additional to a per-buffer mark ring, there is a "global mark
-ring". Marks are pushed onto the global mark ring the first time you
-set a mark after switching buffers.
-
- - Variable: global-mark-ring
- The value of this variable is the list of saved former global
- marks, most recent first.
-
- - User Option: mark-ring-max
- The value of this variable is the maximum size of
- `global-mark-ring'. If more marks than this are pushed onto the
- `global-mark-ring', `push-mark' discards an old mark when it adds
- a new one.
-
- - Command: pop-global-mark
- This function pops a mark off the global mark ring and jumps to
- that location.
+* Basic Console Functions:: Functions for working with consoles.
+* Basic Device Functions:: Functions for working with devices.
+* Console Types and Device Classes::
+ I/O and color characteristics.
+* Connecting to a Console or Device::
+* The Selected Console and Device::
+* Console and Device I/O:: Controlling input and output.
\1f
-File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
-
-The Region
-==========
-
- The text between point and the mark is known as "the region".
-Various functions operate on text delimited by point and the mark, but
-only those functions specifically related to the region itself are
-described here.
-
- When `zmacs-regions' is non-`nil' (this is the default), the concept
-of an "active region" exists. The region is active when the
-corresponding mark is active. Note that only one active region at a
-time can exist - i.e. only one buffer's region is active at a time.
-*Note The Mark::, for more information about active regions.
-
- - User Option: zmacs-regions
- If non-`nil' (the default), active regions are used. *Note The
- Mark::, for a detailed explanation of what this means.
-
- A number of functions are provided for explicitly determining the
-bounds of the region and whether it is active. Few programs need to use
-these functions, however. A command designed to operate on a region
-should normally use `interactive' with the `r' specification to find
-the beginning and end of the region. This lets other Lisp programs
-specify the bounds explicitly as arguments and automatically respects
-the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
-
- - Function: region-beginning &optional BUFFER
- This function returns the position of the beginning of BUFFER's
- region (as an integer). This is the position of either point or
- the mark, whichever is smaller. BUFFER defaults to the current
- buffer if omitted.
+File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices
+
+Basic Console Functions
+=======================
+
+ - Function: console-list
+ This function returns a list of all existing consoles.
+
+ - Function: console-device-list &optional console
+ This function returns a list of all devices on CONSOLE. If
+ CONSOLE is `nil', the selected console will be used.
+
+\1f
+File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices
+
+Basic Device Functions
+======================
+
+ - Function: device-list
+ This function returns a list of all existing devices.
+
+ - Function: device-or-frame-p object
+ This function returns non-`nil' if OBJECT is a device or frame.
+ This function is useful because devices and frames are similar in
+ many respects and many functions can operate on either one.
+
+ - Function: device-frame-list &optional device
+ This function returns a list of all frames on DEVICE. DEVICE
+ defaults to the currently selected device.
+
+ - Function: frame-device &optional frame
+ This function returns the device that FRAME is on. FRAME defaults
+ to the currently selected frame.
+
+\1f
+File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices
+
+Console Types and Device Classes
+================================
+
+ Every device is of a particular "type", which describes how the
+connection to that device is made and how the device operates, and a
+particular "class", which describes other characteristics of the device
+(currently, the color capabilities of the device).
+
+ The currently-defined device types are
+
+`x'
+ A connection to an X display (such as `willow:0').
+
+`tty'
+ A connection to a tty (such as `/dev/ttyp3').
+
+`stream'
+ A stdio connection. This describes a device for which input and
+ output is only possible in a stream-like fashion, such as when
+ XEmacs in running in batch mode. The very first device created by
+ XEmacs is a terminal device and is used to print out messages of
+ various sorts (for example, the help message when you use the
+ `-help' command-line option).
+
+ The currently-defined device classes are
+`color'
+ A color device.
+
+`grayscale'
+ A grayscale device (a device that can display multiple shades of
+ gray, but no color).
+
+`mono'
+ A device that can only display two colors (e.g. black and white).
+
+ - Function: device-type &optional device
+ This function returns the type of DEVICE. This is a symbol whose
+ name is one of the device types mentioned above. DEVICE defaults
+ to the selected device.
+
+ - Function: device-or-frame-type device-or-frame
+ This function returns the type of DEVICE-OR-FRAME.
+
+ - Function: device-class &optional device
+ This function returns the class (color behavior) of DEVICE. This
+ is a symbol whose name is one of the device classes mentioned
+ above.
- If the mark does not point anywhere, an error is signaled. Note
- that this function ignores whether the region is active.
+ - Function: valid-device-type-p device-type
+ This function returns whether DEVICE-TYPE (which should be a
+ symbol) specifies a valid device type.
- - Function: region-end &optional BUFFER
- This function returns the position of the end of BUFFER's region
- (as an integer). This is the position of either point or the mark,
- whichever is larger. BUFFER defaults to the current buffer if
+ - Function: valid-device-class-p device-class
+ This function returns whether DEVICE-CLASS (which should be a
+ symbol) specifies a valid device class.
+
+ - Variable: terminal-device
+ This variable holds the initial terminal device object, which
+ represents XEmacs's stdout.
+
+\1f
+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
+
+Connecting to a Console or Device
+=================================
+
+ - Function: make-device type connection &optional props
+ This function creates a new device.
+
+ The following two functions create devices of specific types and are
+written in terms of `make-device'.
+
+ - Function: make-tty-device &optional tty terminal-type
+ This function creates a new tty device on TTY. This also creates
+ the tty's first frame. TTY should be a string giving the name of
+ a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
+ returned by the `tty' command issued from the Unix shell. A value
+ of `nil' means use the stdin and stdout as passed to XEmacs from
+ the shell. If TERMINAL-TYPE is non-`nil', it should be a string
+ specifying the type of the terminal attached to the specified tty.
+ If it is `nil', the terminal type will be inferred from the
+ `TERM' environment variable.
+
+ - Function: make-x-device &optional display argv-list
+ This function creates a new device connected to DISPLAY. Optional
+ argument ARGV-LIST is a list of strings describing command line
+ options.
+
+ - Function: delete-device device &optional force
+ This function deletes DEVICE, permanently eliminating it from use.
+ This disconnects XEmacs's connection to the device.
+
+ - Variable: create-device-hook
+ This variable, if non-`nil', should contain a list of functions,
+ which are called when a device is created.
+
+ - Variable: delete-device-hook
+ This variable, if non-`nil', should contain a list of functions,
+ which are called when a device is deleted.
+
+ - Function: console-live-p object
+ This function returns non-`nil' if OBJECT is a console that has
+ not been deleted.
+
+ - Function: device-live-p object
+ This function returns non-`nil' if OBJECT is a device that has not
+ been deleted.
+
+ - Function: device-x-display device
+ This function returns the X display which DEVICE is connected to,
+ if DEVICE is an X device.
+
+\1f
+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
+
+The Selected Console and Device
+===============================
+
+ - Function: select-console console
+ This function selects the console CONSOLE. Subsequent editing
+ commands apply to its selected device, selected frame, and selected
+ window. The selection of CONSOLE lasts until the next time the
+ user does something to select a different console, or until the
+ next time this function is called.
+
+ - Function: selected-console
+ This function returns the console which is currently active.
+
+ - Function: select-device device
+ This function selects the device DEVICE.
+
+ - Function: selected-device &optional console
+ This function returns the device which is currently active. If
+ optional CONSOLE is non-`nil', this function returns the device
+ that would be currently active if CONSOLE were the selected
+ console.
+
+\1f
+File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
+
+Console and Device I/O
+======================
+
+ - Function: console-disable-input console
+ This function disables input on console CONSOLE.
+
+ - Function: console-enable-input console
+ This function enables input on console CONSOLE.
+
+ Each device has a "baud rate" value associated with it. On most
+systems, changing this value will affect the amount of padding and
+other strategic decisions made during redisplay.
+
+ - Function: device-baud-rate &optional device
+ This function returns the output baud rate of DEVICE.
+
+ - Function: set-device-baud-rate device rate
+ This function sets the output baud rate of DEVICE to RATE.
+
+\1f
+File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
+
+Positions
+*********
+
+ A "position" is the index of a character in the text of a buffer.
+More precisely, a position identifies the place between two characters
+(or before the first character, or after the last character), so we can
+speak of the character before or after a given position. However, we
+often speak of the character "at" a position, meaning the character
+after that position.
+
+ Positions are usually represented as integers starting from 1, but
+can also be represented as "markers"--special objects that relocate
+automatically when text is inserted or deleted so they stay with the
+surrounding characters. *Note Markers::.
+
+* Menu:
+
+* Point:: The special position where editing takes place.
+* Motion:: Changing point.
+* Excursions:: Temporary motion and buffer changes.
+* Narrowing:: Restricting editing to a portion of the buffer.
+
+\1f
+File: lispref.info, Node: Point, Next: Motion, Up: Positions
+
+Point
+=====
+
+ "Point" is a special buffer position used by many editing commands,
+including the self-inserting typed characters and text insertion
+functions. Other commands move point through the text to allow editing
+and insertion at different places.
+
+ Like other positions, point designates a place between two characters
+(or before the first character, or after the last character), rather
+than a particular character. Usually terminals display the cursor over
+the character that immediately follows point; point is actually before
+the character on which the cursor sits.
+
+ The value of point is a number between 1 and the buffer size plus 1.
+If narrowing is in effect (*note Narrowing::), then point is constrained
+to fall within the accessible portion of the buffer (possibly at one end
+of it).
+
+ Each buffer has its own value of point, which is independent of the
+value of point in other buffers. Each window also has a value of point,
+which is independent of the value of point in other windows on the same
+buffer. This is why point can have different values in various windows
+that display the same buffer. When a buffer appears in only one window,
+the buffer's point and the window's point normally have the same value,
+so the distinction is rarely important. *Note Window Point::, for more
+details.
+
+ - Function: point &optional buffer
+ This function returns the value of point in BUFFER, as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ (point)
+ => 175
+
+ - Function: point-min &optional buffer
+ This function returns the minimum accessible value of point in
+ BUFFER. This is normally 1, but if narrowing is in effect, it is
+ the position of the start of the region that you narrowed to.
+ (*Note Narrowing::.) BUFFER defaults to the current buffer if
omitted.
- If the mark does not point anywhere, an error is signaled. Note
- that this function ignores whether the region is active.
-
- - Function: region-exists-p
- This function is non-`nil' if the region exists. If active regions
- are in use (i.e. `zmacs-regions' is true), this means that the
- region is active. Otherwise, this means that the user has pushed
- a mark in this buffer at some point in the past. If this function
- returns `nil', a function that uses the `r' interactive
- specification will cause an error when called interactively.
-
- - Function: region-active-p
- If `zmacs-regions' is true, this is equivalent to
- `region-exists-p'. Otherwise, this function always returns false.
- This function is used by commands such as
- `fill-paragraph-or-region' and `capitalize-region-or-word', which
- operate either on the active region or on something else (e.g. the
- word or paragraph at point).
-
- - Variable: zmacs-region-stays
- If a command sets this variable to true, the currently active
- region will remain activated when the command finishes. (Normally
- the region is deactivated when each command terminates.) If
- ZMACS-REGIONS is false, however, this has no effect. Under normal
- circumstances, you do not need to set this; use the interactive
- specification `_' instead, if you want the region to remain active.
-
- - Function: zmacs-activate-region
- This function activates the region in the current buffer (this is
- equivalent to activating the current buffer's mark). This will
- normally also highlight the text in the active region and set
- ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
- this function has no effect.)
-
- - Function: zmacs-deactivate-region
- This function deactivates the region in the current buffer (this is
- equivalent to deactivating the current buffer's mark). This will
- normally also unhighlight the text in the active region and set
- ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
- this function has no effect.)
-
- - Function: zmacs-update-region
- This function updates the active region, if it's currently active.
- (If there is no active region, this function does nothing.) This
- has the effect of updating the highlighting on the text in the
- region; but you should never need to call this except under rather
- strange circumstances. The command loop automatically calls it
- when appropriate. Calling this function will call the hook
- `zmacs-update-region-hook', if the region is active.
-
- - Variable: zmacs-activate-region-hook
- This normal hook is called when a region becomes active. (Usually
- this happens as a result of a command that activates the region,
- such as `set-mark-command', `activate-region', or
- `exchange-point-and-mark'.) Note that calling
- `zmacs-activate-region' will call this hook, even if the region is
- already active. If ZMACS-REGIONS is false, however, this hook
- will never get called under any circumstances.
-
- - Variable: zmacs-deactivate-region-hook
- This normal hook is called when an active region becomes inactive.
- (Calling `zmacs-deactivate-region' when the region is inactive will
- *not* cause this hook to be called.) If ZMACS-REGIONS is false,
- this hook will never get called.
-
- - Variable: zmacs-update-region-hook
- This normal hook is called when an active region is "updated" by
- `zmacs-update-region'. This normally gets called at the end of
- each command that sets ZMACS-REGION-STAYS to `t', indicating that
- the region should remain activated. The motion commands do this.
+ - Function: point-max &optional buffer
+ This function returns the maximum accessible value of point in
+ BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
+ in effect, in which case it is the position of the end of the
+ region that you narrowed to. (*note Narrowing::). BUFFER defaults
+ to the current buffer if omitted.
+
+ - Function: buffer-end flag &optional buffer
+ This function returns `(point-min buffer)' if FLAG is less than 1,
+ `(point-max buffer)' otherwise. The argument FLAG must be a
+ number. BUFFER defaults to the current buffer if omitted.
+
+ - Function: buffer-size &optional buffer
+ This function returns the total number of characters in BUFFER.
+ In the absence of any narrowing (*note Narrowing::), `point-max'
+ returns a value one larger than this. BUFFER defaults to the
+ current buffer if omitted.
+
+ (buffer-size)
+ => 35
+ (point-max)
+ => 36
+
+ - Variable: buffer-saved-size
+ The value of this buffer-local variable is the former length of the
+ current buffer, as of the last time it was read in, saved or
+ auto-saved.
\1f
-File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
-
-Text
-****
-
- This chapter describes the functions that deal with the text in a
-buffer. Most examine, insert, or delete text in the current buffer,
-often in the vicinity of point. Many are interactive. All the
-functions that change the text provide for undoing the changes (*note
-Undo::.).
-
- Many text-related functions operate on a region of text defined by
-two buffer positions passed in arguments named START and END. These
-arguments should be either markers (*note Markers::.) or numeric
-character positions (*note Positions::.). The order of these arguments
-does not matter; it is all right for START to be the end of the region
-and END the beginning. For example, `(delete-region 1 10)' and
-`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
-signaled if either START or END is outside the accessible portion of
-the buffer. In an interactive call, point and the mark are used for
-these arguments.
-
- Throughout this chapter, "text" refers to the characters in the
-buffer, together with their properties (when relevant).
+File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
+
+Motion
+======
+
+ Motion functions change the value of point, either relative to the
+current value of point, relative to the beginning or end of the buffer,
+or relative to the edges of the selected window. *Note Point::.
* Menu:
-* Near Point:: Examining text in the vicinity of point.
-* Buffer Contents:: Examining text in a general fashion.
-* Comparing Text:: Comparing substrings of buffers.
-* Insertion:: Adding new text to a buffer.
-* Commands for Insertion:: User-level commands to insert text.
-* Deletion:: Removing text from a buffer.
-* User-Level Deletion:: User-level commands to delete text.
-* The Kill Ring:: Where removed text sometimes is saved for later use.
-* Undo:: Undoing changes to the text of a buffer.
-* Maintaining Undo:: How to enable and disable undo information.
- How to control how much information is kept.
-* Filling:: Functions for explicit filling.
-* Margins:: How to specify margins for filling commands.
-* Auto Filling:: How auto-fill mode is implemented to break lines.
-* Sorting:: Functions for sorting parts of the buffer.
-* Columns:: Computing horizontal positions, and using them.
-* Indentation:: Functions to insert or adjust indentation.
-* Case Changes:: Case conversion of parts of the buffer.
-* Text Properties:: Assigning Lisp property lists to text characters.
-* Substitution:: Replacing a given character wherever it appears.
-* Registers:: How registers are implemented. Accessing the text or
- position stored in a register.
-* Transposition:: Swapping two portions of a buffer.
-* Change Hooks:: Supplying functions to be run when text is changed.
-* Transformations:: MD5 and base64 support.
+* Character Motion:: Moving in terms of characters.
+* Word Motion:: Moving in terms of words.
+* Buffer End Motion:: Moving to the beginning or end of the buffer.
+* Text Lines:: Moving in terms of lines of text.
+* Screen Lines:: Moving in terms of lines as displayed.
+* List Motion:: Moving by parsing lists and sexps.
+* Skipping Characters:: Skipping characters belonging to a certain set.
\1f
-File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
-
-Examining Text Near Point
-=========================
-
- Many functions are provided to look at the characters around point.
-Several simple functions are described here. See also `looking-at' in
-*Note Regexp Search::.
-
- Many of these functions take an optional BUFFER argument. In all
-such cases, the current buffer will be used if this argument is
-omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
-usually did not have these optional BUFFER arguments and always
-operated on the current buffer.)
-
- - Function: char-after &optional POSITION BUFFER
- This function returns the character in the buffer at (i.e.,
- immediately after) position POSITION. If POSITION is out of range
- for this purpose, either before the beginning of the buffer, or at
- or beyond the end, then the value is `nil'. The default for
- POSITION is point. If optional argument BUFFER is `nil', the
- current buffer is assumed.
-
- In the following example, assume that the first character in the
- buffer is `@':
-
- (char-to-string (char-after 1))
- => "@"
-
- - Function: char-before &optional POSITION BUFFER
- This function returns the character in the current buffer
- immediately before position POSITION. If POSITION is out of range
- for this purpose, either at or before the beginning of the buffer,
- or beyond the end, then the value is `nil'. The default for
- POSITION is point. If optional argument BUFFER is `nil', the
- current buffer is assumed.
-
- - Function: following-char &optional BUFFER
- This function returns the character following point in the buffer.
- This is similar to `(char-after (point))'. However, if point is at
- the end of the buffer, then the result of `following-char' is 0.
- If optional argument BUFFER is `nil', the current buffer is
- assumed.
-
- Remember that point is always between characters, and the terminal
- cursor normally appears over the character following point.
- Therefore, the character returned by `following-char' is the
- character the cursor is over.
-
- In this example, point is between the `a' and the `c'.
+File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
- ---------- Buffer: foo ----------
- Gentlemen may cry ``Pea-!-ce! Peace!,''
- but there is no peace.
- ---------- Buffer: foo ----------
-
- (char-to-string (preceding-char))
- => "a"
- (char-to-string (following-char))
- => "c"
-
- - Function: preceding-char &optional BUFFER
- This function returns the character preceding point in the buffer.
- See above, under `following-char', for an example. If point is at
- the beginning of the buffer, `preceding-char' returns 0. If
- optional argument BUFFER is `nil', the current buffer is assumed.
-
- - Function: bobp &optional BUFFER
- This function returns `t' if point is at the beginning of the
- buffer. If narrowing is in effect, this means the beginning of the
- accessible portion of the text. If optional argument BUFFER is
- `nil', the current buffer is assumed. See also `point-min' in
- *Note Point::.
-
- - Function: eobp &optional BUFFER
- This function returns `t' if point is at the end of the buffer.
- If narrowing is in effect, this means the end of accessible
- portion of the text. If optional argument BUFFER is `nil', the
- current buffer is assumed. See also `point-max' in *Note Point::.
-
- - Function: bolp &optional BUFFER
- This function returns `t' if point is at the beginning of a line.
- If optional argument BUFFER is `nil', the current buffer is
- assumed. *Note Text Lines::. The beginning of the buffer (or its
- accessible portion) always counts as the beginning of a line.
-
- - Function: eolp &optional BUFFER
- This function returns `t' if point is at the end of a line. The
- end of the buffer is always considered the end of a line. If
- optional argument BUFFER is `nil', the current buffer is assumed.
- The end of the buffer (or of its accessible portion) is always
- considered the end of a line.
+Motion by Characters
+--------------------
+
+ These functions move point based on a count of characters.
+`goto-char' is the fundamental primitive; the other functions use that.
+
+ - Command: goto-char position &optional buffer
+ This function sets point in `buffer' to the value POSITION. If
+ POSITION is less than 1, it moves point to the beginning of the
+ buffer. If POSITION is greater than the length of the buffer, it
+ moves point to the end. BUFFER defaults to the current buffer if
+ omitted.
+
+ If narrowing is in effect, POSITION still counts from the
+ beginning of the buffer, but point cannot go outside the accessible
+ portion. If POSITION is out of range, `goto-char' moves point to
+ the beginning or the end of the accessible portion.
+
+ When this function is called interactively, POSITION is the
+ numeric prefix argument, if provided; otherwise it is read from the
+ minibuffer.
+
+ `goto-char' returns POSITION.
+
+ - Command: forward-char &optional count buffer
+ This function moves point COUNT characters forward, towards the
+ end of the buffer (or backward, towards the beginning of the
+ buffer, if COUNT is negative). If the function attempts to move
+ point past the beginning or end of the buffer (or the limits of
+ the accessible portion, when narrowing is in effect), an error is
+ signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+ BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ - Command: backward-char &optional count buffer
+ This function moves point COUNT characters backward, towards the
+ beginning of the buffer (or forward, towards the end of the
+ buffer, if COUNT is negative). If the function attempts to move
+ point past the beginning or end of the buffer (or the limits of
+ the accessible portion, when narrowing is in effect), an error is
+ signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+ BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is the numeric prefix argument.
\1f
-File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
+File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
-Examining Buffer Contents
-=========================
+Motion by Words
+---------------
- This section describes two functions that allow a Lisp program to
-convert any portion of the text in the buffer into a string.
+ These functions for parsing words use the syntax table to decide
+whether a given character is part of a word. *Note Syntax Tables::.
- - Function: buffer-substring START END &optional BUFFER
- - Function: buffer-string START END &optional BUFFER
- These functions are equivalent and return a string containing a
- copy of the text of the region defined by positions START and END
- in the buffer. If the arguments are not positions in the
- accessible portion of the buffer, `buffer-substring' signals an
- `args-out-of-range' error. If optional argument BUFFER is `nil',
- the current buffer is assumed.
+ - Command: forward-word &optional count buffer
+ This function moves point forward COUNT words (or backward if
+ COUNT is negative). Normally it returns `t'. If this motion
+ encounters the beginning or end of the buffer, or the limits of the
+ accessible portion when narrowing is in effect, point stops there
+ and the value is `nil'.
- If the region delineated by START and END contains duplicable
- extents, they will be remembered in the string. *Note Duplicable
- Extents::.
+ COUNT defaults to `1' and BUFFER defaults to the current buffer.
- It is not necessary for START to be less than END; the arguments
- can be given in either order. But most often the smaller argument
- is written first.
+ In an interactive call, COUNT is set to the numeric prefix
+ argument.
- ---------- Buffer: foo ----------
- This is the contents of buffer foo
-
- ---------- Buffer: foo ----------
-
- (buffer-substring 1 10)
- => "This is t"
- (buffer-substring (point-max) 10)
- => "he contents of buffer foo
- "
+ - Command: backward-word &optional count buffer
+ This function is just like `forward-word', except that it moves
+ backward until encountering the front of a word, rather than
+ forward. BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is set to the numeric prefix
+ argument.
+
+ - Variable: words-include-escapes
+ This variable affects the behavior of `forward-word' and everything
+ that uses it. If it is non-`nil', then characters in the "escape"
+ and "character quote" syntax classes count as part of words.
+ Otherwise, they do not.
\1f
-File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
+File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
-Comparing Text
-==============
+Motion to an End of the Buffer
+------------------------------
+
+ To move point to the beginning of the buffer, write:
+
+ (goto-char (point-min))
- This function lets you compare portions of the text in a buffer,
-without copying them into strings first.
+Likewise, to move to the end of the buffer, use:
- - Function: compare-buffer-substrings BUFFER1 START1 END1 BUFFER2
- START2 END2
- This function lets you compare two substrings of the same buffer
- or two different buffers. The first three arguments specify one
- substring, giving a buffer and two positions within the buffer.
- The last three arguments specify the other substring in the same
- way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
- the current buffer.
+ (goto-char (point-max))
- The value is negative if the first substring is less, positive if
- the first is greater, and zero if they are equal. The absolute
- value of the result is one plus the index of the first differing
- characters within the substrings.
+ Here are two commands that users use to do these things. They are
+documented here to warn you not to use them in Lisp programs, because
+they set the mark and display messages in the echo area.
- This function ignores case when comparing characters if
- `case-fold-search' is non-`nil'. It always ignores text
- properties.
+ - Command: beginning-of-buffer &optional count
+ This function moves point to the beginning of the buffer (or the
+ limits of the accessible portion, when narrowing is in effect),
+ setting the mark at the previous position. If COUNT is non-`nil',
+ then it puts point COUNT tenths of the way from the beginning of
+ the buffer.
- Suppose the current buffer contains the text `foobarbar
- haha!rara!'; then in this example the two substrings are `rbar '
- and `rara!'. The value is 2 because the first substring is greater
- at the second character.
+ In an interactive call, COUNT is the numeric prefix argument, if
+ provided; otherwise COUNT defaults to `nil'.
- (compare-buffer-substring nil 6 11 nil 16 21)
- => 2
+ Don't use this function in Lisp programs!
+
+ - Command: end-of-buffer &optional count
+ This function moves point to the end of the buffer (or the limits
+ of the accessible portion, when narrowing is in effect), setting
+ the mark at the previous position. If COUNT is non-`nil', then it
+ puts point COUNT tenths of the way from the end of the buffer.
+
+ In an interactive call, COUNT is the numeric prefix argument, if
+ provided; otherwise COUNT defaults to `nil'.
+
+ Don't use this function in Lisp programs!
\1f
-File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
-
-Inserting Text
-==============
-
- "Insertion" means adding new text to a buffer. The inserted text
-goes at point--between the character before point and the character
-after point.
-
- Insertion relocates markers that point at positions after the
-insertion point, so that they stay with the surrounding text (*note
-Markers::.). When a marker points at the place of insertion, insertion
-normally doesn't relocate the marker, so that it points to the
-beginning of the inserted text; however, certain special functions such
-as `insert-before-markers' relocate such markers to point after the
-inserted text.
-
- Some insertion functions leave point before the inserted text, while
-other functions leave it after. We call the former insertion "after
-point" and the latter insertion "before point".
-
- If a string with non-`nil' extent data is inserted, the remembered
-extents will also be inserted. *Note Duplicable Extents::.
-
- Insertion functions signal an error if the current buffer is
-read-only.
-
- These functions copy text characters from strings and buffers along
-with their properties. The inserted characters have exactly the same
-properties as the characters they were copied from. By contrast,
-characters specified as separate arguments, not part of a string or
-buffer, inherit their text properties from the neighboring text.
-
- - Function: insert &rest ARGS
- This function inserts the strings and/or characters ARGS into the
- current buffer, at point, moving point forward. In other words, it
- inserts the text before point. An error is signaled unless all
- ARGS are either strings or characters. The value is `nil'.
-
- - Function: insert-before-markers &rest ARGS
- This function inserts the strings and/or characters ARGS into the
- current buffer, at point, moving point forward. An error is
- signaled unless all ARGS are either strings or characters. The
- value is `nil'.
-
- This function is unlike the other insertion functions in that it
- relocates markers initially pointing at the insertion point, to
- point after the inserted text.
-
- - Function: insert-string STRING &optional BUFFER
- This function inserts STRING into BUFFER before point. BUFFER
- defaults to the current buffer if omitted. This function is
- chiefly useful if you want to insert a string in a buffer other
- than the current one (otherwise you could just use `insert').
-
- - Function: insert-char CHARACTER COUNT &optional BUFFER
- This function inserts COUNT instances of CHARACTER into BUFFER
- before point. COUNT must be a number, and CHARACTER must be a
- character. The value is `nil'. If optional argument BUFFER is
- `nil', the current buffer is assumed. (In FSF Emacs, the third
- argument is called INHERIT and refers to text properties.)
-
- - Function: insert-buffer-substring FROM-BUFFER-OR-NAME &optional
- START END
- This function inserts a portion of buffer FROM-BUFFER-OR-NAME
- (which must already exist) into the current buffer before point.
- The text inserted is the region from START and END. (These
- arguments default to the beginning and end of the accessible
- portion of that buffer.) This function returns `nil'.
-
- In this example, the form is executed with buffer `bar' as the
- current buffer. We assume that buffer `bar' is initially empty.
+File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
+
+Motion by Text Lines
+--------------------
+
+ Text lines are portions of the buffer delimited by newline
+characters, which are regarded as part of the previous line. The first
+text line begins at the beginning of the buffer, and the last text line
+ends at the end of the buffer whether or not the last character is a
+newline. The division of the buffer into text lines is not affected by
+the width of the window, by line continuation in display, or by how
+tabs and control characters are displayed.
+
+ - Command: goto-line line
+ This function moves point to the front of the LINEth line,
+ counting from line 1 at beginning of the buffer. If LINE is less
+ than 1, it moves point to the beginning of the buffer. If LINE is
+ greater than the number of lines in the buffer, it moves point to
+ the end of the buffer--that is, the _end of the last line_ of the
+ buffer. This is the only case in which `goto-line' does not
+ necessarily move to the beginning of a line.
+
+ If narrowing is in effect, then LINE still counts from the
+ beginning of the buffer, but point cannot go outside the accessible
+ portion. So `goto-line' moves point to the beginning or end of the
+ accessible portion, if the line number specifies an inaccessible
+ position.
+
+ The return value of `goto-line' is the difference between LINE and
+ the line number of the line to which point actually was able to
+ move (in the full buffer, before taking account of narrowing).
+ Thus, the value is positive if the scan encounters the real end of
+ the buffer. The value is zero if scan encounters the end of the
+ accessible portion but not the real end of the buffer.
+
+ In an interactive call, LINE is the numeric prefix argument if one
+ has been provided. Otherwise LINE is read in the minibuffer.
+
+ - Command: beginning-of-line &optional count buffer
+ This function moves point to the beginning of the current line.
+ With an argument COUNT not `nil' or 1, it moves forward COUNT-1
+ lines and then to the beginning of the line. BUFFER defaults to
+ the current buffer if omitted.
+
+ If this function reaches the end of the buffer (or of the
+ accessible portion, if narrowing is in effect), it positions point
+ there. No error is signaled.
+
+ - Command: end-of-line &optional count buffer
+ This function moves point to the end of the current line. With an
+ argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
+ then to the end of the line. BUFFER defaults to the current
+ buffer if omitted.
+
+ If this function reaches the end of the buffer (or of the
+ accessible portion, if narrowing is in effect), it positions point
+ there. No error is signaled.
+
+ - Command: forward-line &optional count buffer
+ This function moves point forward COUNT lines, to the beginning of
+ the line. If COUNT is negative, it moves point -COUNT lines
+ backward, to the beginning of a line. If COUNT is zero, it moves
+ point to the beginning of the current line. BUFFER defaults to
+ the current buffer if omitted.
+
+ If `forward-line' encounters the beginning or end of the buffer (or
+ of the accessible portion) before finding that many lines, it sets
+ point there. No error is signaled.
+
+ `forward-line' returns the difference between COUNT and the number
+ of lines actually moved. If you attempt to move down five lines
+ from the beginning of a buffer that has only three lines, point
+ stops at the end of the last line, and the value will be 2.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ - Function: count-lines start end &optional ignore-invisible-lines-flag
+ This function returns the number of lines between the positions
+ START and END in the current buffer. If START and END are equal,
+ then it returns 0. Otherwise it returns at least 1, even if START
+ and END are on the same line. This is because the text between
+ them, considered in isolation, must contain at least one line
+ unless it is empty.
+
+ With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines
+ collapsed with selective-display are excluded from the line count.
+
+ *Note:* The expression to return the current line number is not
+ obvious:
+
+ (1+ (count-lines 1 (point-at-bol)))
+
+ Here is an example of using `count-lines':
+
+ (defun current-line ()
+ "Return the vertical position of point..."
+ (+ (count-lines (window-start) (point))
+ (if (= (current-column) 0) 1 0)
+ -1))
+
+ Also see the functions `bolp' and `eolp' in *Note Near Point::.
+These functions do not move point, but test whether it is already at the
+beginning or end of a line.
+
+\1f
+File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
+
+Motion by Screen Lines
+----------------------
+
+ The line functions in the previous section count text lines,
+delimited only by newline characters. By contrast, these functions
+count screen lines, which are defined by the way the text appears on
+the screen. A text line is a single screen line if it is short enough
+to fit the width of the selected window, but otherwise it may occupy
+several screen lines.
+
+ In some cases, text lines are truncated on the screen rather than
+continued onto additional screen lines. In these cases,
+`vertical-motion' moves point much like `forward-line'. *Note
+Truncation::.
+
+ Because the width of a given string depends on the flags that control
+the appearance of certain characters, `vertical-motion' behaves
+differently, for a given piece of text, depending on the buffer it is
+in, and even on the selected window (because the width, the truncation
+flag, and display table may vary between windows). *Note Usual
+Display::.
+
+ These functions scan text to determine where screen lines break, and
+thus take time proportional to the distance scanned. If you intend to
+use them heavily, Emacs provides caches which may improve the
+performance of your code. *Note cache-long-line-scans: Text Lines.
+
+ - Function: vertical-motion count &optional window pixels
+ This function moves point to the start of the frame line COUNT
+ frame lines down from the frame line containing point. If COUNT
+ is negative, it moves up instead. The optional second argument
+ WINDOW may be used to specify a window other than the selected
+ window in which to perform the motion.
+
+ Normally, `vertical-motion' returns the number of lines moved. The
+ value may be less in absolute value than COUNT if the beginning or
+ end of the buffer was reached. If the optional third argument,
+ PIXELS is non-`nil', the vertical pixel height of the motion which
+ took place is returned instead of the actual number of lines
+ moved. A motion of zero lines returns the height of the current
+ line.
+
+ Note that `vertical-motion' sets WINDOW's buffer's point, not
+ WINDOW's point. (This differs from FSF Emacs, which buggily always
+ sets current buffer's point, regardless of WINDOW.)
+
+ - Function: vertical-motion-pixels count &optional window how
+ This function moves point to the start of the frame line PIXELS
+ vertical pixels down from the frame line containing point, or up if
+ PIXELS is negative. The optional second argument WINDOW is the
+ window to move in, and defaults to the selected window. The
+ optional third argument HOW specifies the stopping condition. A
+ negative integer indicates that the motion should be no more than
+ PIXELS. A positive value indicates that the motion should be at
+ least PIXELS. Any other value indicates that the motion should be
+ as close as possible to PIXELS.
+
+ - Command: move-to-window-line count &optional window
+ This function moves point with respect to the text currently
+ displayed in WINDOW, which defaults to the selected window. It
+ moves point to the beginning of the screen line COUNT screen lines
+ from the top of the window. If COUNT is negative, that specifies a
+ position -COUNT lines from the bottom (or the last line of the
+ buffer, if the buffer ends above the specified screen position).
+
+ If COUNT is `nil', then point moves to the beginning of the line
+ in the middle of the window. If the absolute value of COUNT is
+ greater than the size of the window, then point moves to the place
+ that would appear on that screen line if the window were tall
+ enough. This will probably cause the next redisplay to scroll to
+ bring that location onto the screen.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ The value returned is the window line number point has moved to,
+ with the top line in the window numbered 0.
+
+\1f
+File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
+
+Moving over Balanced Expressions
+--------------------------------
+
+ Here are several functions concerned with balanced-parenthesis
+expressions (also called "sexps" in connection with moving across them
+in XEmacs). The syntax table controls how these functions interpret
+various characters; see *Note Syntax Tables::. *Note Parsing
+Expressions::, for lower-level primitives for scanning sexps or parts of
+sexps. For user-level commands, see *Note Lists and Sexps:
+(xemacs)Lists and Sexps.
+
+ - Command: forward-list &optional arg
+ This function moves forward across ARG balanced groups of
+ parentheses. (Other syntactic entities such as words or paired
+ string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
+ is negative, move backward across that many groups of parentheses.
+
+ - Command: backward-list &optional count
+ This function moves backward across COUNT balanced groups of
+ parentheses. (Other syntactic entities such as words or paired
+ string quotes are ignored.) COUNT defaults to 1 if omitted. If
+ COUNT is negative, move forward across that many groups of
+ parentheses.
+
+ - Command: up-list &optional count
+ This function moves forward out of COUNT levels of parentheses. A
+ negative argument means move backward but still to a less deep
+ spot.
+
+ - Command: down-list &optional count
+ This function moves forward into COUNT levels of parentheses. A
+ negative argument means move backward but still go deeper in
+ parentheses (-COUNT levels).
+
+ - Command: forward-sexp &optional count
+ This function moves forward across COUNT balanced expressions.
+ Balanced expressions include both those delimited by parentheses
+ and other kinds, such as words and string constants. COUNT
+ defaults to 1 if omitted. If COUNT is negative, move backward
+ across that many balanced expressions. For example,
---------- Buffer: foo ----------
- We hold these truths to be self-evident, that all
+ (concat-!- "foo " (car x) y z)
---------- Buffer: foo ----------
- (insert-buffer-substring "foo" 1 20)
+ (forward-sexp 3)
=> nil
- ---------- Buffer: bar ----------
- We hold these truth-!-
- ---------- Buffer: bar ----------
+ ---------- Buffer: foo ----------
+ (concat "foo " (car x) y-!- z)
+ ---------- Buffer: foo ----------
+
+ - Command: backward-sexp &optional count
+ This function moves backward across COUNT balanced expressions.
+ COUNT defaults to 1 if omitted. If COUNT is negative, move
+ forward across that many balanced expressions.
+
+ - Command: beginning-of-defun &optional count
+ This function moves back to the COUNTth beginning of a defun. If
+ COUNT is negative, this actually moves forward, but it still moves
+ to the beginning of a defun, not to the end of one. COUNT
+ defaults to 1 if omitted.
+
+ - Command: end-of-defun &optional count
+ This function moves forward to the COUNTth end of a defun. If
+ COUNT is negative, this actually moves backward, but it still
+ moves to the end of a defun, not to the beginning of one. COUNT
+ defaults to 1 if omitted.
+
+ - User Option: defun-prompt-regexp
+ If non-`nil', this variable holds a regular expression that
+ specifies what text can appear before the open-parenthesis that
+ starts a defun. That is to say, a defun begins on a line that
+ starts with a match for this regular expression, followed by a
+ character with open-parenthesis syntax.
projects / chise / xemacs-chise.git- / blobdiff