Frames
******

A FRAME is a rectangle on the screen that contains one or more Emacs 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 Emacs runs on a text-only terminal, it has just one frame, a terminal frame.  There is no way to create another terminal frame after startup.  If Emacs has an X display, it does not have a terminal frame; instead, it starts with a single X window frame.  You can create more; see Creating Frames.

 -- Function: framep object
     This predicate returns t if OBJECT is a frame, and nil otherwise.

See Display, for related information.

Creating Frames
===============

To create a new frame, call the function make-frame.

 -- Function: make-frame alist
     This function creates a new frame, if the display mechanism permits creation of frames.  (An X server does; an ordinary terminal does not.)

     The argument is an alist specifying frame parameters.  Any parameters not mentioned in ALIST default according to the value of the variable default-frame-alist; parameters not specified there either default from the standard X defaults file and X resources.

     The set of possible parameters depends in principle on what kind of window system Emacs uses to display its the frames.  See X Frame Parameters, for documentation of individual parameters you can specify when creating an X window frame.

 -- Variable: default-frame-alist
     This is an alist specifying default values of frame parameters. Each element has the form:

          (PARAMETER . VALUE)

     If you use options that specify window appearance when you invoke Emacs, they take effect by adding elements to default-frame-alist. See Command Arguments (The GNU Emacs Manual).

 -- Variable: before-make-frame-hook
     A normal hook run by make-frame before it actually creates the frame.

 -- Variable: after-make-frame-hook
     A normal hook run by make-frame after it creates the frame.

Frame Parameters
================

A frame has many parameters that control its appearance and behavior. Just what parameters a frame has depends on what display mechanism it uses.

Frame parameters exist for the sake of window systems.  A terminal frame has a few parameters, for compatibility's sake only.  You can't change these parameters directly; the only ones that ever change are the height and width.

Access to Frame Parameters
--------------------------

These functions let you read and change the parameter values of a frame.

 -- Function: frame-parameters frame
     The function frame-parameters returns an alist listing all the parameters of FRAME and their values.

 -- Function: modify-frame-parameters frame alist
     This function alters the parameters of frame FRAME based on the elements of ALIST.  Each element of ALIST has the form (PARM . VALUE), where PARM is a symbol naming a parameter.  If you don't mention a parameter in ALIST, its value doesn't change.

Initial Frame Parameters
------------------------

You can specify the parameters for the initial startup frame by setting initial-frame-alist in your .emacs file.

 -- Variable: initial-frame-alist
     This variable's value is an alist of parameter values used when creating the initial X window frame.

If these parameters specify a separate minibuffer-only frame, and you have not created one, Emacs creates one for you.

 -- Variable: minibuffer-frame-alist
     This variable's value is an alist of parameter values used when creating an initial minibuffer-only frame---if such a frame is needed, according to the parameters for the main initial frame.

X Window Frame Parameters
-------------------------

Just what parameters a frame has depends on what display mechanism it uses.  Here is a table of the parameters of an X window frame:

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, Emacs 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 Emacs executable) when looking up X resources for the frame.

left
     The screen position of the left edge, in pixels.

top
     The screen position of the top edge, in pixels.

height
     The height of the frame contents, in pixels.

width
     The width of the frame contents, in pixels.

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, a minibuffer window (in some other frame) means the new frame uses that minibuffer.

font
     The name of the font for displaying text in the frame.  This is a string.

auto-raise
     Whether selecting the frame raises it (non-nil means yes).

auto-lower
     Whether deselecting the frame lowers it (non-nil means yes).

vertical-scroll-bars
     Whether the frame has scroll bars for vertical scrolling (non-nil means yes).

horizontal-scroll-bars
     Whether the frame has scroll bars for horizontal scrolling (non-nil means yes).  (Horizontal scroll bars are not currently implemented.)

icon-type
     The type of icon to use for this frame when it is iconified. Non-nil specifies a bitmap icon, nil a text icon.

foreground-color
     The color to use for the inside of a character.  This is a string; the X server defines the meaningful color names.

background-color
     The color to use for the background of text.

mouse-color
     The color for the mouse cursor.

cursor-color
     The color for the cursor that shows point.

