+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows
-
-Windows and Point
-=================
-
- Each window has its own value of point, independent of the value of
-point in other windows displaying the same buffer. This makes it useful
-to have multiple windows showing one buffer.
-
- * The window point is established when a window is first created; it
- is initialized from the buffer's point, or from the window point
- of another window opened on the buffer if such a window exists.
-
- * Selecting a window sets the value of point in its buffer to the
- window's value of point. Conversely, deselecting a window sets
- the window's value of point from that of the buffer. Thus, when
- you switch between windows that display a given buffer, the point
- value for the selected window is in effect in the buffer, while
- the point values for the other windows are stored in those windows.
-
- * As long as the selected window displays the current buffer, the
- window's point and the buffer's point always move together; they
- remain equal.
-
- * *Note Positions::, for more details on buffer positions.
-
- As far as the user is concerned, point is where the cursor is, and
-when the user switches to another buffer, the cursor jumps to the
-position of point in that buffer.
-
- - Function: window-point WINDOW
- This function returns the current position of point in WINDOW.
- For a nonselected window, this is the value point would have (in
- that window's buffer) if that window were selected.
-
- When WINDOW is the selected window and its buffer is also the
- current buffer, the value returned is the same as point in that
- buffer.
-
- Strictly speaking, it would be more correct to return the
- "top-level" value of point, outside of any `save-excursion' forms.
- But that value is hard to find.
-
- - Function: set-window-point WINDOW POSITION
- This function positions point in WINDOW at position POSITION in
- WINDOW's buffer.
-
-\1f
-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
- 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 moving point 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.
-
- - 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 ----------
-
- 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.
-
- - 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:
-
- (or (pos-visible-in-window-p
- (point) (selected-window))
- (recenter 0))
-
- 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: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows
-
-Vertical Scrolling
-==================
-
- 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 COUNT
- This function scrolls the text in the selected window upward COUNT
- lines. If COUNT is negative, scrolling is actually downward.
-
- If COUNT 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 COUNT
- This function scrolls the text in the selected window downward
- COUNT lines. If COUNT is negative, scrolling is actually upward.
-
- If COUNT 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 COUNT
- This function scrolls the text in another window upward COUNT
- lines. Negative values of COUNT, 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 COUNT
- This function scrolls the selected window to put the text where
- point is located at a specified vertical position within the
- window.
-
- If COUNT is a nonnegative number, it puts the line containing
- point COUNT lines down from the top of the window. If COUNT 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 COUNT is a non-`nil' list, then it stands for the line in the
- middle of the window.
-
- If COUNT 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, COUNT is the raw prefix
- argument. Thus, typing `C-u' as the prefix sets the COUNT to a
- non-`nil' list, while typing `C-u 4' sets COUNT 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: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows
-
-Horizontal Scrolling
-====================
-
- 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 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 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: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows
-
-The Size of a Window
-====================
-
- 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: 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 the 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 or toolbars 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 TOP and BOTTOM 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: 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 SIZE &optional HORIZONTAL WINDOW
- This function makes the selected window SIZE 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
- SIZE 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 SIZE is negative, this function shrinks the window by -SIZE
- 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 SIZE &optional HORIZONTAL WINDOW
- This function is like `enlarge-window' but negates the argument
- SIZE, 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 SIZE is negative, the window is enlarged by -SIZE 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: 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
- This function returns a new object representing XEmacs's current
- window configuration, 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.
-
- - 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: 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. A frame initially contains a single main window (plus
-perhaps a minibuffer window), which you can subdivide vertically or
-horizontally into smaller windows.
-
- 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.
-
-* Menu:
-
-* 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: Creating Frames, Next: Frame Properties, Up: Frames
-
-Creating Frames
-===============
-
- To create a new frame, call the function `make-frame'.
-
- - Function: 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: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
-
-Frame Properties
-================
-
- A frame has many properties that control its appearance and behavior.
-Just what properties a frame has depends on which display mechanism it
-uses.
-
- 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.
-
-* Menu:
-
-* 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: Property Access, Next: Initial Properties, Up: Frame Properties
-
-Access to Frame Properties
---------------------------
-
- These functions let you read and change the properties of a frame.
-
- - Function: frame-properties &optional FRAME
- This function returns a plist listing all the properties of FRAME
- and their values.
-
- - Function: frame-property FRAME PROPERTY &optional DEFAULT
- This function returns FRAME's value for the property PROPERTY.
-
- - 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.
-
- - Function: set-frame-property FRAME PROP VAL
- This function sets the property PROP of frame FRAME to the value
- VAL.
-
-\1f
-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: 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: 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: Frame Name, Prev: Size and Position, Up: Frame Properties
-
-The Name of a Frame (As Opposed to Its Title)
----------------------------------------------
-
- 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.
-
- - 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::.
-
- - 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: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
-
-Frame Titles
-============
-
- 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.
-
- XEmacs computes the frame title based on a template stored in the
-variable `frame-title-format'.
-
- - Variable: frame-title-format
- This variable specifies how to compute a title for a frame when
- you have not explicitly specified one.
-
- The variable's value is actually a modeline construct, just like
- `modeline-format'. *Note Modeline Data::.
-
- - 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.
-
- - 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.
-
- If the given image instance has a mask, that will be used as the
- icon mask; however, not all window managers support this.
-
- The window manager is also not required to support color pixmaps,
- only bitmaps (one plane deep).
-
- 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: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
-
-Deleting Frames
-===============
-
- 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: delete-frame &optional FRAME
- This function deletes the frame FRAME. By default, FRAME is the
- selected frame.
-
- - 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