-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-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 minibuf
- The function `next-frame' lets you cycle conveniently through all
- the frames from an arbitrary starting point. It returns the "next"
- frame after FRAME in the cycle. If FRAME is omitted or `nil', it
- defaults to the selected frame.
-
- The second argument, MINIBUF, says which frames to consider:
-
- `nil'
- Exclude minibuffer-only frames.
-
- `visible'
- Consider all visible frames.
-
- 0
- Consider all visible or iconified frames.
-
- a window
- Consider only the frames using that particular window as their
- minibuffer.
-
- the symbol `visible'
- Include all visible frames.
+File: lispref.info, Node: Window Start, Next: Vertical Scrolling, Prev: Window Point, Up: Windows
+
+The Window Start Position
+=========================
+
+ Each window contains a marker used to keep track of a buffer position
+that specifies where in the buffer display should start. This position
+is called the "display-start" position of the window (or just the
+"start"). The character after this position is the one that appears at
+the upper left corner of the window. It is usually, but not
+inevitably, at the beginning of a text line.
+
+ - Function: window-start &optional window
+ This function returns the display-start position of window WINDOW.
+ If WINDOW is `nil', the selected window is used. For example,
+
+ (window-start)
+ => 7058
+
+ When you create a window, or display a different buffer in it, the
+ display-start position is set to a display-start position recently
+ used for the same buffer, or 1 if the buffer doesn't have any.
+
+ For a realistic example, see the description of `count-lines' in
+ *Note Text Lines::.
+
+ - Function: window-end &optional window guarantee
+ This function returns the position of the end of the display in
+ window WINDOW. If WINDOW is `nil', the selected window is used.
+
+ Simply changing the buffer text or setting `window-start' does not
+ update the value that `window-end' returns. The value is updated
+ only when Emacs redisplays and redisplay actually finishes.
+
+ If the last redisplay of WINDOW was preempted, and did not finish,
+ Emacs does not know the position of the end of display in that
+ window. In that case, this function returns a value that is not
+ correct. In a future version, `window-end' will return `nil' in
+ that case.
+
+ If optional arg GUARANTEE is non-`nil', the return value is
+ guaranteed to be the same as `window-end' would return at the end
+ of the next full redisplay assuming nothing else changes in the
+ meantime. This function is potentially much slower with this flag
+ set.
+
+
+ - Function: set-window-start window position &optional noforce
+ This function sets the display-start position of WINDOW to
+ POSITION in WINDOW's buffer. It returns POSITION.
+
+ The display routines insist that the position of point be visible
+ when a buffer is displayed. Normally, they change the
+ display-start position (that is, scroll the window) whenever
+ necessary to make point visible. However, if you specify the
+ start position with this function using `nil' for NOFORCE, it
+ means you want display to start at POSITION even if that would put
+ the location of point off the screen. If this does place point
+ off screen, the display routines move point to the left margin on
+ the middle line in the window.
+
+ For example, if point is 1 and you set the start of the window
+ to 2, then point would be "above" the top of the window. The
+ display routines will automatically move point if it is still 1
+ when redisplay occurs. Here is an example:
+
+ ;; Here is what `foo' looks like before executing
+ ;; the `set-window-start' expression.
+
+ ---------- Buffer: foo ----------
+ -!-This is the contents of buffer foo.
+ 2
+ 3
+ 4
+ 5
+ 6
+ ---------- Buffer: foo ----------
+
+ (set-window-start
+ (selected-window)
+ (1+ (window-start)))
+ => 2
+
+ ;; Here is what `foo' looks like after executing
+ ;; the `set-window-start' expression.
+ ---------- Buffer: foo ----------
+ his is the contents of buffer foo.
+ 2
+ 3
+ -!-4
+ 5
+ 6
+ ---------- Buffer: foo ----------
- `0'
- Include all visible and iconified frames.
+ If NOFORCE is non-`nil', and POSITION would place point off screen
+ at the next redisplay, then redisplay computes a new window-start
+ position that works well with point, and thus POSITION is not used.
- anything else
- Consider all frames.
+ - Function: pos-visible-in-window-p &optional position window
+ This function returns `t' if POSITION is within the range of text
+ currently visible on the screen in WINDOW. It returns `nil' if
+ POSITION is scrolled vertically out of view. The argument
+ POSITION defaults to the current position of point; WINDOW, to the
+ selected window. Here is an example:
- - Function: previous-frame &optional frame minibuf
- Like `next-frame', but cycles through all frames in the opposite
- direction.
+ (or (pos-visible-in-window-p
+ (point) (selected-window))
+ (recenter 0))
- See also `next-window' and `previous-window', in *Note Cyclic Window
-Ordering::.
+ The `pos-visible-in-window-p' function considers only vertical
+ scrolling. If POSITION is out of view only because WINDOW has
+ been scrolled horizontally, `pos-visible-in-window-p' returns `t'.
+ *Note Horizontal Scrolling::.
\1f
-File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
+File: lispref.info, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows
-Frames and Windows
+Vertical Scrolling
==================
- Each window is part of one and only one frame; you can get the frame
-with `window-frame'.
-
- - Function: frame-root-window &optional frame
- This returns the root window of frame FRAME. FRAME defaults to
- the selected frame if not specified.
-
- - Function: window-frame &optional window
- This function returns the frame that WINDOW is on. WINDOW
- defaults to the selected window if omitted.
-
- 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.
-
- - Function: frame-top-window frame
- This returns the topmost, leftmost window of frame FRAME.
-
- At any time, exactly one window on any frame is "selected within the
-frame". The significance of this designation is that selecting the
-frame also selects this window. You can get the frame's current
-selected window with `frame-selected-window'.
-
- - Function: frame-selected-window &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: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
-
-Minibuffers and Frames
-======================
-
- Normally, each frame has its own minibuffer window at the bottom,
-which is used whenever that frame is selected. If the frame has a
-minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
-Misc::).
-
- However, you can also create a frame with no minibuffer. Such a
-frame must use the minibuffer window of some other frame. When you
-create the frame, you can specify explicitly the 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.
-
- - Variable: default-minibuffer-frame
- This variable specifies the frame to use for the minibuffer
- window, by default.
-
-\1f
-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'.
-
- - Macro: save-selected-frame forms...
- This macro records the selected frame, executes FORMS in sequence,
- then restores the earlier selected frame. The value returned is
- the value of the last form.
-
- - Macro: with-selected-frame frame forms...
- This macro 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.
+ Vertical scrolling means moving the text up or down in a window. It
+works by changing the value of the window's display-start location. It
+may also change the value of `window-point' to keep it on the screen.
+
+ In the commands `scroll-up' and `scroll-down', the directions "up"
+and "down" refer to the motion of the text in the buffer at which you
+are looking through the window. Imagine that the text is written on a
+long roll of paper and that the scrolling commands move the paper up
+and down. Thus, if you are looking at text in the middle of a buffer
+and repeatedly call `scroll-down', you will eventually see the
+beginning of the buffer.
+
+ Some people have urged that the opposite convention be used: they
+imagine that the window moves over text that remains in place. Then
+"down" commands would take you to the end of the buffer. This view is
+more consistent with the actual relationship between windows and the
+text in the buffer, but it is less like what the user sees. The
+position of a window on the terminal does not move, and short scrolling
+commands clearly move the text up or down on the screen. We have chosen
+names that fit the user's point of view.
+
+ The scrolling functions (aside from `scroll-other-window') have
+unpredictable results if the current buffer is different from the buffer
+that is displayed in the selected window. *Note Current Buffer::.
+
+ - Command: scroll-up &optional lines
+ This function scrolls the text in the selected window upward LINES
+ lines. If LINES is negative, scrolling is actually downward.
+
+ If LINES is `nil' (or omitted), then the length of scroll is
+ `next-screen-context-lines' lines less than the usable height of
+ the window (not counting its modeline).
+
+ `scroll-up' returns `nil'.
+
+ - Command: scroll-down &optional lines
+ This function scrolls the text in the selected window downward
+ LINES lines. If LINES is negative, scrolling is actually upward.
+
+ If LINES is omitted or `nil', then the length of the scroll is
+ `next-screen-context-lines' lines less than the usable height of
+ the window (not counting its mode line).
+
+ `scroll-down' returns `nil'.
+
+ - Command: scroll-other-window &optional lines
+ This function scrolls the text in another window upward LINES
+ lines. Negative values of LINES, or `nil', are handled as in
+ `scroll-up'.
+
+ You can specify a buffer to scroll with the variable
+ `other-window-scroll-buffer'. When the selected window is the
+ minibuffer, the next window is normally the one at the top left
+ corner. You can specify a different window to scroll with the
+ variable `minibuffer-scroll-window'. This variable has no effect
+ when any other window is selected. *Note Minibuffer Misc::.
+
+ When the minibuffer is active, it is the next window if the
+ selected window is the one at the bottom right corner. In this
+ case, `scroll-other-window' attempts to scroll the minibuffer. If
+ the minibuffer contains just one line, it has nowhere to scroll
+ to, so the line reappears after the echo area momentarily displays
+ the message "Beginning of buffer".
+
+ - Variable: other-window-scroll-buffer
+ If this variable is non-`nil', it tells `scroll-other-window'
+ which buffer to scroll.
+
+ - User Option: scroll-step
+ This variable controls how scrolling is done automatically when
+ point moves off the screen. If the value is zero, then redisplay
+ scrolls the text to center point vertically in the window. If the
+ value is a positive integer N, then redisplay brings point back on
+ screen by scrolling N lines in either direction, if possible;
+ otherwise, it centers point. The default value is zero.
+
+ - User Option: scroll-conservatively
+ This variable controls how many lines Emacs tries to scroll before
+ recentering. If you set it to a small number, then when you move
+ point a short distance off the screen, XEmacs will scroll the
+ screen just far enough to bring point back on screen, provided
+ that does not exceed `scroll-conservatively' lines. This variable
+ overrides the redisplay preemption.
+
+ - User Option: next-screen-context-lines
+ The value of this variable is the number of lines of continuity to
+ retain when scrolling by full screens. For example, `scroll-up'
+ with an argument of `nil' scrolls so that this many lines at the
+ bottom of the window appear instead at the top. The default value
+ is `2'.
+
+ - Command: recenter &optional location window
+ This function scrolls WINDOW (which defaults to the selected
+ window) to put the text where point is located at a specified
+ vertical position within the window.
+
+ If LOCATION is a nonnegative number, it puts the line containing
+ point LOCATION lines down from the top of the window. If LOCATION
+ is a negative number, then it counts upward from the bottom of the
+ window, so that -1 stands for the last usable line in the window.
+ If LOCATION is a non-`nil' list, then it stands for the line in
+ the middle of the window.
+
+ If LOCATION is `nil', `recenter' puts the line containing point in
+ the middle of the window, then clears and redisplays the entire
+ selected frame.
+
+ When `recenter' is called interactively, LOCATION is the raw
+ prefix argument. Thus, typing `C-u' as the prefix sets the
+ LOCATION to a non-`nil' list, while typing `C-u 4' sets LOCATION
+ to 4, which positions the current line four lines from the top.
+
+ With an argument of zero, `recenter' positions the current line at
+ the top of the window. This action is so handy that some people
+ make a separate key binding to do this. For example,
+
+ (defun line-to-top-of-window ()
+ "Scroll current line to top of window.
+ Replaces three keystroke sequence C-u 0 C-l."
+ (interactive)
+ (recenter 0))
+
+ (global-set-key [kp-multiply] 'line-to-top-of-window)
\1f
-File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
+File: lispref.info, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows
-Visibility of Frames
+Horizontal Scrolling
====================
- An X window frame may be "visible", "invisible", or "iconified". If
-it is visible, you can see its contents. If it is iconified, the
-frame's contents do not appear on the screen, but an icon does. If the
-frame is invisible, it doesn't show on the screen, not even as an icon.
-
- Visibility is meaningless for TTY frames, since only the selected
-one is actually displayed in any case.
-
- - Command: make-frame-visible &optional frame
- This function makes frame FRAME visible. If you omit FRAME, it
- makes the selected frame visible.
-
- - Command: make-frame-invisible &optional frame
- This function makes frame FRAME invisible.
-
- - Command: iconify-frame &optional frame
- This function iconifies frame FRAME.
-
- - Command: deiconify-frame &optional frame
- This function de-iconifies frame FRAME. Under X, this is
- equivalent to `make-frame-visible'.
-
- - Function: frame-visible-p 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 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 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: 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'.
+ Because we read English first from top to bottom and second from left
+to right, horizontal scrolling is not like vertical scrolling. Vertical
+scrolling involves selection of a contiguous portion of text to display.
+Horizontal scrolling causes part of each line to go off screen. The
+amount of horizontal scrolling is therefore specified as a number of
+columns rather than as a position in the buffer. It has nothing to do
+with the display-start position returned by `window-start'.
+
+ Usually, no horizontal scrolling is in effect; then the leftmost
+column is at the left edge of the window. In this state, scrolling to
+the right is meaningless, since there is no data to the left of the
+screen to be revealed by it; so this is not allowed. Scrolling to the
+left is allowed; it scrolls the first columns of text off the edge of
+the window and can reveal additional columns on the right that were
+truncated before. Once a window has a nonzero amount of leftward
+horizontal scrolling, you can scroll it back to the right, but only so
+far as to reduce the net horizontal scroll to zero. There is no limit
+to how far left you can scroll, but eventually all the text will
+disappear off the left edge.
+
+ - Command: scroll-left &optional count
+ This function scrolls the selected window COUNT columns to the
+ left (or to the right if COUNT is negative). The return value is
+ the total amount of leftward horizontal scrolling in effect after
+ the change--just like the value returned by `window-hscroll'
+ (below).
+
+ - Command: scroll-right &optional count
+ This function scrolls the selected window COUNT columns to the
+ right (or to the left if COUNT is negative). The return value is
+ the total amount of leftward horizontal scrolling in effect after
+ the change--just like the value returned by `window-hscroll'
+ (below).
+
+ Once you scroll a window as far right as it can go, back to its
+ normal position where the total leftward scrolling is zero,
+ attempts to scroll any farther right have no effect.
+
+ - Function: window-hscroll &optional window
+ This function returns the total leftward horizontal scrolling of
+ WINDOW--the number of columns by which the text in WINDOW is
+ scrolled left past the left margin.
+
+ The value is never negative. It is zero when no horizontal
+ scrolling has been done in WINDOW (which is usually the case).
+
+ If WINDOW is `nil', the selected window is used.
+
+ (window-hscroll)
+ => 0
+ (scroll-left 5)
+ => 5
+ (window-hscroll)
+ => 5
+
+ - Function: set-window-hscroll window columns
+ This function sets the number of columns from the left margin that
+ WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS
+ should be zero or positive; if not, it is taken as zero.
+
+ The value returned is COLUMNS.
+
+ (set-window-hscroll (selected-window) 10)
+ => 10
+
+ Here is how you can determine whether a given position POSITION is
+off the screen due to horizontal scrolling:
+
+ (defun hscroll-on-screen (window position)
+ (save-excursion
+ (goto-char position)
+ (and
+ (>= (- (current-column) (window-hscroll window)) 0)
+ (< (- (current-column) (window-hscroll window))
+ (window-width window)))))
\1f
-File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
+File: lispref.info, Node: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows
-Frame Configurations
+The Size of a Window
====================
- A "frame configuration" records the current arrangement of frames,
-all their properties, and the window configuration of each one.
-
- - Function: current-frame-configuration
- This function returns a frame configuration list that describes
- the current arrangement of frames and their contents.
-
- - Function: set-frame-configuration configuration
- This function restores the state of frames described in
- CONFIGURATION.
+ An Emacs window is rectangular, and its size information consists of
+the height (in lines or pixels) and the width (in character positions
+or pixels). The modeline is included in the height. The pixel width
+and height values include scrollbars and margins, while the
+line/character-position values do not.
+
+ Note that the height in lines, and the width in characters, are
+determined by dividing the corresponding pixel value by the height or
+width of the default font in that window (if this is a variable-width
+font, the average width is used). The resulting values may or may not
+represent the actual number of lines in the window, or the actual number
+of character positions in any particular line, esp. if there are pixmaps
+or various different fonts in the window.
+
+ The following functions return size information about a window:
+
+ - Function: window-height &optional window
+ This function returns the number of lines in WINDOW, including its
+ modeline but not including the horizontal scrollbar, if any (this
+ is different from `window-pixel-height'). If WINDOW is `nil', the
+ function uses the selected window.
+
+ (window-height)
+ => 40
+ (split-window-vertically)
+ => #<window on "windows.texi" 0x679b>
+ (window-height)
+ => 20
+
+ - Function: window-width &optional window
+ This function returns the number of columns in WINDOW, not
+ including any left margin, right margin, or vertical scrollbar
+ (this is different from `window-pixel-width'). If WINDOW is
+ `nil', the function uses the selected window.
+
+ (window-width)
+ => 80
+ (window-height)
+ => 40
+ (split-window-horizontally)
+ => #<window on "windows.texi" 0x7538>
+ (window-width)
+ => 39
+
+ Note that after splitting the window into two side-by-side windows,
+the width of each window is less the half the width of the original
+window because a vertical scrollbar appeared between the windows,
+occupying two columns worth of space. Also, the height shrunk by one
+because horizontal scrollbars appeared that weren't there before.
+(Horizontal scrollbars appear only when lines are truncated, not when
+they wrap. This is usually the case for horizontally split windows but
+not for full-frame windows. You can change this using the variables
+`truncate-lines' and `truncate-partial-width-windows'.)
+
+ - Function: window-pixel-height &optional window
+ This function returns the height of WINDOW in pixels, including
+ its modeline and horizontal scrollbar, if any. If WINDOW is
+ `nil', the function uses the selected window.
+
+ (window-pixel-height)
+ => 600
+ (split-window-vertically)
+ => #<window on "windows.texi" 0x68a6>
+ (window-pixel-height)
+ => 300
+
+ - Function: window-pixel-width &optional window
+ This function returns the width of WINDOW in pixels, including any
+ left margin, right margin, or vertical scrollbar that may be
+ displayed alongside it. If WINDOW is `nil', the function uses the
+ selected window.
+
+ (window-pixel-width)
+ => 735
+ (window-pixel-height)
+ => 600
+ (split-window-horizontally)
+ => #<window on "windows.texi" 0x7538>
+ (window-pixel-width)
+ => 367
+ (window-pixel-height)
+ => 600
+
+ - Function: window-text-area-pixel-height &optional window
+ This function returns the height in pixels of the text displaying
+ portion of WINDOW, which defaults to the selected window. Unlike
+ `window-pixel-height', the space occupied by the modeline and
+ horizontal scrollbar, if any, is not counted.
+
+ - Function: window-text-area-pixel-width &optional window
+ This function returns the width in pixels of the text displaying
+ portion of WINDOW, which defaults to the selected window. Unlike
+ `window-pixel-width', the space occupied by the vertical scrollbar
+ and divider, if any, is not counted.
+
+ - Function: window-displayed-text-pixel-height &optional window
+ noclipped
+ This function returns the height in pixels of the text displayed in
+ WINDOW, which defaults to the selected window. Unlike
+ `window-text-area-pixel-height', any blank space below the end of
+ the buffer is not included. If optional argument NOCLIPPED is
+ non-`nil', any space occupied by clipped lines will not be
+ included.
\1f
-File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames
-
-Hooks for Customizing Frame Behavior
-====================================
-
- XEmacs provides many hooks that are called at various times during a
-frame's lifetime. *Note Hooks::.
-
- - 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.
-
- - 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.
-
- - 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.
-
- 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.
-
- - 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.
-
- - 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: 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:
-
-* 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.
+File: lispref.info, Node: Position of Window, Next: Resizing Windows, Prev: Size of Window, Up: Windows
+
+The Position of a Window
+========================
+
+ XEmacs provides functions to determine the absolute location of
+windows within a frame, and the relative location of a window in
+comparison to other windows in the same frame.
+
+ - Function: window-pixel-edges &optional window
+ This function returns a list of the pixel edge coordinates of
+ WINDOW. If WINDOW is `nil', the selected window is used.
+
+ The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements
+ relative to 0, 0 at the top left corner of WINDOW's frame. The
+ element RIGHT of the value is one more than the rightmost pixel
+ used by WINDOW (including any left margin, right margin, or
+ vertical scrollbar displayed alongside it), and BOTTOM is one more
+ than the bottommost pixel used by WINDOW (including any modeline
+ or horizontal scrollbar displayed above or below it). The frame
+ area does not include any frame menubars, toolbars, or gutters
+ that may be displayed; thus, for example, if there is only one
+ window on the frame, the values for LEFT and TOP will always be 0.
+
+ If WINDOW is at the upper left corner of its frame, RIGHT and
+ BOTTOM are the same as the values returned by
+ `(window-pixel-width)' and `(window-pixel-height)' respectively,
+ and LEFT and TOP are zero.
+
+ There is no longer a function `window-edges' because it does not
+make sense in a world with variable-width and variable-height lines, as
+are allowed in XEmacs.
+
+ - Function: window-highest-p window
+ This function returns non-`nil' if WINDOW is along the top of its
+ frame.
+
+ - Function: window-lowest-p window
+ This function returns non-`nil' if WINDOW is along the bottom of
+ its frame.
+
+ - Function: window-text-area-pixel-edges &optional window
+ This function allows one to determine the location of the
+ text-displaying portion of WINDOW, which defaults to the selected
+ window, with respect to the top left corner of the window. It
+ returns a list of integer pixel positions `(left top right
+ bottom)', all relative to `(0,0)' at the top left corner of the
+ window.
\1f
-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.
+File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows
+
+Changing the Size of a Window
+=============================
+
+ The window size functions fall into two classes: high-level commands
+that change the size of windows and low-level functions that access
+window size. XEmacs does not permit overlapping windows or gaps between
+windows, so resizing one window affects other windows.
+
+ - Command: enlarge-window count &optional horizontal window
+ This function makes the selected window COUNT lines taller,
+ stealing lines from neighboring windows. It takes the lines from
+ one window at a time until that window is used up, then takes from
+ another. If a window from which lines are stolen shrinks below
+ `window-min-height' lines, that window disappears.
+
+ If HORIZONTAL is non-`nil', this function makes WINDOW wider by
+ COUNT columns, stealing columns instead of lines. If a window
+ from which columns are stolen shrinks below `window-min-width'
+ columns, that window disappears.
+
+ If the requested size would exceed that of the window's frame,
+ then the function makes the window occupy the entire height (or
+ width) of the frame.
+
+ If COUNT is negative, this function shrinks the window by -COUNT
+ lines or columns. If that makes the window smaller than the
+ minimum size (`window-min-height' and `window-min-width'),
+ `enlarge-window' deletes the window.
+
+ If WINDOW is non-`nil', it specifies a window to change instead of
+ the selected window.
+
+ `enlarge-window' returns `nil'.
+
+ - Command: enlarge-window-horizontally columns
+ This function makes the selected window COLUMNS wider. It could
+ be defined as follows:
+
+ (defun enlarge-window-horizontally (columns)
+ (enlarge-window columns t))
+
+ - Command: enlarge-window-pixels count &optional side window
+ This function makes the selected window COUNT pixels larger. When
+ called from Lisp, optional second argument SIDE non-`nil' means to
+ grow sideways COUNT pixels, and optional third argument WINDOW
+ specifies the window to change instead of the selected window.
+
+ - Command: shrink-window count &optional horizontal window
+ This function is like `enlarge-window' but negates the argument
+ COUNT, making the selected window smaller by giving lines (or
+ columns) to the other windows. If the window shrinks below
+ `window-min-height' or `window-min-width', then it disappears.
+
+ If COUNT is negative, the window is enlarged by -COUNT lines or
+ columns.
+
+ If WINDOW is non-`nil', it specifies a window to change instead of
+ the selected window.
+
+ - Command: shrink-window-horizontally columns
+ This function makes the selected window COLUMNS narrower. It
+ could be defined as follows:
+
+ (defun shrink-window-horizontally (columns)
+ (shrink-window columns t))
+
+ - Command: shrink-window-pixels count &optional side window
+ This function makes the selected window COUNT pixels smaller.
+ When called from Lisp, optional second argument SIDE non-`nil'
+ means to shrink sideways COUNT pixels, and optional third argument
+ WINDOW specifies the window to change instead of the selected
+ window.
+
+ The following two variables constrain the window-size-changing
+functions to a minimum height and width.
+
+ - User Option: window-min-height
+ The value of this variable determines how short a window may become
+ before it is automatically deleted. Making a window smaller than
+ `window-min-height' automatically deletes it, and no window may be
+ created shorter than this. The absolute minimum height is two
+ (allowing one line for the mode line, and one line for the buffer
+ display). Actions that change window sizes reset this variable to
+ two if it is less than two. The default value is 4.
+
+ - User Option: window-min-width
+ The value of this variable determines how narrow a window may
+ become before it automatically deleted. Making a window smaller
+ than `window-min-width' automatically deletes it, and no window
+ may be created narrower than this. The absolute minimum width is
+ one; any value below that is ignored. The default value is 10.
+
+ - Variable: window-size-change-functions
+ This variable holds a list of functions to be called if the size
+ of any window changes for any reason. The functions are called
+ just once per redisplay, and just once for each frame on which
+ size changes have occurred.
+
+ Each function receives the frame as its sole argument. There is no
+ direct way to find out which windows changed size, or precisely
+ how; however, if your size-change function keeps track, after each
+ change, of the windows that interest you, you can figure out what
+ has changed by comparing the old size data with the new.
+
+ Creating or deleting windows counts as a size change, and therefore
+ causes these functions to be called. Changing the frame size also
+ counts, because it changes the sizes of the existing windows.
+
+ It is not a good idea to use `save-window-excursion' in these
+ functions, because that always counts as a size change, and it
+ would cause these functions to be called over and over. In most
+ cases, `save-selected-window' is what you need here.
\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 device
- This function returns a list of all frames on DEVICE.
-
- - Function: frame-device frame
- This function returns the device that FRAME is on.
+File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows
+
+Window Configurations
+=====================
+
+ A "window configuration" records the entire layout of a frame--all
+windows, their sizes, which buffers they contain, what part of each
+buffer is displayed, and the values of point and the mark. You can
+bring back an entire previous layout by restoring a window
+configuration previously saved.
+
+ If you want to record all frames instead of just one, use a frame
+configuration instead of a window configuration. *Note Frame
+Configurations::.
+
+ - Function: current-window-configuration &optional frame
+ This function returns a new object representing the current current
+ window configuration of FRAME, namely the number of windows, their
+ sizes and current buffers, which window is the selected window,
+ and for each window the displayed buffer, the display-start
+ position, and the positions of point and the mark. An exception
+ is made for point in the current buffer, whose value is not saved.
+
+ FRAME defaults to the selected frame.
+
+ - Function: set-window-configuration configuration
+ This function restores the configuration of XEmacs's windows and
+ buffers to the state specified by CONFIGURATION. The argument
+ CONFIGURATION must be a value that was previously returned by
+ `current-window-configuration'.
+
+ This function always counts as a window size change and triggers
+ execution of the `window-size-change-functions'. (It doesn't know
+ how to tell whether the new configuration actually differs from
+ the old one.)
+
+ Here is a way of using this function to get the same effect as
+ `save-window-excursion':
+
+ (let ((config (current-window-configuration)))
+ (unwind-protect
+ (progn (split-window-vertically nil)
+ ...)
+ (set-window-configuration config)))
+
+ - Special Form: save-window-excursion forms...
+ This special form records the window configuration, executes FORMS
+ in sequence, then restores the earlier window configuration. The
+ window configuration includes the value of point and the portion
+ of the buffer that is visible. It also includes the choice of
+ selected window. However, it does not include the value of point
+ in the current buffer; use `save-excursion' if you wish to
+ preserve that.
+
+ Don't use this construct when `save-selected-window' is all you
+ need.
+
+ Exit from `save-window-excursion' always triggers execution of the
+ `window-size-change-functions'. (It doesn't know how to tell
+ whether the restored configuration actually differs from the one in
+ effect at the end of the FORMS.)
+
+ The return value is the value of the final form in FORMS. For
+ example:
+
+ (split-window)
+ => #<window 25 on control.texi>
+ (setq w (selected-window))
+ => #<window 19 on control.texi>
+ (save-window-excursion
+ (delete-other-windows w)
+ (switch-to-buffer "foo")
+ 'do-something)
+ => do-something
+ ;; The frame is now split again.
+
+ - Function: window-configuration-p object
+ This function returns `t' if OBJECT is a window configuration.
+
+ Primitives to look inside of window configurations would make sense,
+but none are implemented. It is not clear they are useful enough to be
+worth implementing.
\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 device
- This function returns the type of DEVICE. This is a symbol whose
- name is one of the device types mentioned above.
-
- - Function: device-or-frame-type device-or-frame
- This function returns the type of DEVICE-OR-FRAME.
-
- - Function: device-class device
- This function returns the class (color behavior) of DEVICE. This
- is a symbol whose name is one of the device classes mentioned
- above.
-
- - Function: valid-device-type-p device-type
- This function returns whether DEVICE-TYPE (which should be a
- symbol) species a valid device type.
+File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top
+
+Frames
+******
+
+ A FRAME is a rectangle on the screen that contains one or more
+XEmacs windows (*note Windows::). A frame initially contains a single
+main window (plus perhaps an echo area), which you can subdivide
+vertically or horizontally into smaller windows. Each window is
+associated with a modeline (*note Modeline Format::), and optionally two
+scrollbars (*note Scrollbars::). By default the vertical scrollbar is
+on, the horizontal scrollbar is off.
+
+ The frame may also contain menubars (*note Menubar::), toolbars
+(*note Toolbar Intro::), and gutters (*note Gutter Intro::). By default
+there is one of each at the top of the frame, with menubar topmost,
+toolbar next, and gutter lowest, immediately above the windows.
+(Warning: the gutter is a new, experimental, and unstable feature of
+XEmacs version 21.2.)
+
+ When XEmacs runs on a text-only terminal, it starts with one "TTY
+frame". If you create additional ones, XEmacs displays one and only
+one at any given time--on the terminal screen, of course.
+
+ When XEmacs communicates directly with an X server, it does not have
+a TTY frame; instead, it starts with a single "X window frame". It can
+display multiple X window frames at the same time, each in its own X
+window.
+
+ - Function: framep object
+ This predicate returns `t' if OBJECT is a frame, and `nil'
+ otherwise.
- - Function: valid-device-class-p device-class
- This function returns whether DEVICE-CLASS (which should be a
- symbol) species a valid device class.
+* Menu:
- - Variable: terminal-device
- This variable holds the initial terminal device object, which
- represents XEmacs's stdout.
+* Creating Frames:: Creating additional frames.
+* Frame Properties:: Controlling frame size, position, font, etc.
+* Frame Titles:: Automatic updating of frame titles.
+* Deleting Frames:: Frames last until explicitly deleted.
+* Finding All Frames:: How to examine all existing frames.
+* Frames and Windows:: A frame contains windows;
+ display of text always works through windows.
+* Minibuffers and Frames:: How a frame finds the minibuffer to use.
+* Input Focus:: Specifying the selected frame.
+* Visibility of Frames:: Frames may be visible or invisible, or icons.
+* Raising and Lowering:: Raising a frame makes it hide other X windows;
+ lowering it makes the others hide them.
+* Frame Configurations:: Saving the state of all frames.
+* Frame Hooks:: Hooks for customizing frame behavior.
+
+ *Note Display::, for related information.
\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 &optional type device-data
- 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
- 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.
+File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames
+
+Creating Frames
+===============
+
+ To create a new frame, call the function `make-frame'.
+
+ - Command: make-frame &optional props device
+ This function creates a new frame on DEVICE, if DEVICE permits
+ creation of frames. (An X server does; an ordinary terminal does
+ not (yet).) DEVICE defaults to the selected device if omitted.
+ *Note Consoles and Devices::.
+
+ The argument PROPS is a property list (a list of alternating
+ keyword-value specifications) of properties for the new frame. (An
+ alist is accepted for backward compatibility but should not be
+ passed in.) Any properties not mentioned in PROPS default
+ according to the value of the variable `default-frame-plist'. For
+ X devices, properties not specified in `default-frame-plist'
+ default in turn from `default-x-frame-plist' and, if not specified
+ there, from the X resources. For TTY devices,
+ `default-tty-frame-plist' is consulted as well as
+ `default-frame-plist'.
+
+ The set of possible properties depends in principle on what kind of
+ window system XEmacs uses to display its frames. *Note X Frame
+ Properties::, for documentation of individual properties you can
+ specify when creating an X window frame.
\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
+File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
-The Selected Console and Device
-===============================
+Frame Properties
+================
- - 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.
+ A frame has many properties that control its appearance and behavior.
+Just what properties a frame has depends on which display mechanism it
+uses.
- - Function: selected-console
- This function returns the console which is currently active.
+ Frame properties exist for the sake of window systems. A terminal
+frame has few properties, mostly for compatibility's sake; only the
+height, width and `buffer-predicate' properties really do something.
- - Function: select-device device
- This function selects the device DEVICE.
+* Menu:
- - 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.
+* Property Access:: How to change a frame's properties.
+* Initial Properties:: Specifying frame properties when you make a frame.
+* X Frame Properties:: List of frame properties.
+* Size and Position:: Changing the size and position of a frame.
+* Frame Name:: The name of a frame (as opposed to its title).
\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.
+File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties
- 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.
+Access to Frame Properties
+--------------------------
- - Function: device-baud-rate &optional device
- This function returns the output baud rate of DEVICE.
+ These functions let you read and change the properties of a frame.
- - Function: set-device-baud-rate device rate
- This function sets the output baud rate of DEVICE to RATE.
+ - Function: frame-properties &optional frame
+ This function returns a plist listing all the properties of FRAME
+ and their values.
-\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.
+ - Function: frame-property frame property &optional default
+ This function returns FRAME's value for the property PROPERTY, or
+ DEFAULT if there is no such property.
- 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:
+ - Function: set-frame-properties frame plist
+ This function alters the properties of frame FRAME based on the
+ elements of property list PLIST. If you don't mention a property
+ in PLIST, its value doesn't change.
-* 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.
+ - Function: set-frame-property frame property value
+ This function sets the property PROPERTY of frame FRAME to the
+ value VALUE.
\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.
-
- - 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.
+File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties
+
+Initial Frame Properties
+------------------------
+
+ You can specify the properties for the initial startup frame by
+setting `initial-frame-plist' in your `.emacs' file.
+
+ - Variable: initial-frame-plist
+ This variable's value is a plist of alternating property-value
+ pairs used when creating the initial X window frame.
+
+ XEmacs creates the initial frame before it reads your `~/.emacs'
+ file. After reading that file, XEmacs checks
+ `initial-frame-plist', and applies the property settings in the
+ altered value to the already created initial frame.
+
+ If these settings affect the frame geometry and appearance, you'll
+ see the frame appear with the wrong ones and then change to the
+ specified ones. If that bothers you, you can specify the same
+ geometry and appearance with X resources; those do take affect
+ before the frame is created. *Note X Resources: (xemacs)Resources
+ X.
+
+ X resource settings typically apply to all frames. If you want to
+ specify some X resources solely for the sake of the initial frame,
+ and you don't want them to apply to subsequent frames, here's how
+ to achieve this: specify properties in `default-frame-plist' to
+ override the X resources for subsequent frames; then, to prevent
+ these from affecting the initial frame, specify the same
+ properties in `initial-frame-plist' with values that match the X
+ resources.
+
+ If these properties specify a separate minibuffer-only frame via a
+`minibuffer' property of `nil', and you have not yet created one,
+XEmacs creates one for you.
+
+ - Variable: minibuffer-frame-plist
+ This variable's value is a plist of properties used when creating
+ an initial minibuffer-only frame--if such a frame is needed,
+ according to the properties for the main initial frame.
+
+ - Variable: default-frame-plist
+ This is a plist specifying default values of frame properties for
+ subsequent XEmacs frames (not the initial ones).
+
+ See also `special-display-frame-plist', in *Note Choosing Window::.
+
+ If you use options that specify window appearance when you invoke
+XEmacs, they take effect by adding elements to `default-frame-plist'.
+One exception is `-geometry', which adds the specified position to
+`initial-frame-plist' instead. *Note Command Arguments:
+(xemacs)Command Arguments.
\1f
-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:
-
-* Character Motion:: Moving in terms of characters.
-* Word Motion:: Moving in terms of words.
-* Buffer End Motion:: Moving to the beginning or end of the buffer.
-* Text Lines:: Moving in terms of lines of text.
-* Screen Lines:: Moving in terms of lines as displayed.
-* List Motion:: Moving by parsing lists and sexps.
-* Skipping Characters:: Skipping characters belonging to a certain set.
+File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties
+
+X Window Frame Properties
+-------------------------
+
+ Just what properties a frame has depends on what display mechanism it
+uses. Here is a table of the properties of an X window frame; of these,
+`name', `height', `width', and `buffer-predicate' provide meaningful
+information in non-X frames.
+
+`name'
+ The name of the frame. Most window managers display the frame's
+ name in the frame's border, at the top of the frame. If you don't
+ specify a name, and you have more than one frame, XEmacs sets the
+ frame name based on the buffer displayed in the frame's selected
+ window.
+
+ If you specify the frame name explicitly when you create the
+ frame, the name is also used (instead of the name of the XEmacs
+ executable) when looking up X resources for the frame.
+
+`display'
+ The display on which to open this frame. It should be a string of
+ the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
+ variable.
+
+`left'
+ The screen position of the left edge, in pixels, with respect to
+ the left edge of the screen. The value may be a positive number
+ POS, or a list of the form `(+ POS)' which permits specifying a
+ negative POS value.
+
+ A negative number -POS, or a list of the form `(- POS)', actually
+ specifies the position of the right edge of the window with
+ respect to the right edge of the screen. A positive value of POS
+ counts toward the left. If the property is a negative integer
+ -POS then POS is positive!
+
+`top'
+ The screen position of the top edge, in pixels, with respect to the
+ top edge of the screen. The value may be a positive number POS,
+ or a list of the form `(+ POS)' which permits specifying a
+ negative POS value.
+
+ A negative number -POS, or a list of the form `(- POS)', actually
+ specifies the position of the bottom edge of the window with
+ respect to the bottom edge of the screen. A positive value of POS
+ counts toward the top. If the property is a negative integer -POS
+ then POS is positive!
+
+`icon-left'
+ The screen position of the left edge _of the frame's icon_, in
+ pixels, counting from the left edge of the screen. This takes
+ effect if and when the frame is iconified.
+
+`icon-top'
+ The screen position of the top edge _of the frame's icon_, in
+ pixels, counting from the top edge of the screen. This takes
+ effect if and when the frame is iconified.
+
+`user-position'
+ Non-`nil' if the screen position of the frame was explicitly
+ requested by the user (for example, with the `-geometry' option).
+ Nothing automatically makes this property non-`nil'; it is up to
+ Lisp programs that call `make-frame' to specify this property as
+ well as specifying the `left' and `top' properties.
+
+`height'
+ The height of the frame contents, in characters. (To get the
+ height in pixels, call `frame-pixel-height'; see *Note Size and
+ Position::.)
+
+`width'
+ The width of the frame contents, in characters. (To get the
+ height in pixels, call `frame-pixel-width'; see *Note Size and
+ Position::.)
+
+`window-id'
+ The number of the X window for the frame.
+
+`minibuffer'
+ Whether this frame has its own minibuffer. The value `t' means
+ yes, `nil' means no, `only' means this frame is just a minibuffer.
+ If the value is a minibuffer window (in some other frame), the
+ new frame uses that minibuffer. (Minibuffer-only and
+ minibuffer-less frames are not yet implemented in XEmacs.)
+
+`buffer-predicate'
+ The buffer-predicate function for this frame. The function
+ `other-buffer' uses this predicate (from the selected frame) to
+ decide which buffers it should consider, if the predicate is not
+ `nil'. It calls the predicate with one arg, a buffer, once for
+ each buffer; if the predicate returns a non-`nil' value, it
+ considers that buffer.
+
+`scroll-bar-width'
+ The width of the vertical scroll bar, in pixels.
+
+`cursor-color'
+ The color for the cursor that shows point.
+
+`border-color'
+ The color for the border of the frame.
+
+`border-width'
+ The width in pixels of the window border.
+
+`internal-border-width'
+ The distance in pixels between text and border.
+
+`unsplittable'
+ If non-`nil', this frame's window is never split automatically.
+
+`inter-line-space'
+ The space in pixels between adjacent lines of text. (Not currently
+ implemented.)
+
+`modeline'
+ Whether the frame has a modeline.
\1f
-File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
-
-Motion by Characters
---------------------
-
- These functions move point based on a count of characters.
-`goto-char' is the fundamental primitive; the other functions use that.
-
- - Command: goto-char position &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.
+File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties
+
+Frame Size And Position
+-----------------------
+
+ You can read or change the size and position of a frame using the
+frame properties `left', `top', `height', and `width'. Whatever
+geometry properties you don't specify are chosen by the window manager
+in its usual fashion.
+
+ Here are some special features for working with sizes and positions:
+
+ - Function: set-frame-position frame left top
+ This function sets the position of the top left corner of FRAME to
+ LEFT and TOP. These arguments are measured in pixels, and count
+ from the top left corner of the screen. Negative property values
+ count up or rightward from the top left corner of the screen.
+
+ - Function: frame-height &optional frame
+ - Function: frame-width &optional frame
+ These functions return the height and width of FRAME, measured in
+ lines and columns. If you don't supply FRAME, they use the
+ selected frame.
+
+ - Function: frame-pixel-height &optional frame
+ - Function: frame-pixel-width &optional frame
+ These functions return the height and width of FRAME, measured in
+ pixels. If you don't supply FRAME, they use the selected frame.
+
+ - Function: set-frame-size frame cols rows &optional pretend
+ This function sets the size of FRAME, measured in characters; COLS
+ and ROWS specify the new width and height. (If PRETEND is
+ non-`nil', it means that redisplay should act as if the frame's
+ size is COLS by ROWS, but the actual size of the frame should not
+ be changed. You should not normally use this option.)
+
+ You can also use the functions `set-frame-height' and
+`set-frame-width' to set the height and width individually. The frame
+is the first argument and the size (in rows or columns) is the second.
+(There is an optional third argument, PRETEND, which has the same
+purpose as the corresponding argument in `set-frame-size'.)
\1f
-File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
-
-Motion by Words
----------------
-
- These functions for parsing words use the syntax table to decide
-whether a given character is part of a word. *Note Syntax Tables::.
-
- - Command: forward-word count &optional 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'. BUFFER defaults to the current buffer if
- omitted.
+File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties
- In an interactive call, COUNT is set to the numeric prefix
- argument.
+The Name of a Frame (As Opposed to Its Title)
+---------------------------------------------
- - Command: backward-word count &optional 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.
+ Under X, every frame has a name, which is not the same as the title
+of the frame. A frame's name is used to look up its resources and does
+not normally change over the lifetime of a frame. It is perfectly
+allowable, and quite common, for multiple frames to have the same name.
- In an interactive call, COUNT is set to the numeric prefix
- argument.
+ - Function: frame-name &optional frame
+ This function returns the name of FRAME, which defaults to the
+ selected frame if not specified. The name of a frame can also be
+ obtained from the frame's properties. *Note Frame Properties::.
- This function is rarely used in programs, as it is more efficient
- to call `forward-word' with a negative argument.
-
- - Variable: words-include-escapes
- This variable affects the behavior of `forward-word' and everything
- that uses it. If it is non-`nil', then characters in the "escape"
- and "character quote" syntax classes count as part of words.
- Otherwise, they do not.
+ - Variable: default-frame-name
+ This variable holds the default name to assign to newly-created
+ frames. This can be overridden by arguments to `make-frame'. This
+ must be a string.
\1f
-File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
-
-Motion to an End of the Buffer
-------------------------------
+File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
- To move point to the beginning of the buffer, write:
+Frame Titles
+============
- (goto-char (point-min))
+ Every frame has a title; most window managers display the frame
+title at the top of the frame. You can specify an explicit title with
+the `name' frame property. But normally you don't specify this
+explicitly, and XEmacs computes the title automatically.
-Likewise, to move to the end of the buffer, use:
+ XEmacs computes the frame title based on a template stored in the
+variable `frame-title-format'.
- (goto-char (point-max))
+ - Variable: frame-title-format
+ This variable specifies how to compute a title for a frame when
+ you have not explicitly specified one.
- 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.
+ The variable's value is actually a modeline construct, just like
+ `modeline-format'. *Note Modeline Data::.
- - Command: beginning-of-buffer &optional n
- This function moves point to the beginning of the buffer (or the
- limits of the accessible portion, when narrowing is in effect),
- setting the mark at the previous position. If N is non-`nil',
- then it puts point N tenths of the way from the beginning of the
- buffer.
+ - Variable: frame-icon-title-format
+ This variable specifies how to compute the title for an iconified
+ frame, when you have not explicitly specified the frame title.
+ This title appears in the icon itself.
- In an interactive call, N is the numeric prefix argument, if
- provided; otherwise N defaults to `nil'.
+ - Function: x-set-frame-icon-pixmap frame pixmap &optional mask
+ This function sets the icon of the given frame to the given image
+ instance, which should be an image instance object (as returned by
+ `make-image-instance'), a glyph object (as returned by
+ `make-glyph'), or `nil'. If a glyph object is given, the glyph
+ will be instantiated on the frame to produce an image instance
+ object.
- Don't use this function in Lisp programs!
+ If the given image instance has a mask, that will be used as the
+ icon mask; however, not all window managers support this.
- - Command: end-of-buffer &optional n
- This function moves point to the end of the buffer (or the limits
- of the accessible portion, when narrowing is in effect), setting
- the mark at the previous position. If N is non-`nil', then it puts
- point N tenths of the way from the end of the buffer.
+ The window manager is also not required to support color pixmaps,
+ only bitmaps (one plane deep).
- In an interactive call, N is the numeric prefix argument, if
- provided; otherwise N defaults to `nil'.
-
- Don't use this function in Lisp programs!
+ If the image instance does not have a mask, then the optional
+ third argument may be the image instance to use as the mask (it
+ must be one plane deep). *Note Glyphs::.
\1f
-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
- This function returns the number of lines between the positions
- START and END in the current buffer. If START and END are equal,
- then it returns 0. Otherwise it returns at least 1, even if START
- and END are on the same line. This is because the text between
- them, considered in isolation, must contain at least one line
- unless it is empty.
-
- Here is an example of using `count-lines':
-
- (defun current-line ()
- "Return the vertical position of point..."
- (+ (count-lines (window-start) (point))
- (if (= (current-column) 0) 1 0)
- -1))
-
- Also see the functions `bolp' and `eolp' in *Note Near Point::.
-These functions do not move point, but test whether it is already at the
-beginning or end of a line.
+File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
-\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.
+Deleting Frames
+===============
-\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:
-(emacs)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 arg
- This function moves backward 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 forward across that many groups of parentheses.
-
- - Command: up-list arg
- This function moves forward out of ARG levels of parentheses. A
- negative argument means move backward but still to a less deep
- spot.
-
- - Command: down-list arg
- This function moves forward into ARG levels of parentheses. A
- negative argument means move backward but still go deeper in
- parentheses (-ARG levels).
-
- - Command: forward-sexp &optional arg
- This function moves forward across ARG balanced expressions.
- Balanced expressions include both those delimited by parentheses
- and other kinds, such as words and string constants. ARG defaults
- to 1 if omitted. If ARG is negative, move backward across that
- many balanced expressions. For example,
-
- ---------- Buffer: foo ----------
- (concat-!- "foo " (car x) y z)
- ---------- Buffer: foo ----------
-
- (forward-sexp 3)
- => nil
-
- ---------- Buffer: foo ----------
- (concat "foo " (car x) y-!- z)
- ---------- Buffer: foo ----------
+ Frames remain potentially visible until you explicitly "delete"
+them. A deleted frame cannot appear on the screen, but continues to
+exist as a Lisp object until there are no references to it.
- - Command: backward-sexp &optional arg
- This function moves backward across ARG balanced expressions. ARG
- defaults to 1 if omitted. If ARG is negative, move forward across
- that many balanced expressions.
-
- - Command: beginning-of-defun &optional arg
- This function moves back to the ARGth beginning of a defun. If
- ARG is negative, this actually moves forward, but it still moves
- to the beginning of a defun, not to the end of one. ARG defaults
- to 1 if omitted.
-
- - Command: end-of-defun &optional arg
- This function moves forward to the ARGth end of a defun. If ARG
- is negative, this actually moves backward, but it still moves to
- the end of a defun, not to the beginning of one. ARG 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.
+ - Command: delete-frame &optional frame force
+ This function deletes the frame FRAME. By default, FRAME is the
+ selected frame.
-\1f
-File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
-
-Skipping Characters
--------------------
-
- The following two functions move point over a specified set of
-characters. For example, they are often used to skip whitespace. For
-related functions, see *Note Motion and Syntax::.
-
- - Function: skip-chars-forward character-set &optional limit buffer
- This function moves point in BUFFER forward, skipping over a given
- set of characters. It examines the character following point,
- then advances point if the character matches CHARACTER-SET. This
- continues until it reaches a character that does not match. The
- function returns `nil'. BUFFER defaults to the current buffer if
- omitted.
-
- The argument CHARACTER-SET is like the inside of a `[...]' in a
- regular expression except that `]' is never special and `\' quotes
- `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
- stopping before the first non-letter, and `"^a-zA-Z'" skips
- non-letters stopping before the first letter. *Note Regular
- Expressions::.
-
- If LIMIT is supplied (it must be a number or a marker), it
- specifies the maximum position in the buffer that point can be
- skipped to. Point will stop at or before LIMIT.
-
- In the following example, point is initially located directly
- before the `T'. After the form is evaluated, point is located at
- the end of that line (between the `t' of `hat' and the newline).
- The function skips all letters and spaces, but not newlines.
-
- ---------- Buffer: foo ----------
- I read "-!-The cat in the hat
- comes back" twice.
- ---------- Buffer: foo ----------
-
- (skip-chars-forward "a-zA-Z ")
- => nil
-
- ---------- Buffer: foo ----------
- I read "The cat in the hat-!-
- comes back" twice.
- ---------- Buffer: foo ----------
+ A frame may not be deleted if its minibuffer is used by other
+ frames. Normally, you cannot delete the last non-minibuffer-only
+ frame (you must use `save-buffers-kill-emacs' or `kill-emacs').
+ However, if optional second argument FORCE is non-`nil', you can
+ delete the last frame. (This will automatically call
+ `save-buffers-kill-emacs'.)
- - Function: skip-chars-backward character-set &optional limit buffer
- This function moves point backward, skipping characters that match
- CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
- except for the direction of motion.
+ - Function: frame-live-p frame
+ The function `frame-live-p' returns non-`nil' if the frame FRAME
+ has not been deleted.
projects / chise / xemacs-chise.git / blobdiff