+File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
+
+Finding All Frames
+==================
+
+ - Function: frame-list
+ The function `frame-list' returns a list of all the frames that
+ have not been deleted. It is analogous to `buffer-list' for
+ buffers. The list that you get is newly created, so modifying the
+ list doesn't have any effect on the internals of XEmacs.
+
+ - Function: device-frame-list &optional device
+ This function returns a list of all frames on DEVICE. If DEVICE
+ is `nil', the selected device will be used.
+
+ - Function: visible-frame-list &optional device
+ This function returns a list of just the currently visible frames.
+ If DEVICE is specified only frames on that device will be returned.
+ *Note Visibility of Frames::. (TTY frames always count as
+ "visible", even though only the selected one is actually
+ displayed.)
+
+ - Function: next-frame &optional frame which-frames which-devices
+ The function `next-frame' lets you cycle conveniently through all
+ the frames from an arbitrary starting point. It returns the "next"
+ frame after FRAME in the cycle. If FRAME defaults to the selected
+ frame.
+
+ The second argument, WHICH-FRAMES, says which frames to consider:
+
+ `visible'
+ Consider only frames that are visible.
+
+ `iconic'
+ Consider only frames that are iconic.
+
+ `invisible'
+ Consider only frames that are invisible (this is different
+ from iconic).
+
+ `visible-iconic'
+ Consider frames that are visible or iconic.
+
+ `invisible-iconic'
+ Consider frames that are invisible or iconic.
+
+ `nomini'
+ Consider all frames except minibuffer-only ones.
+
+ `visible-nomini'
+ Like `visible' but omits minibuffer-only frames.
+
+ `iconic-nomini'
+ Like `iconic' but omits minibuffer-only frames.
+
+ `invisible-nomini'
+ Like `invisible' but omits minibuffer-only frames.
+
+ `visible-iconic-nomini'
+ Like `visible-iconic' but omits minibuffer-only frames.
+
+ `invisible-iconic-nomini'
+ Like `invisible-iconic' but omits minibuffer-only frames.
+
+ `nil'
+ Identical to `nomini'.
+
+ WINDOW
+ Consider only the window WINDOW's frame and any frame now
+ using WINDOW as the minibuffer.
+
+ any other value
+ Consider all frames.
+
+ The optional argument WHICH-DEVICES further clarifies on which
+ devices to search for frames as specified by WHICH-FRAMES.
+
+ `nil'
+ Consider all devices on the selected console.
+
+ DEVICE
+ Consider only the one device DEVICE.
+
+ CONSOLE
+ Consider all devices on CONSOLE.
+
+ DEVICE-TYPE
+ Consider all devices with device type DEVICE-TYPE.
+
+ `window-system'
+ Consider all devices on window system consoles.
+
+ anything else
+ Consider all devices without restriction.
+
+ - Function: previous-frame &optional frame which-frames which-devices
+ Like `next-frame', but cycles through all frames in the opposite
+ direction.
+
+ See also `next-window' and `previous-window', in *Note Cyclic Window
+Ordering::.
+
+\1f
+File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
+
+Frames and Windows
+==================
+
+ 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-highest-window &optional frame position
+ This function returns the topmost, leftmost window of frame FRAME
+ at position POSITION.
+
+ If omitted, FRAME defaults to the currently selected frame.
+
+ POSITION is used to distinguish between multiple windows that abut
+ the top of the frame: 0 means the leftmost window abutting the top
+ of the frame, 1 the next-leftmost, etc. POSITION can also be less
+ than zero: -1 means the rightmost window abutting the top of the
+ frame, -2 the next-rightmost, etc. If omitted, POSITION defaults
+ to 0, i.e. the leftmost highest window. If there is no window at
+ the given POSITION, `nil' is returned.
+
+ The following three functions work similarly.
+
+ - Function: frame-lowest-window &optional frame position
+ This function returns the lowest window on FRAME which is at
+ POSITION.
+
+ - Function: frame-leftmost-window &optional frame position
+ This function returns the leftmost window on FRAME which is at
+ POSITION.
+
+ - Function: frame-rightmost-window &optional frame position
+ This function returns the rightmost window on FRAME which is at
+ POSITION.
+
+ 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'.
+
+ - Special Form: save-selected-frame forms...
+ This special form records the selected frame, executes FORMS in
+ sequence, then restores the earlier selected frame. The value
+ returned is the value of the last form.
+
+ - Special Form: with-selected-frame frame forms...
+ This special form records the selected frame, then selects FRAME
+ and executes FORMS in sequence. After the last form is finished,
+ the earlier selected frame is restored. The value returned is the
+ value of the last form.
+
+\1f
+File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
+
+Visibility of Frames
+====================
+
+ An frame on a window system may be "visible", "invisible", or
+"iconified". If it is visible, you can see its contents. If it is
+iconified, the frame's contents do not appear on the screen, but an icon
+does. If the frame is invisible, it doesn't show on the screen, not
+even as an icon.
+
+ Visibility is meaningless for TTY frames, since only the selected
+one is actually displayed in any case.
+
+ - Function: make-frame-visible &optional frame
+ This function makes frame FRAME visible. If you omit FRAME, it
+ makes the selected frame visible.
+
+ - Function: make-frame-invisible &optional frame force
+ This function makes frame FRAME invisible.
+
+ - Command: iconify-frame &optional frame
+ This function iconifies frame FRAME.
+
+ - Function: Command deiconify-frame &optional frame
+ This function de-iconifies frame FRAME. Under a window system,
+ this is equivalent to `make-frame-visible'.
+
+ - Function: frame-visible-p &optional frame
+ This returns whether FRAME is currently "visible" (actually in use
+ for display). A frame that is not visible is not updated, and, if
+ it works through a window system, may not show at all.
+
+ - Function: frame-iconified-p &optional frame
+ This returns whether FRAME is iconified. Not all window managers
+ use icons; some merely unmap the window, so this function is not
+ the inverse of `frame-visible-p'. It is possible for a frame to
+ not be visible and not be iconified either. However, if the frame
+ is iconified, it will not be visible. (Under FSF Emacs, the
+ functionality of this function is obtained through
+ `frame-visible-p'.)
+
+ - Function: frame-totally-visible-p &optional frame
+ This returns whether FRAME is not obscured by any other X windows.
+ On TTY frames, this is the same as `frame-visible-p'.
+
+\1f
+File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
+
+Raising and Lowering Frames
+===========================
+
+ The X Window System uses a desktop metaphor. Part of this metaphor
+is the idea that windows are stacked in a notional third dimension
+perpendicular to the screen surface, and thus ordered from "highest" to
+"lowest". Where two windows overlap, the one higher up covers the one
+underneath. Even a window at the bottom of the stack can be seen if no
+other window overlaps it.
+
+ A window's place in this ordering is not fixed; in fact, users tend
+to change the order frequently. "Raising" a window means moving it
+"up", to the top of the stack. "Lowering" a window means moving it to
+the bottom of the stack. This motion is in the notional third
+dimension only, and does not change the position of the window on the
+screen.
+
+ You can raise and lower XEmacs's X windows with these functions:
+
+ - Command: raise-frame &optional frame
+ This function raises frame FRAME.
+
+ - Command: lower-frame &optional frame
+ This function lowers frame FRAME.
+
+ You can also specify auto-raise (raising automatically when a frame
+is selected) or auto-lower (lowering automatically when it is
+deselected). Under X, most ICCCM-compliant window managers will have
+an option to do this for you, but the following variables are provided
+in case you're using a broken WM. (Under FSF Emacs, the same
+functionality is provided through the `auto-raise' and `auto-lower'
+frame properties.)
+
+ - Variable: auto-raise-frame
+ This variable's value is `t' if frames will be raised to the top
+ when selected.
+
+ - Variable: auto-lower-frame
+ This variable's value is `t' if frames will be lowered to the
+ bottom when no longer selected.
+
+ Auto-raising and auto-lowering is implemented through functions
+attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
+Hooks::). Under normal circumstances, you should not call these
+functions directly.
+
+ - Function: default-select-frame-hook
+ This hook function implements the `auto-raise-frame' variable; it
+ is for use as the value of `select-frame-hook'.
+
+ - Function: default-deselect-frame-hook
+ This hook function implements the `auto-lower-frame' variable; it
+ is for use as the value of `deselect-frame-hook'.
+
+\1f
+File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
+
+Frame Configurations
+====================
+
+ 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 &optional nodelete
+ This function restores the state of frames described by
+ CONFIGURATION, which should be the return value from a previous
+ call to `current-frame-configuration'.
+
+ Each frame listed in CONFIGURATION has its position, size, window
+ configuration, and other properties set as specified in
+ CONFIGURATION.
+
+ Ordinarily, this function deletes all existing frames not listed in
+ CONFIGURATION. But if optional second argument NODELETE is
+ non-`nil', the unwanted frames are iconified instead.
+
+\1f
+File: lispref.info, Node: 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.
+
+\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.
+
+\1f
+File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices
+
+Basic Device Functions
+======================
+
+ - Function: device-list
+ This function returns a list of all existing devices.
+
+ - Function: device-or-frame-p object
+ This function returns non-`nil' if OBJECT is a device or frame.
+ This function is useful because devices and frames are similar in
+ many respects and many functions can operate on either one.
+
+ - Function: device-frame-list &optional device
+ This function returns a list of all frames on DEVICE. DEVICE
+ defaults to the currently selected device.
+
+ - Function: frame-device &optional frame
+ This function returns the device that FRAME is on. FRAME defaults
+ to the currently selected frame.
+
+\1f
+File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices
+
+Console Types and Device Classes
+================================
+
+ Every device is of a particular "type", which describes how the
+connection to that device is made and how the device operates, and a
+particular "class", which describes other characteristics of the device
+(currently, the color capabilities of the device).
+
+ The currently-defined device types are
+
+`x'
+ A connection to an X display (such as `willow:0').
+
+`tty'
+ A connection to a tty (such as `/dev/ttyp3').
+
+`stream'
+ A stdio connection. This describes a device for which input and
+ output is only possible in a stream-like fashion, such as when
+ XEmacs in running in batch mode. The very first device created by
+ XEmacs is a terminal device and is used to print out messages of
+ various sorts (for example, the help message when you use the
+ `-help' command-line option).
+
+ The currently-defined device classes are
+`color'
+ A color device.
+
+`grayscale'
+ A grayscale device (a device that can display multiple shades of
+ gray, but no color).
+
+`mono'
+ A device that can only display two colors (e.g. black and white).
+
+ - Function: device-type &optional device
+ This function returns the type of DEVICE. This is a symbol whose
+ name is one of the device types mentioned above. DEVICE defaults
+ to the selected device.
+
+ - Function: device-or-frame-type device-or-frame
+ This function returns the type of DEVICE-OR-FRAME.
+
+ - Function: device-class &optional device
+ This function returns the class (color behavior) of DEVICE. This
+ is a symbol whose name is one of the device classes mentioned
+ above.
+
+ - Function: valid-device-type-p device-type
+ This function returns whether DEVICE-TYPE (which should be a
+ symbol) specifies a valid device type.
+
+ - Function: valid-device-class-p device-class
+ This function returns whether DEVICE-CLASS (which should be a
+ symbol) specifies a valid device class.
+
+ - Variable: terminal-device
+ This variable holds the initial terminal device object, which
+ represents XEmacs's stdout.
+
+\1f
+File: lispref.info, Node: Connecting to a Console or Device, Next: The Selected Console and Device, Prev: Console Types and Device Classes, Up: Consoles and Devices
+
+Connecting to a Console or Device
+=================================
+
+ - Function: make-device type connection &optional props
+ This function creates a new device.
+
+ The following two functions create devices of specific types and are
+written in terms of `make-device'.
+
+ - Function: make-tty-device &optional tty terminal-type
+ This function creates a new tty device on TTY. This also creates
+ the tty's first frame. TTY should be a string giving the name of
+ a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
+ returned by the `tty' command issued from the Unix shell. A value
+ of `nil' means use the stdin and stdout as passed to XEmacs from
+ the shell. If TERMINAL-TYPE is non-`nil', it should be a string
+ specifying the type of the terminal attached to the specified tty.
+ If it is `nil', the terminal type will be inferred from the
+ `TERM' environment variable.
+
+ - Function: make-x-device &optional display argv-list
+ This function creates a new device connected to DISPLAY. Optional
+ argument ARGV-LIST is a list of strings describing command line
+ options.
+
+ - Function: delete-device device &optional force
+ This function deletes DEVICE, permanently eliminating it from use.
+ This disconnects XEmacs's connection to the device.
+
+ - Variable: create-device-hook
+ This variable, if non-`nil', should contain a list of functions,
+ which are called when a device is created.
+
+ - Variable: delete-device-hook
+ This variable, if non-`nil', should contain a list of functions,
+ which are called when a device is deleted.
+
+ - Function: console-live-p object
+ This function returns non-`nil' if OBJECT is a console that has
+ not been deleted.
+
+ - Function: device-live-p object
+ This function returns non-`nil' if OBJECT is a device that has not
+ been deleted.
+
+ - Function: device-x-display device
+ This function returns the X display which DEVICE is connected to,
+ if DEVICE is an X device.
+
+\1f