border-color
     The color for the border of the frame.

cursor-type
     The way to display the cursor.  There are two legitimate values: bar and box.  The symbol bar specifies a vertical bar between characters as the cursor.  The symbol box specifies an ordinary black box overlaying the character after point; that is the default.

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.

visibility
     The state of visibility of the frame.  There are three possibilities: nil for invisible, t for visible, and icon for iconified.  See Visibility of Frames.

menu-bar-lines
     The number of lines to allocate at the top of the frame for a menu bar. The default is 1.  See Menu Bar.

parent-id
     The X window number of the window that should be the parent of this one. Specifying this lets you create an Emacs window inside some other application's window.  (It is not certain this will be implemented; try it and see if it works.)

Frame Size And Position
-----------------------

You can read or change the size and position of a frame using the frame parameters left, top, height and width.  When you create a frame, you must specify either both size parameters or neither.  Likewise, you must specify either both position parameters or neither.  Whatever geometry parameters 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, counting 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 characters.  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: frame-char-height &optional frame
 -- Function: frame-char-width &optional frame
     These functions return the height and width, respectively, of a character in FRAME, measured in pixels.  The values depend on the choice of font.  If you don't supply FRAME, these functions use the selected frame.

 -- Function: set-frame-size frame cols rows
     This function sets the size of FRAME, measured in characters; COLS and ROWS specify the new width and height.

     To set the size with values measured in pixels, use modify-frame-parameters to set the width and height parameters.  See X Frame Parameters.

The old-fashioned functions set-screen-height and set-screen-width, which were used to specify the height and width of the screen in Emacs versions that did not support multiple frames, are still usable.  They apply to the selected frame.  See Screen Size.

 -- Function: x-parse-geometry geom
     The function x-parse-geometry converts a standard X windows geometry string to an alist which you can use as part of the argument to make-frame.

     The alist describes which parameters were specified in GEOM, and gives the values specified for them.  Each element looks like (PARAMETER . VALUE).  The possible PARAMETER values are left, top, width, and height.

          (x-parse-geometry "35x70+0-0")
               => ((width . 35) (height . 70) (left . 0) (top . -1))

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.  There is no way to cancel the deletion of a frame aside from restoring a saved frame configuration (see Frame Configurations); this is similar to the way windows behave.

 -- 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.

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 Emacs.

 -- Function: visible-frame-list
     This function returns a list of just the currently visible frames. See Visibility of Frames.

 -- Function: next-frame &optional frame minibuf
     The function next-frame lets you cycle conveniently through all the frames from an arbitrary starting point.  It returns the ``next'' frame after FRAME in the cycle.  If FRAME is omitted or nil, it defaults to the selected frame.

     The second argument, MINIBUF, says which frames to consider:

     nil
          Exclude minibuffer-only frames.

     visible
          Consider all visible frames.

     a window
          Consider only the frames using that particular window as their minibuffer.

     anything else
          Consider all frames.

 -- Function: previous-frame &optional frame minibuf
     Like next-frame, but cycles through all frames in the opposite direction.

Frames and Windows
==================

All the non-minibuffer windows in a frame are arranged in a tree of subdivisions; the root of this tree is available via the function frame-root-window.  Each window is part of one and only one frame; you can get the frame with window-frame.

 -- Function: frame-root-window frame
     This returns the root window of frame FRAME.

 -- Function: window-frame window
     This function returns the frame that WINDOW is on.

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 frame
     This function returns the window on FRAME which is selected within FRAME.

