+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 (*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.
+
+* 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.
+
+\1f