Conversely, selecting a window for Emacs with select-window also makes that window selected within its frame.  See Selecting Windows.

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 (see 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 frame on which to find the minibuffer to use.  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.

If you use a minibuffer-only frame, you might want that frame to raise when you enter the minibuffer.  If so, set the variable minibuffer-auto-raise to t.  See Raising and Lowering.

Input Focus
===========

At any time, one frame in Emacs is the selected frame.  The selected window always resides on the selected frame.

 -- Function: selected-frame
     This function returns the selected frame.

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.

 -- Function: select-frame frame
     This function selects frame FRAME, temporarily disregarding the focus of the X server.  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.

Emacs cooperates with the X server and the window managers by arranging to select frames according to what the server and window manager ask for.  It does so by generating a special kind of input event, called a focus event.  The command loop handles a focus event by calling handle-select-frame.  See Focus Events.

 -- Command: handle-switch-frame frame
     This function handles a focus event by selecting frame FRAME.

     Focus events normally do their job by invoking this command. Don't call it for any other reason.

 -- Function: redirect-frame-focus frame focus-frame
     This function redirects focus from FRAME to FOCUS-FRAME. This means that FOCUS-FRAME will receive subsequent keystrokes and intended for FRAME.  After such an event, the value of last-event-frame will be FOCUS-FRAME.  Also, switch-frame events specifying FRAME will instead select FOCUS-FRAME.

     If FOCUS-FRAME is nil, that cancels any existing redirection for FRAME, which therefore once again receives its own events.

     One use of focus redirection is for frames that don't have minibuffers. These frames use minibuffers on other frames.  Activating a minibuffer on another frame redirects focus to that frame.  This puts the focus on the minibuffer's frame, where it belongs, even though the mouse remains in the frame which activated the minibuffer.

     Selecting a frame can also change focus redirections.  Selecting frame bar, when foo had been selected, changes any redirections pointing to foo so that they point to bar instead.  This allows focus redirection to work properly when the user switches from one frame to another using select-window.

     This means that a frame whose focus is redirected to itself is treated differently from a frame whose focus is not redirected. select-frame affects the former but not the latter.

     The redirection lasts until redirect-frame-focus is called to change it.

Visibility of Frames
====================

A frame may be visible, invisible, or iconified.  If it is visible, you can see its contents.  If it is iconified, the frame's contents do not appear on the screen, but an icon does.  If the frame is invisible, it doesn't show in the screen, not even as an icon.

 -- Command: make-frame-visible &optional frame
     This function makes frame FRAME visible.  If you omit FRAME, it makes the selected frame visible.

 -- Command: make-frame-invisible &optional frame
     This function makes frame FRAME invisible.  If you omit FRAME, it makes the selected frame invisible.

 -- Command: iconify-frame &optional frame
     This function iconifies frame FRAME.  If you omit FRAME, it iconifies the selected frame.

 -- Function: frame-visible-p frame
     This returns the visibility status of frame FRAME.  The value is t if FRAME is visible, nil if it is invisible, and icon if it is iconified.

The visibility status of a frame is also available as a frame parameter.  You can read or change it as such.  See X Frame Parameters.

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 Emacs's X windows with these functions:

 -- Function: raise-frame frame
     This function raises frame FRAME.

 -- Function: lower-frame frame
     This function lowers frame FRAME.

 -- User Option: minibuffer-auto-raise
     If this is non-nil, activation of the minibuffer raises the frame that the minibuffer window is in.

You can also enable auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected) for any frame using frame parameters.  See X Frame Parameters.

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 which describes the current arrangement of frames and their contents.

 -- Function: set-frame-configuration configuration
     This function restores the state of frames described in CONFIGURATION.

Mouse Tracking
==============

Sometimes it is useful to track the mouse, which means, to display something to indicate where the mouse is and move the indicator as the mouse moves.  For efficient mouse tracking, you need a way to wait until the mouse actually moves.

The convenient way to track the mouse is to ask for events to represent mouse motion.  Then you can wait for motion by waiting for an event.  In addition, you can easily handle any other sorts of events that may occur.  That is useful, because normally you don't want to track the mouse forever---only until some other event, such as the release of a button.

 -- Special Form: track-mouse body...
     Execute BODY, meanwhile generating input events for mouse motion. The code in BODY can read these events with read-event or read-key-sequence.  See Motion Events, for the format of mouse motion events.

     The value of track-mouse is that of the last form in BODY.

The usual purpose of tracking mouse motion is to indicate on the screen the consequences of pushing or releasing a button at the current position.

Mouse Position
==============

The functions mouse-position and set-mouse-position give access to the current position of the mouse.

 -- Function: mouse-position
     This function returns a description of the position of the mouse.  The value looks like (FRAME X . Y), where X and Y are integers giving the position in pixels relative to the top left corner of the inside of FRAME.

 -- Function: set-mouse-position frame x y
     This function warps the mouse to position X, Y in frame FRAME.  The arguments X and Y are integers, giving the position in pixels relative to the top left corner of the inside of FRAME.

     Warping the mouse means changing the screen position of the mouse as if the user had moved the physical mouse---thus simulating the effect of actual mouse motion.

Pop-Up Menus
============

 -- Function: x-popup-menu position menu
     This function displays a pop-up menu and returns an indication of what selection the user makes.

     The argument POSITION specifies where on the screen to put the menu.  It can be either a mouse button event (which says to put the menu where the user actuated the button) or a list of this form:

          ((XOFFSET YOFFSET) WINDOW)

     where XOFFSET and YOFFSET are positions measured in characters, counting from the top left corner of WINDOW's frame.

     If POSITION is t, it means to use the current mouse position.  If POSITION is nil, it means to precompute the key binding equivalents for the keymaps specified in MENU, without actually displaying or popping up the menu.

     The argument MENU says what to display in the menu.  It can be a keymap or a list of keymaps (see Menu Keymaps).  Alternatively, it can have the following form:

          (TITLE PANE1 PANE2...)

     where each pane is a list of form

          (TITLE (LINE ITEM)...)

     Each LINE should be a string, and each ITEM should be the value to return if that LINE is chosen.

Usage note: Don't use x-popup-menu to display a menu if a prefix key with a menu keymap would do the job.  If you use a menu keymap to implement a menu, C-h c and C-h a can see the individual items in that menu and provide help for them.  If instead you implement the menu by defining a command that calls x-popup-menu, the help facilities cannot know what happens inside that command, so they cannot give any help for the menu's items.  This is the reason why all the menu bar items except Buffers are implemented with menu keymaps (see Menu Keymaps).

Dialog Boxes
============

A dialog box is a variant of a pop-up menu.  It looks a little different (if Emacs uses an X toolkit), it always appears in the center of a frame, and it has just one level and one pane.  The main use of dialog boxes is for asking questions that the user can answer with ``yes'', ``no'', and a few other alternatives.  The functions y-or-n-p and yes-or-no-p use dialog boxes instead of the keyboard, when called from commands invoked by mouse clicks.

 -- Function: x-popup-dialog position contents
     This function displays a pop-up dialog box and returns an indication of what selection the user makes.  The argument CONTENTS specifies the alternatives to offer; it has this format:

          (TITLE (STRING VALUE)...)

     which looks like the list that specifies a single pane for x-popup-menu.

     Dialog boxes always appear in the center of a frame; the argument POSITION specifies which frame.  The possible values are as in x-popup-menu, but the precise coordinates don't matter; only the frame matters.

X Selections
============

The X server records a set of selections which permit transfer of data between application programs.  The various selections are distinguished by selection types, represented in Emacs by symbols.  X clients including Emacs can read or set the selection for any given type.

 -- Function: x-set-selection type data
     This function sets a ``selection'' in the X server.  It takes two arguments: a selection type TYPE, and the value to assign to it, DATA.  If DATA is nil, it means to clear out the selection.  Otherwise, DATA may be a string, a symbol, an integer (or a cons of two integers or list of two integers), an overlay, or a cons of two markers pointing to the same buffer.  An overlay or a pair of markers stands for text in the overlay or between the markers.

     The data may also be a vector of valid non-vector selection values.

     Each possible TYPE has its own selection value, which changes independently.  The usual values of TYPE are PRIMARY and SECONDARY; these are symbols with upper-case names, in accord with X Window System conventions.  The default is PRIMARY.

 -- Function: x-get-selection type data-type
     This function accesses selections set up by Emacs or by other X clients.  It takes two optional arguments, TYPE and DATA-TYPE.  The default for TYPE, the selection type, is PRIMARY.

     The DATA-TYPE argument specifies the form of data conversion to use, to convert the raw data obtained from another X client into Lisp data.  Meaningful values include TEXT, STRING, TARGETS, LENGTH, DELETE, FILE_NAME, CHARACTER_POSITION, LINE_NUMBER, COLUMN_NUMBER, OWNER_OS, HOST_NAME, USER, CLASS, NAME, ATOM, and INTEGER.  (These are symbols with upper-case names in accord with X conventions.)  The default for DATA-TYPE is STRING.

The X server also has a set of numbered cut buffers which can store text or other data being moved between applications.  Cut buffers are considered obsolete, but Emacs supports them for the sake of X clients that still use them.

 -- Function: x-get-cut-buffer n
     This function returns the contents of cut buffer number N.

 -- Function: x-set-cut-buffer string
     This function stores STRING into the first cut buffer (cut buffer 0), moving the other values down through the series of cut buffers, much like the way successive kills in Emacs move down the kill ring.

X Connections
=============

You can close the connection with the X server with the function x-close-current-connection, and open a new one with x-open-connection (perhaps with a different server and display).

 -- Function: x-close-current-connection
     This function closes the connection to the X server.  It deletes all frames, making Emacs effectively inaccessible to the user; therefore, a Lisp program that closes the connection should open another one.

 -- Function: x-open-connection display &optional resource-string
     This function opens a connection to an X server, for use of display DISPLAY.

     The optional argument RESOURCE-STRING is a string of resource names and values, in the same format used in the .Xresources file.  The values you specify override the resource values recorded in the X server itself.  Here's an example of what this string might look like:

          "*BorderWidth: 3\n*InternalBorder: 2\n"

     See Resources.

 -- Function: x-display-color-p
     This returns t if the connected X display has color, and nil otherwise.

 -- Function: x-color-defined-p color
     This function reports whether a color name is meaningful and supported on the X display Emacs is using.  It returns t if the display supports that color; otherwise, nil.

     Black-and-white displays support just two colors, "black" or "white".  Color displays support many other colors.

 -- Function: x-synchronize flag
     The function x-synchronize enables or disables synchronous communication with the X server.  It enables synchronous communication if FLAG is non-nil, and disables it if FLAG is nil.

     In synchronous mode, Emacs waits for a response to each X protocol command before doing anything else.  This is useful for debugging Emacs, because protocol errors are reported right away, which helps you find the erroneous command.  Synchronous mode is not the default because it is much slower.

X Resources
===========

 -- Function: x-get-resource attribute &optional name class
     The function x-get-resource retrieves a resource value from the X Windows defaults database.

     Resources are indexed by a combination of a key and a class. This function searches using a key of the form INSTANCE.ATTRIBUTE, using the name under which Emacs was invoked as INSTANCE, and using Emacs as the class.

     The optional arguments COMPONENT and SUBCLASS add to the key and the class, respectively.  You must specify both of them or neither. If you specify them, the key is INSTANCE.COMPONENT.ATTRIBUTE, and the class is Emacs.SUBCLASS.

See X Resources (The GNU Emacs Manual).

Data about the X Server
=======================

This section describes functions and a variable that you can use to get information about the capabilities and origin of the X server that Emacs is displaying its frames on.

 -- Function: x-display-screens
     This function returns the number of screens associated with the current display.

 -- Function: x-server-version
     This function returns the list of version numbers of the X server in use.

 -- Function: x-server-vendor
     This function returns the vendor supporting the X server in use.

 -- Function: x-display-pixel-height
     This function returns the height of this X screen in pixels.

 -- Function: x-display-mm-height
     This function returns the height of this X screen in millimeters.

 -- Function: x-display-pixel-width
     This function returns the width of this X screen in pixels.

 -- Function: x-display-mm-width
     This function returns the width of this X screen in millimeters.

 -- Function: x-display-backing-store
     This function returns the backing store capability of this screen. Values can be the symbols always, when-mapped, or not-useful.

 -- Function: x-display-save-under
     This function returns non-nil if this X screen supports the SaveUnder feature.

 -- Function: x-display-planes
     This function returns the number of planes this display supports.

 -- Function: x-display-visual-class
     This function returns the visual class for this X screen.  The value is one of the symbols static-gray, gray-scale, static-color, pseudo-color, true-color, and direct-color.

 -- Function: x-display-color-p
     This function returns t if the X screen in use is a color screen.

 -- Function: x-display-color-cells
     This function returns the number of color cells this X screen supports.