"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/lispref/frames.texi" (23 Apr 2018, 183388 Bytes) of package /linux/misc/emacs-26.1.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "frames.texi": 25.3_vs_26.1.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Frames

A frame is a screen object that contains one or more Emacs windows (@pxref{Windows}). It is the kind of object called a “window” in the terminology of graphical environments; but we can’t call it a “window” here, because Emacs uses that word in a different way. In Emacs Lisp, a frame object is a Lisp object that represents a frame on the screen. @xref{Frame Type}.

A frame initially contains a single main window and/or a minibuffer window; you can subdivide the main window vertically or horizontally into smaller windows. @xref{Splitting Windows}.

A terminal is a display device capable of displaying one or more Emacs frames. In Emacs Lisp, a terminal object is a Lisp object that represents a terminal. @xref{Terminal Type}.

There are two classes of terminals: text terminals and graphical terminals. Text terminals are non-graphics-capable displays, including xterm and other terminal emulators. On a text terminal, each Emacs frame occupies the terminal’s entire screen; although you can create additional frames and switch between them, the terminal only shows one frame at a time. Graphical terminals, on the other hand, are managed by graphical display systems such as the X Window System, which allow Emacs to show multiple frames simultaneously on the same display.

On GNU and Unix systems, you can create additional frames on any available terminal, within a single Emacs session, regardless of whether Emacs was started on a text or graphical terminal. Emacs can display on both graphical and text terminals simultaneously. This comes in handy, for instance, when you connect to the same session from several remote locations. See section Multiple Terminals.

Function: framep object

This predicate returns a non-nil value if object is a frame, and nil otherwise. For a frame, the value indicates which kind of display the frame uses:

t

The frame is displayed on a text terminal.

x

The frame is displayed on an X graphical terminal.

w32

The frame is displayed on a MS-Windows graphical terminal.

ns

The frame is displayed on a GNUstep or Macintosh Cocoa graphical terminal.

pc

The frame is displayed on an MS-DOS terminal.

Function: frame-terminal &optional frame

This function returns the terminal object that displays frame. If frame is nil or unspecified, it defaults to the selected frame.

Function: terminal-live-p object

This predicate returns a non-nil value if object is a terminal that is live (i.e., not deleted), and nil otherwise. For live terminals, the return value indicates what kind of frames are displayed on that terminal; the list of possible values is the same as for framep above.

On a graphical terminal we distinguish two types of frames: A normal top-level frame is a frame whose window-system window is a child of the window-system’s root window for that terminal. A child frame is a frame whose window-system window is the child of the window-system window of another Emacs frame. See section Child Frames.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Creating Frames

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

Command: make-frame &optional parameters

This function creates and returns a new frame, displaying the current buffer.

The parameters argument is an alist that specifies frame parameters for the new frame. See section Frame Parameters. If you specify the terminal parameter in parameters, the new frame is created on that terminal. Otherwise, if you specify the window-system frame parameter in parameters, that determines whether the frame should be displayed on a text terminal or a graphical terminal. @xref{Window Systems}. If neither is specified, the new frame is created in the same terminal as the selected frame.

Any parameters not mentioned in parameters default to the values in the alist default-frame-alist (see section Initial Frame Parameters); parameters not specified there default from the X resources or its equivalent on your operating system (see X Resources in The GNU Emacs Manual). After the frame is created, this function applies any parameters specified in frame-inherited-parameters (see below) it has no assigned yet, taking the values from the frame that was selected when make-frame was called.

Note that on multi-monitor displays (see section Multiple Terminals), the window manager might position the frame differently than specified by the positional parameters in parameters (see section Position Parameters). For example, some window managers have a policy of displaying the frame on the monitor that contains the largest part of the window (a.k.a. the dominating monitor).

This function itself does not make the new frame the selected frame. See section Input Focus. The previously selected frame remains selected. On graphical terminals, however, the windowing system may select the new frame for its own reasons.

Variable: before-make-frame-hook

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

Variable: after-make-frame-functions

An abnormal hook run by make-frame after it created the frame. Each function in after-make-frame-functions receives one argument, the frame just created.

Note that any functions added to these hooks by your initial file are usually not run for the initial frame, since Emacs reads the initial file only after creating that frame. However, if the initial frame is specified to use a separate minibuffer frame (see section Minibuffers and Frames), the functions will be run for both, the minibuffer-less and the minibuffer frame.

Variable: frame-inherited-parameters

This variable specifies the list of frame parameters that a newly created frame inherits from the currently selected frame. For each parameter (a symbol) that is an element in this list and has not been assigned earlier when processing make-frame, the function sets the value of that parameter in the created frame to its value in the selected frame.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Multiple Terminals

Emacs represents each terminal as a terminal object data type (@pxref{Terminal Type}). On GNU and Unix systems, Emacs can use multiple terminals simultaneously in each session. On other systems, it can only use a single terminal. Each terminal object has the following attributes:

There is no primitive for creating terminal objects. Emacs creates them as needed, such as when you call make-frame-on-display (described below).

Function: terminal-name &optional terminal

This function returns the file name of the device used by terminal. If terminal is omitted or nil, it defaults to the selected frame’s terminal. terminal can also be a frame, meaning that frame’s terminal.

Function: terminal-list

This function returns a list of all live terminal objects.

Function: get-device-terminal device

This function returns a terminal whose device name is given by device. If device is a string, it can be either the file name of a terminal device, or the name of an X display of the form ‘host:server.screen’. If device is a frame, this function returns that frame’s terminal; nil means the selected frame. Finally, if device is a terminal object that represents a live terminal, that terminal is returned. The function signals an error if its argument is none of the above.

Function: delete-terminal &optional terminal force

This function deletes all frames on terminal and frees the resources used by it. It runs the abnormal hook delete-terminal-functions, passing terminal as the argument to each function.

If terminal is omitted or nil, it defaults to the selected frame’s terminal. terminal can also be a frame, meaning that frame’s terminal.

Normally, this function signals an error if you attempt to delete the sole active terminal, but if force is non-nil, you are allowed to do so. Emacs automatically calls this function when the last frame on a terminal is deleted (see section Deleting Frames).

Variable: delete-terminal-functions

An abnormal hook run by delete-terminal. Each function receives one argument, the terminal argument passed to delete-terminal. Due to technical details, the functions may be called either just before the terminal is deleted, or just afterwards.

A few Lisp variables are terminal-local; that is, they have a separate binding for each terminal. The binding in effect at any time is the one for the terminal that the currently selected frame belongs to. These variables include default-minibuffer-frame, defining-kbd-macro, last-kbd-macro, and system-key-alist. They are always terminal-local, and can never be buffer-local (@pxref{Buffer-Local Variables}).

On GNU and Unix systems, each X display is a separate graphical terminal. When Emacs is started from within the X window system, it uses the X display specified by the DISPLAY environment variable, or by the ‘--display’ option (see Initial Options in The GNU Emacs Manual). Emacs can connect to other X displays via the command make-frame-on-display. Each X display has its own selected frame and its own minibuffer windows; however, only one of those frames is the selected frame at any given moment (see section Input Focus). Emacs can even connect to other text terminals, by interacting with the emacsclient program. See Emacs Server in The GNU Emacs Manual.

A single X server can handle more than one display. Each X display has a three-part name, ‘hostname:displaynumber.screennumber’. The first part, hostname, specifies the name of the machine to which the display is physically connected. The second part, displaynumber, is a zero-based number that identifies one or more monitors connected to that machine that share a common keyboard and pointing device (mouse, tablet, etc.). The third part, screennumber, identifies a zero-based screen number (a separate monitor) that is part of a single monitor collection on that X server. When you use two or more screens belonging to one server, Emacs knows by the similarity in their names that they share a single keyboard.

Systems that don’t use the X window system, such as MS-Windows, don’t support the notion of X displays, and have only one display on each host. The display name on these systems doesn’t follow the above 3-part format; for example, the display name on MS-Windows systems is a constant string ‘w32’, and exists for compatibility, so that you could pass it to functions that expect a display name.

Command: make-frame-on-display display &optional parameters

This function creates and returns a new frame on display, taking the other frame parameters from the alist parameters. display should be the name of an X display (a string).

Before creating the frame, this function ensures that Emacs is set up to display graphics. For instance, if Emacs has not processed X resources (e.g., if it was started on a text terminal), it does so at this time. In all other respects, this function behaves like make-frame (see section Creating Frames).

Function: x-display-list

This function returns a list that indicates which X displays Emacs has a connection to. The elements of the list are strings, and each one is a display name.

Function: x-open-connection display &optional xrm-string must-succeed

This function opens a connection to the X display display, without creating a frame on that display. Normally, Emacs Lisp programs need not call this function, as make-frame-on-display calls it automatically. The only reason for calling it is to check whether communication can be established with a given X display.

The optional argument xrm-string, if not nil, is a string of resource names and values, in the same format used in the ‘.Xresources’ file. See X Resources in The GNU Emacs Manual. These values apply to all Emacs frames created on this display, overriding the resource values recorded in the X server. Here’s an example of what this string might look like:

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

If must-succeed is non-nil, failure to open the connection terminates Emacs. Otherwise, it is an ordinary Lisp error.

Function: x-close-connection display

This function closes the connection to display display. Before you can do this, you must first delete all the frames that were open on that display (see section Deleting Frames).

On some multi-monitor setups, a single X display outputs to more than one physical monitor. You can use the functions display-monitor-attributes-list and frame-monitor-attributes to obtain information about such setups.

Function: display-monitor-attributes-list &optional display

This function returns a list of physical monitor attributes on display, which can be a display name (a string), a terminal, or a frame; if omitted or nil, it defaults to the selected frame’s display. Each element of the list is an association list, representing the attributes of a physical monitor. The first element corresponds to the primary monitor. The attribute keys and values are:

geometry

Position of the top-left corner of the monitor’s screen and its size, in pixels, as ‘(x y width height)’. Note that, if the monitor is not the primary monitor, some of the coordinates might be negative.

workarea

Position of the top-left corner and size of the work area (usable space) in pixels as ‘(x y width height)’. This may be different from ‘geometry’ in that space occupied by various window manager features (docks, taskbars, etc.) may be excluded from the work area. Whether or not such features actually subtract from the work area depends on the platform and environment. Again, if the monitor is not the primary monitor, some of the coordinates might be negative.

mm-size

Width and height in millimeters as ‘(width height)

frames

List of frames that this physical monitor dominates (see below).

name

Name of the physical monitor as string.

source

Source of the multi-monitor information as string; e.g., ‘XRandr’ or ‘Xinerama’.

x, y, width, and height are integers. ‘name’ and ‘source’ may be absent.

A frame is dominated by a physical monitor when either the largest area of the frame resides in that monitor, or (if the frame does not intersect any physical monitors) that monitor is the closest to the frame. Every (non-tooltip) frame (whether visible or not) in a graphical display is dominated by exactly one physical monitor at a time, though the frame can span multiple (or no) physical monitors.

Here’s an example of the data produced by this function on a 2-monitor display:

  (display-monitor-attributes-list)
  ⇒
  (((geometry 0 0 1920 1080) ;; Left-hand, primary monitor
    (workarea 0 0 1920 1050) ;; A taskbar occupies some of the height
    (mm-size 677 381)
    (name . "DISPLAY1")
    (frames #<frame emacs@host *Messages* 0x11578c0>
            #<frame emacs@host *scratch* 0x114b838>))
   ((geometry 1920 0 1680 1050) ;; Right-hand monitor
    (workarea 1920 0 1680 1050) ;; Whole screen can be used
    (mm-size 593 370)
    (name . "DISPLAY2")
    (frames)))
Function: frame-monitor-attributes &optional frame

This function returns the attributes of the physical monitor dominating (see above) frame, which defaults to the selected frame.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Frame Geometry

The geometry of a frame depends on the toolkit that was used to build this instance of Emacs and the terminal that displays the frame. This chapter describes these dependencies and some of the functions to deal with them. Note that the frame argument of all of these functions has to specify a live frame (see section Deleting Frames). If omitted or nil, it specifies the selected frame (see section Input Focus).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.1 Frame Layout

A visible frame occupies a rectangular area on its terminal’s display. This area may contain a number of nested rectangles, each serving a different purpose. The drawing below sketches the layout of a frame on a graphical terminal:

        <------------ Outer Frame Width ----------->
        ____________________________________________
     ^(0)  ________ External/Outer Border _______   |
     | |  |_____________ Title Bar ______________|  |
     | | (1)_____________ Menu Bar ______________|  | ^
     | | (2)_____________ Tool Bar ______________|  | ^
     | | (3) _________ Internal Border ________  |  | ^
     | |  | |   ^                              | |  | |
     | |  | |   |                              | |  | |
Outer  |  | | Inner                            | |  | Native
Frame  |  | | Frame                            | |  | Frame
Height |  | | Height                           | |  | Height
     | |  | |   |                              | |  | |
     | |  | |<--+--- Inner Frame Width ------->| |  | |
     | |  | |   |                              | |  | |
     | |  | |___v______________________________| |  | |
     | |  |___________ Internal Border __________|  | v
     v |___________ External/Outer Border __________|
           <-------- Native Frame Width -------->

In practice not all of the areas shown in the drawing will or may be present. The meaning of these areas is described below.

Outer Frame

The outer frame is a rectangle comprising all areas shown in the drawing. The edges of that rectangle are called the outer edges of the frame. Together, the outer width and outer height of the frame specify the outer size of that rectangle.

Knowing the outer size of a frame is useful for fitting a frame into the working area of its display (see section Multiple Terminals) or for placing two frames adjacent to each other on the screen. Usually, the outer size of a frame is available only after the frame has been mapped (made visible, see section Visibility of Frames) at least once. For the initial frame or a frame that has not been created yet, the outer size can be only estimated or must be calculated from the window-system’s or window manager’s defaults. One workaround is to obtain the differences of the outer and native (see below) sizes of a mapped frame and use them for calculating the outer size of the new frame.

The position of the upper left corner of the outer frame (indicated by ‘(0)’ in the drawing above) is the outer position of the frame. The outer position of a graphical frame is also referred to as “the position” of the frame because it usually remains unchanged on its display whenever the frame is resized or its layout is changed.

The outer position is specified by and can be set via the left and top frame parameters (see section Position Parameters). For a normal, top-level frame these parameters usually represent its absolute position (see below) with respect to its display’s origin. For a child frame (see section Child Frames) these parameters represent its position relative to the native position (see below) of its parent frame. For frames on text terminals the values of these parameters are meaningless and always zero.

External Border

The external border is part of the decorations supplied by the window manager. It is typically used for resizing the frame with the mouse and is therefore not shown on “fullboth” and maximized frames (see section Size Parameters). Its width is determined by the window manager and cannot be changed by Emacs’ functions.

External borders don’t exist on text terminal frames. For graphical frames, their display can be suppressed by setting the override-redirect or undecorated frame parameter (see section Window Management Parameters).

Outer Border

The outer border is a separate border whose width can be specified with the border-width frame parameter (see section Layout Parameters). In practice, either the external or the outer border of a frame are displayed but never both at the same time. Usually, the outer border is shown only for special frames that are not (fully) controlled by the window manager like tooltip frames (@pxref{Tooltips}), child frames (see section Child Frames) and undecorated or override-redirect frames (see section Window Management Parameters).

Outer borders are never shown on text terminal frames and on frames generated by GTK+ routines. On MS-Windows, the outer border is emulated with the help of a one pixel wide external border. Non-toolkit builds on X allow to change the color of the outer border by setting the border-color frame parameter (see section Layout Parameters).

Title Bar

The title bar, a.k.a. caption bar, is also part of the window manager’s decorations and typically displays the title of the frame (see section Frame Titles) as well as buttons for minimizing, maximizing and deleting the frame. It can be also used for dragging the frame with the mouse. The title bar is usually not displayed for fullboth (see section Size Parameters), tooltip (@pxref{Tooltips}) and child frames (see section Child Frames) and doesn’t exist for terminal frames. Display of the title bar can be suppressed by setting the override-redirect or the undecorated frame parameters (see section Window Management Parameters).

Menu Bar

The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs itself) or external (drawn by the toolkit). Most builds (GTK+, Lucid, Motif and MS-Windows) rely on an external menu bar. NS also uses an external menu bar which, however, is not part of the outer frame. Non-toolkit builds can provide an internal menu bar. On text terminal frames, the menu bar is part of the frame’s root window (@pxref{Windows and Frames}). As a rule, menu bars are never shown on child frames (see section Child Frames). Display of the menu bar can be suppressed by setting the menu-bar-lines parameter (see section Layout Parameters) to zero.

Whether the menu bar is wrapped or truncated whenever its width becomes too large to fit on its frame depends on the toolkit . Usually, only Motif and MS-Windows builds can wrap the menu bar. When they (un-)wrap the menu bar, they try to keep the outer height of the frame unchanged, so the native height of the frame (see below) will change instead.

Tool Bar

Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either internal (drawn by Emacs itself) or external (drawn by a toolkit). The GTK+ and NS builds have the tool bar drawn by the toolkit. The remaining builds use internal tool bars. With GTK+ the tool bar can be located on either side of the frame, immediately outside the internal border, see below. Tool bars are usually not shown for child frames (see section Child Frames). Display of the tool bar can be suppressed by setting the tool-bar-lines parameter (see section Layout Parameters) to zero.

If the variable auto-resize-tool-bars is non-nil, Emacs wraps the internal tool bar when its width becomes too large for its frame. If and when Emacs (un-)wraps the internal tool bar, it by default keeps the outer height of the frame unchanged, so the native height of the frame (see below) will change instead. Emacs built with GTK+, on the other hand, never wraps the tool bar but may automatically increase the outer width of a frame in order to accommodate an overlong tool bar.

Native Frame

The native frame is a rectangle located entirely within the outer frame. It excludes the areas occupied by an external or outer border, the title bar and any external menu or tool bar. The edges of the native frame are called the native edges of the frame. Together, the native width and native height of a frame specify the native size of the frame.

The native size of a frame is the size Emacs passes to the window-system or window manager when creating or resizing the frame from within Emacs. It is also the size Emacs receives from the window-system or window manager whenever these resize the frame’s window-system window, for example, after maximizing the frame by clicking on the corresponding button in the title bar or when dragging its external border with the mouse.

The position of the top left corner of the native frame specifies the native position of the frame. (1)–(3) in the drawing above indicate that position for the various builds:

Accordingly, the native height of a frame may include the height of the tool bar but not that of the menu bar (Lucid, Motif, MS-Windows) or those of the menu bar and the tool bar (non-toolkit and text terminal frames).

The native position of a frame is the reference position for functions that set or return the current position of the mouse (see section Mouse Position) and for functions dealing with the position of windows like window-edges, window-at or coordinates-in-window-p (@pxref{Coordinates and Windows}). It also specifies the (0, 0) origin for locating and positioning child frames within this frame (see section Child Frames).

Note also that the native position of a frame usually remains unaltered on its display when removing or adding the window manager decorations by changing the frame’s override-redirect or undecorated parameter (see section Window Management Parameters).

Internal Border

The internal border is a border drawn by Emacs around the inner frame (see below). Its width is specified by the internal-border-width frame parameter (see section Layout Parameters). Its color is specified by the background of the internal-border face.

Inner Frame

The inner frame is the rectangle reserved for the frame’s windows. It’s enclosed by the internal border which, however, is not part of the inner frame. Its edges are called the inner edges of the frame. The inner width and inner height specify the inner size of the rectangle. The inner frame is sometimes also referred to as the display area of the frame.

As a rule, the inner frame is subdivided into the frame’s root window (@pxref{Windows and Frames}) and the frame’s minibuffer window (@pxref{Minibuffer Windows}). There are two notable exceptions to this rule: A minibuffer-less frame contains a root window only and does not contain a minibuffer window. A minibuffer-only frame contains only a minibuffer window which also serves as that frame’s root window. See Initial Frame Parameters for how to create such frame configurations.

Text Area

The text area of a frame is a somewhat fictitious area that can be embedded in the native frame. Its position is unspecified. Its width can be obtained by removing from that of the native width the widths of the internal border, one vertical scroll bar, and one left and one right fringe if they are specified for this frame, see Layout Parameters. Its height can be obtained by removing from that of the native height the widths of the internal border and the heights of the frame’s internal menu and tool bars and one horizontal scroll bar if specified for this frame.

The absolute position of a frame is given as a pair (X, Y) of horizontal and vertical pixel offsets relative to an origin (0, 0) of the frame’s display. Correspondingly, the absolute edges of a frame are given as pixel offsets from that origin.

Note that with multiple monitors, the origin of the display does not necessarily coincide with the top-left corner of the entire usable display area of the terminal. Hence the absolute position of a frame can be negative in such an environment even when that frame is completely visible.

By convention, vertical offsets increase “downwards”. This means that the height of a frame is obtained by subtracting the offset of its top edge from that of its bottom edge. Horizontal offsets increase “rightwards”, as expected, so a frame’s width is calculated by subtracting the offset of its left edge from that of its right edge.

For a frame on a graphical terminal the following function returns the sizes of the areas described above:

Function: frame-geometry &optional frame

This function returns geometric attributes of frame. The return value is an association list of the attributes listed below. All coordinate, height and width values are integers counting pixels. Note that if frame has not been mapped yet, (see section Visibility of Frames) some of the return values may only represent approximations of the actual values—those that can be seen after the frame has been mapped.

outer-position

A cons representing the absolute position of the outer frame, relative to the origin at position (0, 0) of frame’s display.

outer-size

A cons of the outer width and height of frame.

external-border-size

A cons of the horizontal and vertical width of frame’s external borders as supplied by the window manager. If the window manager doesn’t supply these values, Emacs will try to guess them from the coordinates of the outer and inner frame.

outer-border-width

The width of the outer border of frame. The value is meaningful for non-GTK+ X builds only.

title-bar-size

A cons of the width and height of the title bar of frame as supplied by the window manager or operating system. If both of them are zero, the frame has no title bar. If only the width is zero, Emacs was not able to retrieve the width information.

menu-bar-external

If non-nil, this means the menu bar is external (not part of the native frame of frame).

menu-bar-size

A cons of the width and height of the menu bar of frame.

tool-bar-external

If non-nil, this means the tool bar is external (not part of the native frame of frame).

tool-bar-position

This tells on which side the tool bar on frame is and can be one of left, top, right or bottom. The only toolkit that currently supports a value other than top is GTK+.

tool-bar-size

A cons of the width and height of the tool bar of frame.

internal-border-width

The width of the internal border of frame.

The following function can be used to retrieve the edges of the outer, native and inner frame.

Function: frame-edges &optional frame type

This function returns the absolute edges of the outer, native or inner frame of frame. frame must be a live frame and defaults to the selected one. The returned list has the form (left top right bottom) where all values are in pixels relative to the origin of frame’s display. For terminal frames the values returned for left and top are always zero.

Optional argument type specifies the type of the edges to return: outer-edges means to return the outer edges of frame, native-edges (or nil) means to return its native edges and inner-edges means to return its inner edges.

By convention, the pixels of the display at the values returned for left and top are considered to be inside (part of) frame. Hence, if left and top are both zero, the pixel at the display’s origin is part of frame. The pixels at bottom and right, on the other hand, are considered to lie immediately outside frame. This means that if you have, for example, two side-by-side frames positioned such that the right outer edge of the frame on the left equals the left outer edge of the frame on the right, the pixels at that edge show a part of the frame on the right.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.2 Frame Font

Each frame has a default font which specifies the default character size for that frame. This size is meant when retrieving or changing the size of a frame in terms of columns or lines (see section Size Parameters). It is also used when resizing (@pxref{Window Sizes}) or splitting (@pxref{Splitting Windows}) windows.

The terms line height and canonical character height are sometimes used instead of “default character height”. Similarly, the terms column width and canonical character width are used instead of “default character width”.

Function: frame-char-height &optional frame
Function: frame-char-width &optional frame

These functions return the default height and width of a character in frame, measured in pixels. Together, these values establish the size of the default font on frame. The values depend on the choice of font for frame, see Font and Color Parameters.

The default font can be also set directly with the following function:

Command: set-frame-font font &optional keep-size frames

This sets the default font to font. When called interactively, it prompts for the name of a font, and uses that font on the selected frame. When called from Lisp, font should be a font name (a string), a font object, font entity, or a font spec.

If the optional argument keep-size is nil, this keeps the number of frame lines and columns fixed. (If non-nil, the option frame-inhibit-implied-resize described in the next section will override this.) If keep-size is non-nil (or with a prefix argument), it tries to keep the size of the display area of the current frame fixed by adjusting the number of lines and columns.

If the optional argument frames is nil, this applies the font to the selected frame only. If frames is non-nil, it should be a list of frames to act upon, or t meaning all existing and all future graphical frames.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.3 Frame Position

On graphical systems, the position of a normal top-level frame is specified as the absolute position of its outer frame (see section Frame Geometry). The position of a child frame (see section Child Frames) is specified via pixel offsets of its outer edges relative to the native position of its parent frame.

You can access or change the position of a frame using the frame parameters left and top (see section Position Parameters). Here are two additional functions for working with the positions of an existing, visible frame. For both functions, the argument frame must denote a live frame and defaults to the selected frame.

Function: frame-position &optional frame

For a normal, non-child frame this function returns a cons of the pixel coordinates of its outer position (see section Frame Layout) with respect to the origin (0, 0) of its display. For a child frame (see section Child Frames) this function returns the pixel coordinates of its outer position with respect to an origin (0, 0) at the native position of frame’s parent.

Negative values never indicate an offset from the right or bottom edge of frame’s display or parent frame. Rather, they mean that frame’s outer position is on the left and/or above the origin of its display or the native position of its parent frame. This usually means that frame is only partially visible (or completely invisible). However, on systems where the display’s origin does not coincide with its top-left corner, the frame may be visible on a secondary monitor.

On a text terminal frame both values are zero.

Function: set-frame-position frame x y

This function sets the outer frame position of frame to (x, y). The latter arguments specify pixels and normally count from the origin at the position (0, 0) of frame’s display. For child frames, they count from the native position of frame’s parent frame.

Negative parameter values position the right edge of the outer frame by -x pixels left from the right edge of the screen (or the parent frame’s native rectangle) and the bottom edge by -y pixels up from the bottom edge of the screen (or the parent frame’s native rectangle).

Note that negative values do not permit to align the right or bottom edge of frame exactly at the right or bottom edge of its display or parent frame. Neither do they allow to specify a position that does not lie within the edges of the display or parent frame. The frame parameters left and top (see section Position Parameters) allow to do that, but may still fail to provide good results for the initial or a new frame.

This function has no effect on text terminal frames.

Variable: move-frame-functions

This hook specifies the functions that are run when an Emacs frame is moved (assigned a new position) by the window-system or window manager. The functions are run with one argument, the frame that moved. For a child frame (see section Child Frames), the functions are run only when the position of the frame changes in relation to that of its parent frame.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.4 Frame Size

The canonical way to specify the size of a frame from within Emacs is by specifying its text size—a tuple of the width and height of the frame’s text area (see section Frame Layout). It can be measured either in pixels or in terms of the frame’s canonical character size (see section Frame Font).

For frames with an internal menu or tool bar, the frame’s native height cannot be told exactly before the frame has been actually drawn. This means that in general you cannot use the native size to specify the initial size of a frame. As soon as you know the native size of a visible frame, you can calculate its outer size (see section Frame Layout) by adding in the remaining components from the return value of frame-geometry. For invisible frames or for frames that have yet to be created, however, the outer size can only be estimated. This also means that calculating an exact initial position of a frame specified via offsets from the right or bottom edge of the screen (see section Frame Position) is impossible.

The text size of any frame can be set and retrieved with the help of the height and width frame parameters (see section Size Parameters). The text size of the initial frame can be also set with the help of an X-style geometry specification. See Command Line Arguments for Emacs Invocation in The GNU Emacs Manual. Below we list some functions to access and set the size of an existing, visible frame, by default the selected one.

Function: frame-height &optional frame
Function: frame-width &optional frame

These functions return the height and width of the text area of frame, measured in units of the default font height and width of frame (see section Frame Font). These functions are plain shorthands for writing (frame-parameter frame 'height) and (frame-parameter frame 'width).

If the text area of frame measured in pixels is not a multiple of its default font size, the values returned by these functions are rounded down to the number of characters of the default font that fully fit into the text area.

The functions following next return the pixel widths and heights of the native, outer and inner frame and the text area (see section Frame Layout) of a given frame. For a text terminal, the results are in characters rather than pixels.

Function: frame-outer-width &optional frame
Function: frame-outer-height &optional frame

These functions return the outer width and height of frame in pixels.

Function: frame-native-height &optional frame
Function: frame-native-width &optional frame

These functions return the native width and height of frame in pixels.

Function: frame-inner-width &optional frame
Function: frame-inner-height &optional frame

These functions return the inner width and height of frame in pixels.

Function: frame-text-width &optional frame
Function: frame-text-height &optional frame

These functions return the width and height of the text area of frame in pixels.

On window systems that support it, Emacs tries by default to make the text size of a frame measured in pixels a multiple of the frame’s character size. This, however, usually means that a frame can be resized only in character size increments when dragging its external borders. It also may break attempts to truly maximize the frame or making it “fullheight” or “fullwidth” (see section Size Parameters) leaving some empty space below and/or on the right of the frame. The following option may help in that case.

User Option: frame-resize-pixelwise

If this option is nil (the default), a frame’s text pixel size is usually rounded to a multiple of the current values of that frame’s frame-char-height and frame-char-width whenever the frame is resized. If this is non-nil, no rounding occurs, hence frame sizes can increase/decrease by one pixel.

Setting this variable usually causes the next resize operation to pass the corresponding size hints to the window manager. This means that this variable should be set only in a user’s initial file; applications should never bind it temporarily.

The precise meaning of a value of nil for this option depends on the toolkit used. Dragging the external border with the mouse is done character-wise provided the window manager is willing to process the corresponding size hints. Calling set-frame-size (see below) with arguments that do not specify the frame size as an integer multiple of its character size, however, may: be ignored, cause a rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows).

With some window managers you may have to set this to non-nil in order to make a frame appear truly maximized or full-screen.

Function: set-frame-size frame width height &optional pixelwise

This function sets the size of the text area of frame, measured in terms of the canonical height and width of a character on frame (see section Frame Font).

The optional argument pixelwise non-nil means to measure the new width and height in units of pixels instead. Note that if frame-resize-pixelwise is nil, some toolkits may refuse to truly honor the request if it does not increase/decrease the frame size to a multiple of its character size.

Function: set-frame-height frame height &optional pretend pixelwise

This function resizes the text area of frame to a height of height lines. The sizes of existing windows in frame are altered proportionally to fit.

If pretend is non-nil, then Emacs displays height lines of output in frame, but does not change its value for the actual height of the frame. This is only useful on text terminals. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame height directly does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on text terminals.

The optional fourth argument pixelwise non-nil means that frame should be height pixels high. Note that if frame-resize-pixelwise is nil, some window managers may refuse to truly honor the request if it does not increase/decrease the frame height to a multiple of its character height.

Function: set-frame-width frame width &optional pretend pixelwise

This function sets the width of the text area of frame, measured in characters. The argument pretend has the same meaning as in set-frame-height.

The optional fourth argument pixelwise non-nil means that frame should be width pixels wide. Note that if frame-resize-pixelwise is nil, some window managers may refuse to fully honor the request if it does not increase/decrease the frame width to a multiple of its character width.

None of these three functions will make a frame smaller than needed to display all of its windows together with their scroll bars, fringes, margins, dividers, mode and header lines. This contrasts with requests by the window manager triggered, for example, by dragging the external border of a frame with the mouse. Such requests are always honored by clipping, if necessary, portions that cannot be displayed at the right, bottom corner of the frame. The parameters min-width and min-height (see section Size Parameters) can be used to obtain a similar behavior when changing the frame size from within Emacs.

The abnormal hook window-size-change-functions (@pxref{Window Hooks}) tracks all changes of the inner size of a frame including those induced by request of the window-system or window manager. To rule out false positives that might occur when changing only the sizes of a frame’s windows without actually changing the size of the inner frame, use the following function.

Function: frame-size-changed-p &optional frame

This function returns non-nil when the inner width or height of frame has changed since window-size-change-functions was run the last time for frame. It always returns nil immediately after running window-size-change-functions for frame.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.5 Implied Frame Resizing

By default, Emacs tries to keep the number of lines and columns of a frame’s text area unaltered when, for example, adding or removing the menu bar, changing the default font or setting the width of the frame’s scroll bars. This means, however, that in such case Emacs must ask the window manager to resize the outer frame in order to accommodate the size change. Note that wrapping a menu or tool bar usually does not resize the frame’s outer size, hence this will alter the number of displayed lines.

Occasionally, such implied frame resizing may be unwanted, for example, when the frame is maximized or made full-screen (where it’s turned off by default). In other cases you can disable implied resizing with the following option:

User Option: frame-inhibit-implied-resize

If this option is nil, changing font, menu bar, tool bar, internal borders, fringes or scroll bars of a specific frame may implicitly resize the frame’s display area in order to preserve the number of columns or lines the frame displays. If this option is non-nil, no implied resizing is done.

The value of this option can be also a list of frame parameters. In that case, implied resizing is inhibited when changing a parameter that appears in this list. The frame parameters currently handled by this option are: font, font-backend, internal-border-width, menu-bar-lines and tool-bar-lines.

Changing any of the scroll-bar-width, scroll-bar-height, vertical-scroll-bars, horizontal-scroll-bars, left-fringe and right-fringe frame parameters is handled as if the frame contained just one live window. This means, for example, that removing vertical scroll bars on a frame containing several side by side windows will shrink the outer frame width by the width of one scroll bar provided this option is nil and keep it unchanged if this option is either t or a list containing vertical-scroll-bars.

The default value is '(tool-bar-lines) for Lucid, Motif and MS-Windows (which means that adding/removing a tool bar there does not change the outer frame height), nil on all other window systems including GTK+ (which means that changing any of the parameters listed above may change the size of the outer frame), and t otherwise (which means the outer frame size never changes implicitly when there’s no window system support).

Note that when a frame is not large enough to accommodate a change of any of the parameters listed above, Emacs may try to enlarge the frame even if this option is non-nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 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 mostly for the sake of graphical displays. Most frame parameters have no effect when applied to a frame on a text terminal; only the height, width, name, title, menu-bar-lines, buffer-list and buffer-predicate parameters do something special. If the terminal supports colors, the parameters foreground-color, background-color, background-mode and display-type are also meaningful. If the terminal supports frame transparency, the parameter alpha is also meaningful.

By default, frame parameters are saved and restored by the desktop library functions (@pxref{Desktop Save Mode}) when the variable desktop-restore-frames is non-nil. It’s the responsibility of applications that their parameters are included in frameset-persistent-filter-alist to avoid that they get meaningless or even harmful values in restored sessions.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.1 Access to Frame Parameters

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

Function: frame-parameter frame parameter

This function returns the value of the parameter parameter (a symbol) of frame. If frame is nil, it returns the selected frame’s parameter. If frame has no setting for parameter, this function returns nil.

Function: frame-parameters &optional frame

The function frame-parameters returns an alist listing all the parameters of frame and their values. If frame is nil or omitted, this returns the selected frame’s parameters

Function: modify-frame-parameters frame alist

This function alters the 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. If frame is nil, it defaults to the selected frame.

Some parameters are only meaningful for frames on certain kinds of display (see section Frames). If alist includes parameters that are not meaningful for the frame’s display, this function will change its value in the frame’s parameter list, but will otherwise ignore it.

When alist specifies more than one parameter whose value can affect the new size of frame, the final size of the frame may differ according to the toolkit used. For example, specifying that a frame should from now on have a menu and/or tool bar instead of none and simultaneously specifying the new height of the frame will inevitably lead to a recalculation of the frame’s height. Conceptually, in such case, this function will try to have the explicit height specification prevail. It cannot be excluded, however, that the addition (or removal) of the menu or tool bar, when eventually performed by the toolkit, will defeat this intention.

Sometimes, binding frame-inhibit-implied-resize (see section Implied Frame Resizing) to a non-nil value around calls to this function may fix the problem sketched here. Sometimes, however, exactly such binding may be hit by the problem.

Function: set-frame-parameter frame parm value

This function sets the frame parameter parm to the specified value. If frame is nil, it defaults to the selected frame.

Function: modify-all-frames-parameters alist

This function alters the frame parameters of all existing frames according to alist, then modifies default-frame-alist (and, if necessary, initial-frame-alist) to apply the same parameter values to frames that will be created henceforth.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.2 Initial Frame Parameters

You can specify the parameters for the initial startup frame by setting initial-frame-alist in your init file (@pxref{Init File}).

User Option: initial-frame-alist

This variable’s value is an alist of parameter values used when creating the initial frame. You can set this variable to specify the appearance of the initial frame without altering subsequent frames. Each element has the form:

(parameter . value)

Emacs creates the initial frame before it reads your init file. After reading that file, Emacs checks initial-frame-alist, and applies the parameter 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 effect before the frame is created. See X Resources in The GNU Emacs Manual.

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 parameters in default-frame-alist to override the X resources for subsequent frames; then, to prevent these from affecting the initial frame, specify the same parameters in initial-frame-alist with values that match the X resources.

If these parameters include (minibuffer . nil), that indicates that the initial frame should have no minibuffer. In this case, Emacs creates a separate minibuffer-only frame as well.

User Option: minibuffer-frame-alist

This variable’s value is an alist of parameter values used when creating an initial minibuffer-only frame (i.e., the minibuffer-only frame that Emacs creates if initial-frame-alist specifies a frame with no minibuffer).

User Option: default-frame-alist

This is an alist specifying default values of frame parameters for all Emacs frames—the first frame, and subsequent frames. When using the X Window System, you can get the same results by means of X resources in many cases.

Setting this variable does not affect existing frames. Furthermore, functions that display a buffer in a separate frame may override the default parameters by supplying their own parameters.

If you invoke Emacs with command-line options that specify frame appearance, those options take effect by adding elements to either initial-frame-alist or default-frame-alist. Options which affect just the initial frame, such as ‘--geometry’ and ‘--maximized’, add to initial-frame-alist; the others add to default-frame-alist. see Command Line Arguments for Emacs Invocation in The GNU Emacs Manual.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3 Window Frame Parameters

Just what parameters a frame has depends on what display mechanism it uses. This section describes the parameters that have special meanings on some or all kinds of terminals. Of these, name, title, height, width, buffer-list and buffer-predicate provide meaningful information in terminal frames, and tty-color-mode is meaningful only for frames on text terminals.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.1 Basic Parameters

These frame parameters give the most basic information about the frame. title and name are meaningful on all terminals.

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. See section Multiple Terminals, for more details about display names.

display-type

This parameter describes the range of possible colors that can be used in this frame. Its value is color, grayscale or mono.

title

If a frame has a non-nil title, it appears in the window system’s title bar at the top of the frame, and also in the mode line of windows in that frame if mode-line-frame-identification uses ‘%F’ (@pxref{%-Constructs}). This is normally the case when Emacs is not using a window system, and can only display one frame at a time. See section Frame Titles.

name

The name of the frame. The frame name serves as a default for the frame title, if the title parameter is unspecified or nil. If you don’t specify a name, Emacs sets the frame name automatically (see section Frame Titles).

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.

explicit-name

If the frame name was specified explicitly when the frame was created, this parameter will be that name. If the frame wasn’t explicitly named, this parameter will be nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.2 Position Parameters

Parameters describing the X- and Y-offsets of a frame are always measured in pixels. For a normal, non-child frame they specify the frame’s outer position (see section Frame Geometry) relative to its display’s origin. For a child frame (see section Child Frames) they specify the frame’s outer position relative to the native position of the frame’s parent frame. (Note that none of these parameters is meaningful on TTY frames.)

left

The position, in pixels, of the left outer edge of the frame with respect to the left edge of the frame’s display or parent frame. It can be specified in one of the following ways.

an integer

A positive integer always relates the left edge of the frame to the left edge of its display or parent frame. A negative integer relates the right frame edge to the right edge of the display or parent frame.

(+ pos)

This specifies the position of the left frame edge relative to the left edge of its display or parent frame. The integer pos may be positive or negative; a negative value specifies a position outside the screen or parent frame or on a monitor other than the primary one (for multi-monitor displays).

(- pos)

This specifies the position of the right frame edge relative to the right edge of the display or parent frame. The integer pos may be positive or negative; a negative value specifies a position outside the screen or parent frame or on a monitor other than the primary one (for multi-monitor displays).

a floating-point value

A floating-point value in the range 0.0 to 1.0 specifies the left edge’s offset via the left position ratio of the frame—the ratio of the left edge of its outer frame to the width of the frame’s workarea (see section Multiple Terminals) or its parent’s native frame (see section Child Frames) minus the width of the outer frame. Thus, a left position ratio of 0.0 flushes a frame to the left, a ratio of 0.5 centers it and a ratio of 1.0 flushes it to the right of its display or parent frame. Similarly, the top position ratio of a frame is the ratio of the frame’s top position to the height of its workarea or parent frame minus the height of the frame.

Emacs will try to keep the position ratios of a child frame unaltered if that frame has a non-nil keep-ratio parameter (see section Frame Interaction Parameters) and its parent frame is resized.

Since the outer size of a frame (see section Frame Geometry) is usually unavailable before a frame has been made visible, it is generally not advisable to use floating-point values when creating decorated frames. Floating-point values are more suited for ensuring that an (undecorated) child frame is positioned nicely within the area of its parent frame.

Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as in the following example:

(modify-frame-parameters
  nil '((user-position . t) (left . (+ -4))))

In general, it is not a good idea to position a frame relative to the right or bottom edge of its display. Positioning the initial or a new frame is either not accurate (because the size of the outer frame is not yet fully known before the frame has been made visible) or will cause additional flicker (if the frame has to be repositioned after becoming visible).

Note also, that positions specified relative to the right/bottom edge of a display, workarea or parent frame as well as floating-point offsets are stored internally as integer offsets relative to the left/top edge of the display, workarea or parent frame edge. They are also returned as such by functions like frame-parameters and restored as such by the desktop saving routines.

top

The screen position of the top (or bottom) edge, in pixels, with respect to the top (or bottom) edge of the display or parent frame. It works just like left, except vertically instead of horizontally.

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 when the frame is iconified, if the window manager supports this feature. If you specify a value for this parameter, then you must also specify a value for icon-top and vice versa.

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 when the frame is iconified, if the window manager supports this feature.

user-position

When you create a frame and specify its screen position with the left and top parameters, use this parameter to say whether the specified position was user-specified (explicitly requested in some way by a human user) or merely program-specified (chosen by a program). A non-nil value says the position was user-specified.

Window managers generally heed user-specified positions, and some heed program-specified positions too. But many ignore program-specified positions, placing the window in a default fashion or letting the user place it with the mouse. Some window managers, including twm, let the user specify whether to obey program-specified positions or ignore them.

When you call make-frame, you should specify a non-nil value for this parameter if the values of the left and top parameters represent the user’s stated preference; otherwise, use nil.

z-group

This parameter specifies a relative position of the frame’s window-system window in the stacking (Z-) order of the frame’s display.

If this is above, the frame’s window-system window is displayed above all other window-system windows that do not have the above property set. If this is nil, the frame’s window is displayed below all windows that have the above property set and above all windows that have the below property set. If this is below, the frame’s window is displayed below all windows that do not have the below property set.

To position the frame above or below a specific other frame use the function frame-restack (see section Raising, Lowering and Restacking Frames).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.3 Size Parameters

Frame parameters usually specify frame sizes in character units. On graphical displays, the default face determines the actual pixel sizes of these character units (@pxref{Face Attributes}).

width

This parameter specifies the width of the frame. It can be specified as in the following ways:

an integer

A positive integer specifies the width of the frame’s text area (see section Frame Geometry) in characters.

a cons cell

If this is a cons cell with the symbol text-pixels in its CAR, the CDR of that cell specifies the width of the frame’s text area in pixels.

a floating-point value

A floating-point number between 0.0 and 1.0 can be used to specify the width of a frame via its width ratio—the ratio of its outer width (see section Frame Geometry) to the width of the frame’s workarea (see section Multiple Terminals) or its parent frame’s (see section Child Frames) native frame. Thus, a value of 0.5 makes the frame occupy half of the width of its workarea or parent frame, a value of 1.0 the full width. Similarly, the height ratio of a frame is the ratio of its outer height to the height of its workarea or its parent’s native frame.

Emacs will try to keep the width and height ratio of a child frame unaltered if that frame has a non-nil keep-ratio parameter (see section Frame Interaction Parameters) and its parent frame is resized.

Since the outer size of a frame is usually unavailable before a frame has been made visible, it is generally not advisable to use floating-point values when creating decorated frames. Floating-point values are more suited to ensure that a child frame always fits within the area of its parent frame as, for example, when customizing display-buffer-alist (@pxref{Choosing Window}) via display-buffer-in-child-frame.

Regardless of how this parameter was specified, functions reporting the value of this parameter like frame-parameters always report the width of the frame’s text area in characters as an integer rounded, if necessary, to a multiple of the frame’s default character width. That value is also used by the desktop saving routines.

height

This parameter specifies the height of the frame. It works just like width, except vertically instead of horizontally.

user-size

This does for the size parameters height and width what the user-position parameter (see section user-position) does for the position parameters top and left.

min-width

This parameter specifies the minimum native width (see section Frame Geometry) of the frame, in characters. Normally, the functions that establish a frame’s initial width or resize a frame horizontally make sure that all the frame’s windows, vertical scroll bars, fringes, margins and vertical dividers can be displayed. This parameter, if non-nil allows to make a frame narrower than that with the consequence that any components that do not fit will be clipped by the window manager.

min-height

This parameter specifies the minimum native height (see section Frame Geometry) of the frame, in characters. Normally, the functions that establish a frame’s initial size or resize a frame make sure that all the frame’s windows, horizontal scroll bars and dividers, mode and header lines, the echo area and the internal menu and tool bar can be displayed. This parameter, if non-nil allows to make a frame smaller than that with the consequence that any components that do not fit will be clipped by the window manager.

fullscreen

This parameter specifies whether to maximize the frame’s width, height or both. Its value can be fullwidth, fullheight, fullboth, or maximized. A fullwidth frame is as wide as possible, a fullheight frame is as tall as possible, and a fullboth frame is both as wide and as tall as possible. A maximized frame is like a “fullboth” frame, except that it usually keeps its title bar and the buttons for resizing and closing the frame. Also, maximized frames typically avoid hiding any task bar or panels displayed on the desktop. A “fullboth” frame, on the other hand, usually omits the title bar and occupies the entire available screen space.

Full-height and full-width frames are more similar to maximized frames in this regard. However, these typically display an external border which might be absent with maximized frames. Hence the heights of maximized and full-height frames and the widths of maximized and full-width frames often differ by a few pixels.

With some window managers you may have to customize the variable frame-resize-pixelwise (see section Frame Size) in order to make a frame truly appear maximized or full-screen. Moreover, some window managers might not support smooth transition between the various full-screen or maximization states. Customizing the variable x-frame-normalize-before-maximize can help to overcome that.

Full-screen on macOS hides both the tool-bar and the menu-bar, however both will be displayed if the mouse pointer is moved to the top of the screen.

fullscreen-restore

This parameter specifies the desired fullscreen state of the frame after invoking the toggle-frame-fullscreen command (see Frame Commands in The GNU Emacs Manual) in the “fullboth” state. Normally this parameter is installed automatically by that command when toggling the state to fullboth. If, however, you start Emacs in the “fullboth” state, you have to specify the desired behavior in your initial file as, for example

(setq default-frame-alist
    '((fullscreen . fullboth)
      (fullscreen-restore . fullheight)))

This will give a new frame full height after typing in it <F11> for the first time.

fit-frame-to-buffer-margins

This parameter allows to override the value of the option fit-frame-to-buffer-margins when fitting this frame to the buffer of its root window with fit-frame-to-buffer (@pxref{Resizing Windows}).

fit-frame-to-buffer-sizes

This parameter allows to override the value of the option fit-frame-to-buffer-sizes when fitting this frame to the buffer of its root window with fit-frame-to-buffer (@pxref{Resizing Windows}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.4 Layout Parameters

These frame parameters enable or disable various parts of the frame, or control their sizes.

border-width

The width in pixels of the frame’s outer border (see section Frame Geometry).

internal-border-width

The width in pixels of the frame’s internal border (see section Frame Geometry).

vertical-scroll-bars

Whether the frame has scroll bars (@pxref{Scroll Bars}) for vertical scrolling, and which side of the frame they should be on. The possible values are left, right, and nil for no scroll bars.

horizontal-scroll-bars

Whether the frame has scroll bars for horizontal scrolling (t and bottom mean yes, nil means no).

scroll-bar-width

The width of vertical scroll bars, in pixels, or nil meaning to use the default width.

scroll-bar-height

The height of horizontal scroll bars, in pixels, or nil meaning to use the default height.

left-fringe
right-fringe

The default width of the left and right fringes of windows in this frame (@pxref{Fringes}). If either of these is zero, that effectively removes the corresponding fringe.

When you use frame-parameter to query the value of either of these two frame parameters, the return value is always an integer. When using set-frame-parameter, passing a nil value imposes an actual default value of 8 pixels.

right-divider-width

The width (thickness) reserved for the right divider (@pxref{Window Dividers}) of any window on the frame, in pixels. A value of zero means to not draw right dividers.

bottom-divider-width

The width (thickness) reserved for the bottom divider (@pxref{Window Dividers}) of any window on the frame, in pixels. A value of zero means to not draw bottom dividers.

menu-bar-lines

The number of lines to allocate at the top of the frame for a menu bar (@pxref{Menu Bar}). The default is one if Menu Bar mode is enabled and zero otherwise. See Menu Bars in The GNU Emacs Manual. For an external menu bar (see section Frame Layout), this value remains unchanged even when the menu bar wraps to two or more lines. In that case, the menu-bar-size value returned by frame-geometry (see section Frame Geometry) allows to derive whether the menu bar actually occupies one or more lines.

tool-bar-lines

The number of lines to use for the tool bar (@pxref{Tool Bar}). The default is one if Tool Bar mode is enabled and zero otherwise. See Tool Bars in The GNU Emacs Manual. This value may change whenever the tool bar wraps (see section Frame Layout).

tool-bar-position

The position of the tool bar when Emacs was built with GTK+. Its value can be one of top, bottom left, right. The default is top.

line-spacing

Additional space to leave below each text line, in pixels (a positive integer). @xref{Line Height}, for more information.

no-special-glyphs

If this is non-nil, it suppresses the display of any truncation and continuation glyphs (@pxref{Truncation}) for all buffers displayed by this frame. This is useful to eliminate such glyphs when fitting a frame to its buffer via fit-frame-to-buffer (@pxref{Resizing Windows}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.5 Buffer Parameters

These frame parameters, meaningful on all kinds of terminals, deal with which buffers have been, or should, be displayed in 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 frame uses that minibuffer.

This parameter takes effect when the frame is created. If specified as nil, Emacs will try to set it to the minibuffer window of default-minibuffer-frame (see section Minibuffers and Frames). For an existing frame, this parameter can be used exclusively to specify another minibuffer window. It is not allowed to change it from a minibuffer window to t and vice-versa, or from t to nil. If the parameter specifies a minibuffer window already, setting it to nil has no effect.

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 argument, a buffer, once for each buffer; if the predicate returns a non-nil value, it considers that buffer.

buffer-list

A list of buffers that have been selected in this frame, ordered most-recently-selected first.

unsplittable

If non-nil, this frame’s window is never split automatically.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.6 Frame Interaction Parameters

These parameters supply forms of interactions between different frames.

parent-frame

If non-nil, this means that this frame is a child frame (see section Child Frames), and this parameter specifies its parent frame. If nil, this means that this frame is a normal, top-level frame.

delete-before

If non-nil, this parameter specifies another frame whose deletion will automatically trigger the deletion of this frame. See section Deleting Frames.

mouse-wheel-frame

If non-nil, this parameter specifies the frame whose windows will be scrolled whenever the mouse wheel is scrolled with the mouse pointer hovering over this frame, see Mouse Commands in The GNU Emacs Manual.

no-other-frame

If this is non-nil, then this frame is not eligible as candidate for the functions next-frame, previous-frame (see section Finding All Frames) and other-frame, see Frame Commands in The GNU Emacs Manual.

auto-hide-function

When this parameter specifies a function, that function will be called instead of the function specified by the variable frame-auto-hide-function when quitting the frame’s only window (@pxref{Quitting Windows}) and there are other frames left.

minibuffer-exit

When this parameter is non-nil, Emacs will by default make this frame invisible whenever the minibuffer (@pxref{Minibuffers}) is exited. Alternatively, it can specify the functions iconify-frame and delete-frame. This parameter is useful to make a child frame disappear automatically (similar to how Emacs deals with a window) when exiting the minibuffer.

keep-ratio

This parameter is currently meaningful for child frames (see section Child Frames) only. If it is non-nil, then Emacs will try to keep the frame’s size (width and height) ratios (see section Size Parameters) as well as its left and right position ratios (see section Position Parameters) unaltered whenever its parent frame is resized.

If the value of this parameter is nil, the frame’s position and size remain unaltered when the parent frame is resized, so the position and size ratios may change. If the value of this parameter is t, Emacs will try to preserve the frame’s size and position ratios, hence the frame’s size and position relative to its parent frame may change.

More individual control is possible by using a cons cell: In that case the frame’s width ratio is preserved if the CAR of the cell is either t or width-only. The height ratio is preserved if the CAR of the cell is either t or height-only. The left position ratio is preserved if the CDR of the cell is either t or left-only. The top position ratio is preserved if the CDR of the cell is either t or top-only.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.7 Mouse Dragging Parameters

The parameters described below provide support for resizing a frame by dragging its internal borders with the mouse. They also allow moving a frame with the mouse by dragging the header line of its topmost or the mode line of its bottommost window.

These parameters are mostly useful for child frames (see section Child Frames) that come without window manager decorations. If necessary, they can be used for undecorated top-level frames as well.

drag-internal-border

If non-nil, the frame can be resized by dragging its internal borders, if present, with the mouse.

drag-with-header-line

If non-nil, the frame can be moved with the mouse by dragging the header line of its topmost window.

drag-with-mode-line

If non-nil, the frame can be moved with the mouse by dragging the mode line of its bottommost window. Note that such a frame is not allowed to have its own minibuffer window.

snap-width

A frame that is moved with the mouse will “snap” at the border(s) of the display or its parent frame whenever it is dragged as near to such an edge as the number of pixels specified by this parameter.

top-visible

If this parameter is a number, the top edge of the frame never appears above the top edge of its display or parent frame. Moreover, as many pixels of the frame as specified by that number will remain visible when the frame is moved against any of the remaining edges of its display or parent frame. Setting this parameter is useful to guard against dragging a child frame with a non-nil drag-with-header-line parameter completely out of the area of its parent frame.

bottom-visible

If this parameter is a number, the bottom edge of the frame never appears below the bottom edge of its display or parent frame. Moreover, as many pixels of the frame as specified by that number will remain visible when the frame is moved against any of the remaining edges of its display or parent frame. Setting this parameter is useful to guard against dragging a child frame with a non-nil drag-with-mode-line parameter completely out of the area of its parent frame.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.8 Window Management Parameters

The following frame parameters control various aspects of the frame’s interaction with the window manager or window system. They have no effect on text terminals.

visibility

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

auto-raise

If non-nil, Emacs automatically raises the frame when it is selected. Some window managers do not allow this.

auto-lower

If non-nil, Emacs automatically lowers the frame when it is deselected. Some window managers do not allow this.

icon-type

The type of icon to use for this frame. If the value is a string, that specifies a file containing a bitmap to use; nil specifies no icon (in which case the window manager decides what to show); any other non-nil value specifies the default Emacs icon.

icon-name

The name to use in the icon for this frame, when and if the icon appears. If this is nil, the frame’s title is used.

window-id

The ID number which the graphical display uses for this frame. Emacs assigns this parameter when the frame is created; changing the parameter has no effect on the actual ID number.

outer-window-id

The ID number of the outermost window-system window in which the frame exists. As with window-id, changing this parameter has no actual effect.

wait-for-wm

If non-nil, tell Xt to wait for the window manager to confirm geometry changes. Some window managers, including versions of Fvwm2 and KDE, fail to confirm, so Xt hangs. Set this to nil to prevent hanging with those window managers.

sticky

If non-nil, the frame is visible on all virtual desktops on systems with virtual desktops.

inhibit-double-buffering

If non-nil, the frame is drawn to the screen without double buffering. Emacs normally attempts to use double buffering, where available, to reduce flicker. Set this property if you experience display bugs or pine for that retro, flicker-y feeling.

skip-taskbar

If non-nil, this tells the window manager to remove the frame’s icon from the taskbar associated with the frame’s display and inhibit switching to the frame’s window via the combination Alt-<TAB>. On MS-Windows, iconifying such a frame will "roll in" its window-system window at the bottom of the desktop. Some window managers may not honor this parameter.

no-focus-on-map

If non-nil, this means that the frame does not want to receive input focus when it is mapped (see section Visibility of Frames). Some window managers may not honor this parameter.

no-accept-focus

If non-nil, this means that the frame does not want to receive input focus via explicit mouse clicks or when moving the mouse into it either via focus-follows-mouse (see section Input Focus) or mouse-autoselect-window (@pxref{Mouse Window Auto-selection}). This may have the unwanted side-effect that a user cannot scroll a non-selected frame with the mouse. Some window managers may not honor this parameter.

undecorated

If non-nil, this frame’s window-system window is drawn without decorations, like the title, minimize/maximize boxes and external borders. This usually means that the window cannot be dragged, resized, iconified, maximized or deleted with the mouse. If nil, the frame’s window is usually drawn with all the elements listed above unless their display has been suspended via window manager settings.

Under X, Emacs uses the Motif window manager hints to turn off decorations. Some window managers may not honor these hints.

NS builds consider the tool bar to be a decoration, and therefore hide it on an undecorated frame.

override-redirect

If non-nil, this means that this is an override redirect frame—a frame not handled by window managers under X. Override redirect frames have no window manager decorations, can be positioned and resized only via Emacs’ positioning and resizing functions and are usually drawn on top of all other frames. Setting this parameter has no effect on MS-Windows.

ns-appearance

Only available on macOS, if set to dark draw this frame’s window-system window using the “vibrant dark” theme, otherwise use the system default. The “vibrant dark” theme can be used to set the toolbar and scrollbars to a dark appearance when using an Emacs theme with a dark background.

ns-transparent-titlebar

Only available on macOS, if non-nil, set the titlebar and toolbar to be transparent. This effectively sets the background color of both to match the Emacs background color.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.9 Cursor Parameters

This frame parameter controls the way the cursor looks.

cursor-type

How to display the cursor. Legitimate values are:

box

Display a filled box. (This is the default.)

hollow

Display a hollow box.

nil

Don’t display a cursor.

bar

Display a vertical bar between characters.

(bar . width)

Display a vertical bar width pixels wide between characters.

hbar

Display a horizontal bar.

(hbar . height)

Display a horizontal bar height pixels high.

The cursor-type frame parameter may be overridden by the variables cursor-type and cursor-in-non-selected-windows:

User Option: cursor-type

This buffer-local variable controls how the cursor looks in a selected window showing the buffer. If its value is t, that means to use the cursor specified by the cursor-type frame parameter. Otherwise, the value should be one of the cursor types listed above, and it overrides the cursor-type frame parameter.

User Option: cursor-in-non-selected-windows

This buffer-local variable controls how the cursor looks in a window that is not selected. It supports the same values as the cursor-type frame parameter; also, nil means don’t display a cursor in nonselected windows, and t (the default) means use a standard modification of the usual cursor type (solid box becomes hollow box, and bar becomes a narrower bar).

User Option: x-stretch-cursor

This variable controls the width of the block cursor displayed on extra-wide glyphs such as a tab or a stretch of white space. By default, the block cursor is only as wide as the font’s default character, and will not cover all of the width of the glyph under it if that glyph is extra-wide. A non-nil value of this variable means draw the block cursor as wide as the glyph under it. The default value is nil.

This variable has no effect on text-mode frames, since the text-mode cursor is drawn by the terminal out of Emacs’s control.

User Option: blink-cursor-alist

This variable specifies how to blink the cursor. Each element has the form (on-state . off-state). Whenever the cursor type equals on-state (comparing using equal), the corresponding off-state specifies what the cursor looks like when it blinks off. Both on-state and off-state should be suitable values for the cursor-type frame parameter.

There are various defaults for how to blink each type of cursor, if the type is not mentioned as an on-state here. Changes in this variable do not take effect immediately, only when you specify the cursor-type frame parameter.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3.10 Font and Color Parameters

These frame parameters control the use of fonts and colors.

font-backend

A list of symbols, specifying the font backends to use for drawing fonts in the frame, in order of priority. On X, there are currently two available font backends: x (the X core font driver) and xft (the Xft font driver). On MS-Windows, there are currently two available font backends: gdi and uniscribe (see Windows Fonts in The GNU Emacs Manual). On other systems, there is only one available font backend, so it does not make sense to modify this frame parameter.

background-mode

This parameter is either dark or light, according to whether the background color is a light one or a dark one.

tty-color-mode

This parameter overrides the terminal’s color support as given by the system’s terminal capabilities database in that this parameter’s value specifies the color mode to use on a text terminal. The value can be either a symbol or a number. A number specifies the number of colors to use (and, indirectly, what commands to issue to produce each color). For example, (tty-color-mode . 8) specifies use of the ANSI escape sequences for 8 standard text colors. A value of -1 turns off color support.

If the parameter’s value is a symbol, it specifies a number through the value of tty-color-mode-alist, and the associated number is used instead.

screen-gamma

If this is a number, Emacs performs gamma correction which adjusts the brightness of all colors. The value should be the screen gamma of your display.

Usual PC monitors have a screen gamma of 2.2, so color values in Emacs, and in X windows generally, are calibrated to display properly on a monitor with that gamma value. If you specify 2.2 for screen-gamma, that means no correction is needed. Other values request correction, designed to make the corrected colors appear on your screen the way they would have appeared without correction on an ordinary monitor with a gamma value of 2.2.

If your monitor displays colors too light, you should specify a screen-gamma value smaller than 2.2. This requests correction that makes colors darker. A screen gamma value of 1.5 may give good results for LCD color displays.

alpha

This parameter specifies the opacity of the frame, on graphical displays that support variable opacity. It should be an integer between 0 and 100, where 0 means completely transparent and 100 means completely opaque. It can also have a nil value, which tells Emacs not to set the frame opacity (leaving it to the window manager).

To prevent the frame from disappearing completely from view, the variable frame-alpha-lower-limit defines a lower opacity limit. If the value of the frame parameter is less than the value of this variable, Emacs uses the latter. By default, frame-alpha-lower-limit is 20.

The alpha frame parameter can also be a cons cell (active . inactive), where active is the opacity of the frame when it is selected, and inactive is the opacity when it is not selected.

Some window systems do not support the alpha parameter for child frames (see section Child Frames).

The following frame parameters are semi-obsolete in that they are automatically equivalent to particular face attributes of particular faces (see Standard Faces in The Emacs Manual):

font

The name of the font for displaying text in the frame. This is a string, either a valid font name for your system or the name of an Emacs fontset (@pxref{Fontsets}). It is equivalent to the font attribute of the default face.

foreground-color

The color to use for the image of a character. It is equivalent to the :foreground attribute of the default face.

background-color

The color to use for the background of characters. It is equivalent to the :background attribute of the default face.

mouse-color

The color for the mouse pointer. It is equivalent to the :background attribute of the mouse face.

cursor-color

The color for the cursor that shows point. It is equivalent to the :background attribute of the cursor face.

border-color

The color for the border of the frame. It is equivalent to the :background attribute of the border face.

scroll-bar-foreground

If non-nil, the color for the foreground of scroll bars. It is equivalent to the :foreground attribute of the scroll-bar face.

scroll-bar-background

If non-nil, the color for the background of scroll bars. It is equivalent to the :background attribute of the scroll-bar face.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.4 Geometry

Here’s how to examine the data in an X-style window geometry specification:

Function: x-parse-geometry geom

The function x-parse-geometry converts a standard X window geometry string to an alist that 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.

For the size parameters, the value must be an integer. The position parameter names left and top are not totally accurate, because some values indicate the position of the right or bottom edges instead. The value possibilities for the position parameters are: an integer, a list (+ pos), or a list (- pos); as previously described (see section Position Parameters).

Here is an example:

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Terminal Parameters

Each terminal has a list of associated parameters. These terminal parameters are mostly a convenient way of storage for terminal-local variables, but some terminal parameters have a special meaning.

This section describes functions to read and change the parameter values of a terminal. They all accept as their argument either a terminal or a frame; the latter means use that frame’s terminal. An argument of nil means the selected frame’s terminal.

Function: terminal-parameters &optional terminal

This function returns an alist listing all the parameters of terminal and their values.

Function: terminal-parameter terminal parameter

This function returns the value of the parameter parameter (a symbol) of terminal. If terminal has no setting for parameter, this function returns nil.

Function: set-terminal-parameter terminal parameter value

This function sets the parameter parameter of terminal to the specified value, and returns the previous value of that parameter.

Here’s a list of a few terminal parameters that have a special meaning:

background-mode

The classification of the terminal’s background color, either light or dark.

normal-erase-is-backspace

Value is either 1 or 0, depending on whether normal-erase-is-backspace-mode is turned on or off on this terminal. See DEL Does Not Delete in The Emacs Manual.

terminal-initted

After the terminal is initialized, this is set to the terminal-specific initialization function.

tty-mode-set-strings

When present, a list of strings containing escape sequences that Emacs will output while configuring a tty for rendering. Emacs emits these strings only when configuring a terminal: if you want to enable a mode on a terminal that is already active (for example, while in tty-setup-hook), explicitly output the necessary escape sequence using send-string-to-terminal in addition to adding the sequence to tty-mode-set-strings.

tty-mode-reset-strings

When present, a list of strings that undo the effects of the strings in tty-mode-set-strings. Emacs emits these strings when exiting, deleting a terminal, or suspending itself.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Frame Titles

Every frame has a name parameter; this serves as the default for the frame title which window systems typically display at the top of the frame. You can specify a name explicitly by setting the name frame property.

Normally you don’t specify the name explicitly, and Emacs computes the frame name automatically based on a template stored in the variable frame-title-format. Emacs recomputes the name each time the frame is redisplayed.

Variable: frame-title-format

This variable specifies how to compute a name for a frame when you have not explicitly specified one. The variable’s value is actually a mode line construct, just like mode-line-format, except that the ‘%c’, ‘%C’, and ‘%l’ constructs are ignored. @xref{Mode Line Data}.

Variable: icon-title-format

This variable specifies how to compute the name for an iconified frame, when you have not explicitly specified the frame title. This title appears in the icon itself.

Variable: multiple-frames

This variable is set automatically by Emacs. Its value is t when there are two or more frames (not counting minibuffer-only frames or invisible frames). The default value of frame-title-format uses multiple-frames so as to put the buffer name in the frame title only when there is more than one frame.

The value of this variable is not guaranteed to be accurate except while processing frame-title-format or icon-title-format.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Deleting Frames

A live frame is one that has not been deleted. When a frame is deleted, it is removed from its terminal display, although it may continue to exist as a Lisp object until there are no more references to it.

Command: delete-frame &optional frame force

This function deletes the frame frame. The argument frame must specify a live frame (see below) and defaults to the selected frame.

It first deletes any child frame of frame (see section Child Frames) and any frame whose delete-before frame parameter (see section Frame Interaction Parameters) specifies frame. All such deletions are performed recursively; so this step makes sure that no other frames with frame as their ancestor will exist. Then, unless frame specifies a tooltip, this function runs the hook delete-frame-functions (each function getting one argument, frame) before actually killing the frame.

Note that a frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (see section Minibuffers and Frames). Normally, you cannot delete a frame if all other frames are invisible, but if force is non-nil, then you are allowed to do so.

Function: frame-live-p frame

This function returns non-nil if the frame frame has not been deleted. The possible non-nil return values are like those of framep. See section Frames.

Some window managers provide a command to delete a window. These work by sending a special message to the program that operates the window. When Emacs gets one of these commands, it generates a delete-frame event, whose normal definition is a command that calls the function delete-frame. @xref{Misc Events}.

Command: delete-other-frames &optional frame

This command deletes all frames on frame’s terminal, except frame. If frame uses another frame’s minibuffer, that minibuffer frame is left untouched. The argument frame must specify a live frame and defaults to the selected frame. Internally, this command works by calling delete-frame with force nil for all frames that shall be deleted.

This function does not delete any of frame’s child frames (see section Child Frames). If frame is a child frame, it deletes frame’s siblings only.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 Finding All Frames

Function: frame-list

This function returns a list of all the live frames, i.e., those that have not been deleted. It is analogous to buffer-list for buffers, and includes frames on all terminals. 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 section Visibility of Frames. Frames on text terminals always count as visible, even though only the selected one is actually displayed.

Function: frame-list-z-order &optional display

This function returns a list of Emacs’ frames, in Z (stacking) order (see section Raising, Lowering and Restacking Frames). The optional argument display specifies which display to poll. display should be either a frame or a display name (a string). If omitted or nil, that stands for the selected frame’s display. It returns nil if display contains no Emacs frame.

Frames are listed from topmost (first) to bottommost (last). As a special case, if display is non-nil and specifies a live frame, it returns the child frames of that frame in Z (stacking) order.

This function is not meaningful on text terminals.

Function: next-frame &optional frame minibuf

This function lets you cycle conveniently through all the frames on a specific terminal from an arbitrary starting point. It returns the frame following frame, in the list of all live frames, on frame’s terminal. The argument frame must specify a live frame and defaults to the selected frame. It never returns a frame whose no-other-frame parameter (see section Frame Interaction Parameters) is non-nil.

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

nil

Exclude minibuffer-only frames.

visible

Consider all visible frames.

0

Consider all visible or iconified frames.

a window

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

anything else

Consider all frames.

Function: previous-frame &optional frame minibuf

Like next-frame, but cycles through all frames in the opposite direction.

See also next-window and previous-window, in @ref{Cyclic Window Ordering}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9 Minibuffers and Frames

Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. You can get that window with the function minibuffer-window (@pxref{Minibuffer Windows}).

However, you can also create a frame without a minibuffer. Such a frame must use the minibuffer window of some other frame. That other frame will serve as surrogate minibuffer frame for this frame and cannot be deleted via delete-frame (see section Deleting Frames) as long as this frame is live.

When you create the frame, you can explicitly specify its minibuffer window (in some other frame) with the minibuffer frame parameter (see section Buffer Parameters). 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 that 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 section Raising, Lowering and Restacking Frames.

Variable: default-minibuffer-frame

This variable specifies the frame to use for the minibuffer window, by default. It does not affect existing frames. It is always local to the current terminal and cannot be buffer-local. See section Multiple Terminals.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.10 Input Focus

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

When Emacs displays its frames on several terminals (see section Multiple Terminals), each terminal has its own selected frame. But only one of these is the selected frame: it’s the frame that belongs to the terminal from which the most recent input came. That is, when Emacs runs a command that came from a certain terminal, the selected frame is the one of that terminal. Since Emacs runs only a single command at any given time, it needs to consider only one selected frame at a time; this frame is what we call the selected frame in this manual. The display on which the selected frame is shown is the selected frame’s display.

Function: selected-frame

This function returns the selected frame.

Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to shift the focus to various window objects. Either way, Emacs automatically keeps track of which frame has the focus. To explicitly switch to a different frame from a Lisp function, call select-frame-set-input-focus.

Lisp programs can also switch frames temporarily by calling the function select-frame. This does not alter the window system’s concept of focus; rather, it escapes from the window manager’s control until that control is somehow reasserted.

When using a text terminal, only one frame can be displayed at a time on the terminal, so after a call to select-frame, the next redisplay actually displays the newly selected frame. This frame remains selected until a subsequent call to select-frame. Each frame on a text terminal has a number which appears in the mode line before the buffer name (@pxref{Mode Line Variables}).

Function: select-frame-set-input-focus frame &optional norecord

This function selects frame, raises it (should it happen to be obscured by other frames) and tries to give it the X server’s focus. On a text terminal, the next redisplay displays the new frame on the entire terminal screen. The optional argument norecord has the same meaning as for select-frame (see below). The return value of this function is not significant.

Ideally, the function described next should focus a frame without also raising it above other frames. Unfortunately, many window-systems or window managers may refuse to comply.

Function: x-focus-frame frame &optional noactivate

This function gives frame the focus of the X server without necessarily raising it. frame nil means use the selected frame. Under X, the optional argument noactivate, if non-nil, means to avoid making frame’s window-system window the “active” window which should insist a bit more on avoiding to raise frame above other frames.

On MS-Windows the noactivate argument has no effect. However, if frame is a child frame (see section Child Frames), this function usually focuses frame without raising it above other child frames.

If there is no window system support, this function does nothing.

Command: select-frame frame &optional norecord

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. (If you are using a window system, the previously selected frame may be restored as the selected frame after return to the command loop, because it still may have the window system’s input focus.)

The specified frame becomes the selected frame, and its terminal becomes the selected terminal. This function then calls select-window as a subroutine, passing the window selected within frame as its first argument and norecord as its second argument (hence, if norecord is non-nil, this avoids changing the order of recently selected windows and the buffer list). @xref{Selecting Windows}.

This function returns frame, or nil if frame has been deleted.

In general, you should never use select-frame in a way that could switch to a different terminal without switching back when you’re done.

Emacs cooperates with the window system by arranging to select frames as the server and window manager request. It does so by generating a special kind of input event, called a focus event, when appropriate. The command loop handles a focus event by calling handle-switch-frame. @xref{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 &optional focus-frame

This function redirects focus from frame to focus-frame. This means that focus-frame will receive subsequent keystrokes and events 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 omitted or 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 that 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.

Variable: focus-in-hook

This is a normal hook run when an Emacs frame gains input focus. The frame gaining focus is selected when this hook is run.

Variable: focus-out-hook

This is a normal hook run when an Emacs frame has lost input focus and no other Emacs frame has gained input focus instead.

User Option: focus-follows-mouse

This option informs Emacs whether and how the window manager transfers focus when you move the mouse pointer into a frame. It can have three meaningful values:

nil

The default value nil should be used when your window manager follows a “click-to-focus” policy where you have to click the mouse inside of a frame in order for that frame to gain focus.

t

The value t should be used when your window manager has the focus automatically follow the position of the mouse pointer but a frame that gains focus is not raised automatically and may even remain occluded by other window-system windows.

auto-raise

The value auto-raise should be used when your window manager has the focus automatically follow the position of the mouse pointer and a frame that gains focus is raised automatically.

If this option is non-nil, Emacs moves the mouse pointer to the frame selected by select-frame-set-input-focus. That function is used by a number of commands like, for example, other-frame and pop-to-buffer.

The distinction between the values t and auto-raise is not needed for “normal” frames because the window manager usually takes care of raising them. It is useful to automatically raise child frames via mouse-autoselect-window (@pxref{Mouse Window Auto-selection}).

Note that this option does not distinguish “sloppy” focus (where the frame that previously had focus retains focus as long as the mouse pointer does not move into another window manager window) from “strict” focus (where a frame immediately loses focus when it’s left by the mouse pointer). Neither does it recognize whether your window manager supports delayed focusing or auto-raising where you can explicitly specify the time until a new frame gets focus or is auto-raised.

You can supply a “focus follows mouse” policy for individual Emacs windows by customizing the variable mouse-autoselect-window (@pxref{Mouse Window Auto-selection}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.11 Visibility of Frames

A frame on a graphical display may be visible, invisible, or iconified. If it is visible, its contents are displayed in the usual manner. If it is iconified, its contents are not displayed, but there is a little icon somewhere to bring the frame back into view (some window managers refer to this state as minimized rather than iconified, but from Emacs’ point of view they are the same thing). If a frame is invisible, it is not displayed at all.

The concept of visibility is strongly related to that of (un-)mapped frames. A frame (or, more precisely, its window-system window) is and becomes mapped when it is displayed for the first time and whenever it changes its state of visibility from iconified or invisible to visible. Conversely, a frame is and becomes unmapped whenever it changes its status from visible to iconified or invisible.

Visibility is meaningless on text terminals, since only the selected frame is actually displayed in any case.

Function: frame-visible-p frame

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

On a text terminal, all frames are considered visible for the purposes of this function, even though only one frame is displayed. See section Raising, Lowering and Restacking Frames.

Command: iconify-frame &optional frame

This function iconifies frame frame. If you omit frame, it iconifies the selected frame. This usually makes all child frames of frame (and their descendants) invisible (see section Child Frames).

Command: make-frame-visible &optional frame

This function makes frame frame visible. If you omit frame, it makes the selected frame visible. This does not raise the frame, but you can do that with raise-frame if you wish (see section Raising, Lowering and Restacking Frames).

Making a frame visible usually makes all its child frames (and their descendants) visible as well (see section Child Frames).

Command: make-frame-invisible &optional frame force

This function makes frame frame invisible. If you omit frame, it makes the selected frame invisible. Usually, this makes all child frames of frame (and their descendants) invisible too (see section Child Frames).

Unless force is non-nil, this function refuses to make frame invisible if all other frames are invisible.

The visibility status of a frame is also available as a frame parameter. You can read or change it as such. See section Window Management Parameters. The user can also iconify and deiconify frames with the window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. @xref{Misc Events}.

Function: x-double-buffered-p &optional frame

This function returns non-nil if frame is currently being rendered with double buffering. frame defaults to the selected frame.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12 Raising, Lowering and Restacking Frames

Most window systems use a desktop metaphor. Part of this metaphor is the idea that system-level windows (representing, e.g., Emacs frames) are stacked in a notional third dimension perpendicular to the screen surface. The order induced by stacking is total and usually referred to as stacking (or Z-) order. Where the areas of two windows overlap, the one higher up in that order will (partially) cover the one underneath.

You can raise a frame to the top of that order or lower a frame to its bottom by using the functions raise-frame and lower-frame. You can restack a frame directly above or below another frame using the function frame-restack.

Note that all functions described below will respect the adherence of frames (and all other window-system windows) to their respective z-group (see section Position Parameters). For example, you usually cannot lower a frame below that of the desktop window and you cannot raise a frame whose z-group parameter is nil above the window-system’s taskbar or tooltip window.

Command: raise-frame &optional frame

This function raises frame frame (default, the selected frame) above all other frames belonging to the same or a lower z-group as frame. If frame is invisible or iconified, this makes it visible. If frame is a child frame (see section Child Frames), this raises frame above all other child frames of its parent.

Command: lower-frame &optional frame

This function lowers frame frame (default, the selected frame) below all other frames belonging to the same or a higher z-group as frame. If frame is a child frame (see section Child Frames), this lowers frame below all other child frames of its parent.

Function: frame-restack frame1 frame2 &optional above

This function restacks frame1 below frame2. This implies that if both frames are visible and their display areas overlap, frame2 will (partially) obscure frame1. If the optional third argument above is non-nil, this function restacks frame1 above frame2. This means that if both frames are visible and their display areas overlap, frame1 will (partially) obscure frame2.

Technically, this function may be thought of as an atomic action performed in two steps: The first step removes frame1’s window-system window from the display. The second step reinserts frame1’s window into the display below (above if above is true) that of frame2. Hence the position of frame2 in its display’s Z (stacking) order relative to all other frames excluding frame1 remains unaltered.

Some window managers may refuse to restack windows.

Note that the effect of restacking will only hold as long as neither of the involved frames is iconified or made invisible. You can use the z-group (see section Position Parameters) frame parameter to add a frame to a group of frames permanently shown above or below other frames. As long as a frame belongs to one of these groups, restacking it will only affect its relative stacking position within that group. The effect of restacking frames belonging to different z-groups is undefined. You can list frames in their current stacking order with the function frame-list-z-order (see section Finding All Frames).

User Option: minibuffer-auto-raise

If this is non-nil, activation of the minibuffer raises the frame that the minibuffer window is in.

On window systems, you can also enable auto-raising (on frame selection) or auto-lowering (on frame deselection) using frame parameters. See section Window Management Parameters.

The concept of raising and lowering frames also applies to text terminal frames. On each text terminal, only the top frame is displayed at any one time.

Function: tty-top-frame &optional terminal

This function returns the top frame on terminal. terminal should be a terminal object, a frame (meaning that frame’s terminal), or nil (meaning the selected frame’s terminal). If it does not refer to a text terminal, the return value is nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13 Frame Configurations

A frame configuration records the current arrangement of frames, all their properties, and the window configuration of each one. (@xref{Window Configurations}.)

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 in configuration. However, this function does not restore deleted frames.

Ordinarily, this function deletes all existing frames not listed in configuration. But if nodelete is non-nil, the unwanted frames are iconified instead.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.14 Child Frames

Child frames are objects halfway between windows (@pxref{Windows}) and “normal” frames. Like windows, they are attached to an owning frame. Unlike windows, they may overlap each other—changing the size or position of one child frame does not change the size or position of any of its sibling child frames.

By design, operations to make or modify child frames are implemented with the help of frame parameters (see section Frame Parameters) without any specialized functions or customizable variables. Note that child frames are meaningful on graphical terminals only.

To create a new child frame or to convert a normal frame into a child frame, set that frame’s parent-frame parameter (see section Frame Interaction Parameters) to that of an already existing frame. The frame specified by that parameter will then be the frame’s parent frame as long as the parameter is not changed or reset. Technically, this makes the child frame’s window-system window a child window of the parent frame’s window-system window.

The parent-frame parameter can be changed at any time. Setting it to another frame reparents the child frame. Setting it to another child frame makes the frame a nested child frame. Setting it to nil restores the frame’s status as a top-level frame—a frame whose window-system window is a child of its display’s root window.

Since child frames can be arbitrarily nested, a frame can be both a child and a parent frame. Also, the relative roles of child and parent frame may be reversed at any time (though it’s usually a good idea to keep the size of a child frame sufficiently smaller than that of its parent). An error will be signaled for the attempt to make a frame an ancestor of itself.

Most window-systems clip a child frame at the native edges (see section Frame Geometry) of its parent frame—everything outside these edges is usually invisible. A child frame’s left and top parameters specify a position relative to the top-left corner of its parent’s native frame. When the parent frame is resized, this position remains conceptually unaltered.

NS builds do not clip child frames at the parent frame’s edges, allowing them to be positioned so they do not obscure the parent frame while still being visible themselves.

Usually, moving a parent frame moves along all its child frames and their descendants as well, keeping their relative positions unaltered. Note that the hook move-frame-functions (see section Frame Position) is run for a child frame only when the position of the child frame relative to its parent frame changes.

When a parent frame is resized, its child frames conceptually retain their previous sizes and their positions relative to the left upper corner of the parent. This means that a child frame may become (partially) invisible when its parent frame shrinks. The parameter keep-ratio (see section Frame Interaction Parameters) can be used to resize and reposition a child frame proportionally whenever its parent frame is resized. This may avoid obscuring parts of a frame when its parent frame is shrunk.

A visible child frame always appears on top of its parent frame thus obscuring parts of it, except on NS builds where it may be positioned beneath the parent. This is comparable to the window-system window of a top-level frame which also always appears on top of its parent window—the desktop’s root window. When a parent frame is iconified or made invisible (see section Visibility of Frames), its child frames are made invisible. When a parent frame is deiconified or made visible, its child frames are made visible. When a parent frame is about to be deleted (see section Deleting Frames), its child frames are recursively deleted before it.

Whether a child frame can have a menu or tool bar is window-system or window manager dependent. Most window-systems explicitly disallow menus bars for child frames. It seems advisable to disable both, menu and tool bars, via the frame’s initial parameters settings.

Usually, child frames do not exhibit window manager decorations like a title bar or external borders (see section Frame Geometry). When the child frame does not show a menu or tool bar, any other of the frame’s borders (see section Layout Parameters) can be used instead of the external borders.

In particular, under X (but not when building with GTK+), the frame’s outer border can be used. On MS-Windows, specifying a non-zero outer border width will show a one-pixel wide external border. Under all window-systems, the internal border can be used. In either case, it’s advisable to disable a child frame’s window manager decorations with the undecorated frame parameter (see section Window Management Parameters).

To resize or move an undecorated child frame with the mouse, special frame parameters (see section Mouse Dragging Parameters) have to be used. The internal border of a child frame, if present, can be used to resize the frame with the mouse, provided that frame has a non-nil drag-internal-border parameter. If set, the snap-width parameter indicates the number of pixels where the frame snaps at the respective edge or corner of its parent frame.

There are two ways to drag an entire child frame with the mouse: The drag-with-mode-line parameter, if non-nil, allows to drag a frame without minibuffer window (@pxref{Minibuffer Windows}) via the mode line area of its bottommost window. The drag-with-header-line parameter, if non-nil, allows to drag the frame via the header line area of its topmost window.

In order to give a child frame a draggable header or mode line, the window parameters mode-line-format and header-line-format are handy (@pxref{Window Parameters}). These allow to remove an unwanted mode line (when drag-with-header-line is chosen) and to remove mouse-sensitive areas which might interfere with frame dragging.

To avoid that dragging moves a frame completely out of its parent’s native frame, something which might happen when the mouse cursor overshoots and makes the frame difficult to retrieve once the mouse button has been released, it is advisable to set the frame’s top-visible or bottom-visible parameter correspondingly.

The top-visible parameter specifies the number of pixels at the top of the frame that always remain visible within the parent’s native frame during dragging and should be set when specifying a non-nil drag-with-header-line parameter. The bottom-visible parameter specifies the number of pixels at the bottom of the frame that always remain visible within the parent’s native frame during dragging and should be preferred when specifying a non-nil drag-with-mode-line parameter.

When a child frame is used for displaying a buffer via display-buffer-in-child-frame (@pxref{Display Action Functions}), the frame’s auto-hide-function parameter (see section Frame Interaction Parameters) can be set to a function, in order to appropriately deal with the frame when the window displaying the buffer shall be quit.

When a child frame is used during minibuffer interaction, for example, to display completions in a separate window, the minibuffer-exit parameter (see section Frame Interaction Parameters) is useful in order to deal with the frame when the minibuffer is exited.

The behavior of child frames deviates from that of top-level frames in a number of other ways as well. Here we sketch a few of them:

The following two functions can be useful when working with child and parent frames:

Function: frame-parent &optional frame

This function returns the parent frame of frame. The parent frame of frame is the Emacs frame whose window-system window is the parent window of frame’s window-system window. If such a frame exists, frame is considered a child frame of that frame.

This function returns nil if frame has no parent frame.

Function: frame-ancestor-p ancestor descendant

This functions returns non-nil if ancestor is an ancestor of descendant. ancestor is an ancestor of descendant when it is either descendant’s parent frame or it is an ancestor of descendant’s parent frame. Both, ancestor and descendant must specify live frames.

Note also the function window-largest-empty-rectangle (@pxref{Coordinates and Windows}) which can be used to inscribe a child frame in the largest empty area of an existing window. This can be useful to avoid that a child frame obscures any text shown in that window.

Customizing the following option can be useful to tweak the behavior of iconify-frame for child frames.

User Option: iconify-child-frame

This option tells Emacs how to proceed when it is asked to iconify a child frame. If it is nil, iconify-frame will do nothing when invoked on a child frame. If it is iconify-top-level, Emacs will try to iconify the top-level frame that is the ancestor of this child frame instead. If it is make-invisible, Emacs will try to make this child frame invisible instead of iconifying it.

Any other value means to try iconifying the child frame. Since such an attempt may not be honored by all window managers and can even lead to making the child frame unresponsive to user actions, the default is to iconify the top level frame instead.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.15 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…

This special form executes body, with generation of mouse motion events enabled. Typically, body would use read-event to read the motion events and modify the display accordingly. @xref{Motion Events}, for the format of mouse motion events.

The value of track-mouse is that of the last form in body. You should design body to return when it sees the up-event that indicates the release of the button, or whatever kind of event means it is time to stop tracking.

The track-mouse form causes Emacs to generate mouse motion events by binding the variable track-mouse to a non-nil value. If that variable has the special value dragging, it additionally instructs the display engine to refrain from changing the shape of the mouse pointer. This is desirable in Lisp programs that require mouse dragging across large portions of Emacs display, which might otherwise cause the mouse pointer to change its shape according to the display portion it hovers on (see section Pointer Shape). Therefore, Lisp programs that need the mouse pointer to retain its original shape during dragging should bind track-mouse to the value dragging at the beginning of their 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.

In many cases, you can avoid the need to track the mouse by using the mouse-face text property (@pxref{Special Properties}). That works at a much lower level and runs more smoothly than Lisp-level mouse tracking.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16 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 (possibly rounded) position in multiples of the default character size of frame (see section Frame Font) relative to the native position of frame (see section Frame Geometry).

Variable: mouse-position-function

If non-nil, the value of this variable is a function for mouse-position to call. mouse-position calls this function just before returning, with its normal return value as the sole argument, and it returns whatever this function returns to it.

This abnormal hook exists for the benefit of packages like ‘xt-mouse.el’ that need to do mouse handling at the Lisp level.

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 multiples of the default character size of frame (see section Frame Font) relative to the native position of frame (see section Frame Geometry).

The resulting mouse position is constrained to the native frame of frame. If frame is not visible, this function does nothing. The return value is not significant.

Function: mouse-pixel-position

This function is like mouse-position except that it returns coordinates in units of pixels rather than units of characters.

Function: set-mouse-pixel-position frame x y

This function warps the mouse like set-mouse-position except that x and y are in units of pixels rather than units of characters.

The resulting mouse position is not constrained to the native frame of frame. If frame is not visible, this function does nothing. The return value is not significant.

On a graphical terminal the following two functions allow the absolute position of the mouse cursor to be retrieved and set.

Function: mouse-absolute-pixel-position

This function returns a cons cell (x . y) of the coordinates of the mouse cursor position in pixels, relative to a position (0, 0) of the selected frame’s display.

Function: set-mouse-absolute-pixel-position x y

This function moves the mouse cursor to the position (x, y). The coordinates x and y are interpreted in pixels relative to a position (0, 0) of the selected frame’s display.

The following function can tell whether the mouse cursor is currently visible on a frame:

Function: frame-pointer-visible-p &optional frame

This predicate function returns non-nil if the mouse pointer displayed on frame is visible; otherwise it returns nil. frame omitted or nil means the selected frame. This is useful when make-pointer-invisible is set to t: it allows you to know if the pointer has been hidden. See Mouse Avoidance in The Emacs Manual.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17 Pop-Up Menus

A Lisp program can pop up a menu so that the user can choose an alternative with the mouse. On a text terminal, if the mouse is not available, the user can choose an alternative using the keyboard motion keys—C-n, C-p, or up- and down-arrow keys.

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 top left corner of 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 coordinates, measured in pixels, counting from the top left corner of window. window may be a window or a frame.

If position is t, it means to use the current mouse position (or the top-left corner of the frame if the mouse is not available on a text terminal). 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 (@pxref{Menu Keymaps}). In this case, the return value is the list of events corresponding to the user’s choice. This list has more than one element if the choice occurred in a submenu. (Note that x-popup-menu does not actually execute the command bound to that sequence of events.) On text terminals and toolkits that support menu titles, the title is taken from the prompt string of menu if menu is a keymap, or from the prompt string of the first keymap in menu if it is a list of keymaps (@pxref{Defining Menus}).

Alternatively, menu can have the following form:

(title pane1 pane2...)

where each pane is a list of form

(title item1 item2...)

Each item should be a cons cell, (line . value), where line is a string and value is the value to return if that line is chosen. Unlike in a menu keymap, a nil value does not make the menu item non-selectable. Alternatively, each item can be a string rather than a cons cell; this makes a non-selectable menu item.

If the user gets rid of the menu without making a valid choice, for instance by clicking the mouse away from a valid choice or by typing C-g, then this normally results in a quit and x-popup-menu does not return. But if position is a mouse button event (indicating that the user invoked the menu with the mouse) then no quit occurs and x-popup-menu returns nil.

Usage note: Don’t use x-popup-menu to display a menu if you could do the job with a prefix key defined with a menu keymap. 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.

The menu bar mechanism, which lets you switch between submenus by moving the mouse, cannot look within the definition of a command to see that it calls x-popup-menu. Therefore, if you try to implement a submenu using x-popup-menu, it cannot work with the menu bar in an integrated fashion. This is why all menu bar submenus are implemented with menu keymaps within the parent menu, and never with x-popup-menu. @xref{Menu Bar}.

If you want a menu bar submenu to have contents that vary, you should still use a menu keymap to implement it. To make the contents vary, add a hook function to menu-bar-update-hook to update the contents of the menu keymap as necessary.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.18 Dialog Boxes

A dialog box is a variant of a pop-up menu—it looks a little different, it always appears in the center of a frame, and it has just one level and one or more buttons. The main use of dialog boxes is for asking questions that the user can answer with “yes”, “no”, and a few other alternatives. With a single button, they can also force the user to acknowledge important information. 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 &optional header

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.

The return value is value from the chosen alternative.

As for x-popup-menu, an element of the list may be just a string instead of a cons cell (string . value). That makes a box that cannot be selected.

If nil appears in the list, it separates the left-hand items from the right-hand items; items that precede the nil appear on the left, and items that follow the nil appear on the right. If you don’t include a nil in the list, then approximately half the items appear on each side.

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 or the individual window don’t matter; only the frame matters.

If header is non-nil, the frame title for the box is ‘Information’, otherwise it is ‘Question’. The former is used for message-box (@pxref{message-box}). (On text terminals, the box title is not displayed.)

In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the frame.

If the user gets rid of the dialog box without making a valid choice, for instance using the window manager, then this produces a quit and x-popup-dialog does not return.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.19 Pointer Shape

You can specify the mouse pointer style for particular text or images using the pointer text property, and for images with the :pointer and :map image properties. The values you can use in these properties are text (or nil), arrow, hand, vdrag, hdrag, modeline, and hourglass. text stands for the usual mouse pointer style used over text.

Over void parts of the window (parts that do not correspond to any of the buffer contents), the mouse pointer usually uses the arrow style, but you can specify a different style (one of those above) by setting void-text-area-pointer.

User Option: void-text-area-pointer

This variable specifies the mouse pointer style for void text areas. These include the areas after the end of a line or below the last line in the buffer. The default is to use the arrow (non-text) pointer style.

When using X, you can specify what the text pointer style really looks like by setting the variable x-pointer-shape.

Variable: x-pointer-shape

This variable specifies the pointer shape to use ordinarily in the Emacs frame, for the text pointer style.

Variable: x-sensitive-text-pointer-shape

This variable specifies the pointer shape to use when the mouse is over mouse-sensitive text.

These variables affect newly created frames. They do not normally affect existing frames; however, if you set the mouse color of a frame, that also installs the current value of those two variables. See section Font and Color Parameters.

The values you can use, to specify either of these pointer shapes, are defined in the file ‘lisp/term/x-win.el’. Use M-x apropos <RET> x-pointer <RET> to see a list of them.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.20 Window System Selections

In window systems, such as X, data can be transferred between different applications by means of selections. X defines an arbitrary number of selection types, each of which can store its own data; however, only three are commonly used: the clipboard, primary selection, and secondary selection. Other window systems support only the clipboard. See Cut and Paste in The GNU Emacs Manual, for Emacs commands that make use of these selections. This section documents the low-level functions for reading and setting window-system selections.

Command: gui-set-selection type data

This function sets a window-system selection. It takes two arguments: a selection type type, and the value to assign to it, data.

type should be a symbol; it is usually one of PRIMARY, SECONDARY or CLIPBOARD. These are symbols with upper-case names, in accord with X Window System conventions. If type is nil, that stands for PRIMARY.

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 argument data may also be a vector of valid non-vector selection values.

This function returns data.

Function: gui-get-selection &optional type data-type

This function accesses selections set up by Emacs or by other programs. 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 program into Lisp data. Meaningful values include TEXT, STRING, UTF8_STRING, TARGETS, LENGTH, DELETE, FILE_NAME, CHARACTER_POSITION, NAME, LINE_NUMBER, COLUMN_NUMBER, OWNER_OS, HOST_NAME, USER, CLASS, ATOM, and INTEGER. (These are symbols with upper-case names in accord with X conventions.) The default for data-type is STRING. Window systems other than X usually support only a small subset of these types, in addition to STRING.

User Option: selection-coding-system

This variable specifies the coding system to use when reading and writing selections or the clipboard. @xref{Coding Systems}. The default is compound-text-with-extensions, which converts to the text representation that X11 normally uses.

When Emacs runs on MS-Windows, it does not implement X selections in general, but it does support the clipboard. gui-get-selection and gui-set-selection on MS-Windows support the text data type only; if the clipboard holds other types of data, Emacs treats the clipboard as empty. The supported data type is STRING.

For backward compatibility, there are obsolete aliases x-get-selection and x-set-selection, which were the names of gui-get-selection and gui-set-selection before Emacs 25.1.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.21 Drag and Drop

When a user drags something from another application over Emacs, that other application expects Emacs to tell it if Emacs can handle the data that is dragged. The variable x-dnd-test-function is used by Emacs to determine what to reply. The default value is x-dnd-default-test-function which accepts drops if the type of the data to be dropped is present in x-dnd-known-types. You can customize x-dnd-test-function and/or x-dnd-known-types if you want Emacs to accept or reject drops based on some other criteria.

If you want to change the way Emacs handles drop of different types or add a new type, customize x-dnd-types-alist. This requires detailed knowledge of what types other applications use for drag and drop.

When an URL is dropped on Emacs it may be a file, but it may also be another URL type (ftp, http, etc.). Emacs first checks dnd-protocol-alist to determine what to do with the URL. If there is no match there and if browse-url-browser-function is an alist, Emacs looks for a match there. If no match is found the text for the URL is inserted. If you want to alter Emacs behavior, you can customize these variables.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.22 Color Names

A color name is text (usually in a string) that specifies a color. Symbolic names such as ‘black’, ‘white’, ‘red’, etc., are allowed; use M-x list-colors-display to see a list of defined names. You can also specify colors numerically in forms such as ‘#rgb’ and ‘RGB:r/g/b’, where r specifies the red level, g specifies the green level, and b specifies the blue level. You can use either one, two, three, or four hex digits for r; then you must use the same number of hex digits for all g and b as well, making either 3, 6, 9 or 12 hex digits in all. (See the documentation of the X Window System for more details about numerical RGB specification of colors.)

These functions provide a way to determine which color names are valid, and what they look like. In some cases, the value depends on the selected frame, as described below; see Input Focus, for the meaning of the term “selected frame”.

To read user input of color names with completion, use read-color (@pxref{High-Level Completion, read-color}).

Function: color-defined-p color &optional frame

This function reports whether a color name is meaningful. It returns t if so; otherwise, nil. The argument frame says which frame’s display to ask about; if frame is omitted or nil, the selected frame is used.

Note that this does not tell you whether the display you are using really supports that color. When using X, you can ask for any defined color on any kind of display, and you will get some result—typically, the closest it can do. To determine whether a frame can really display a certain color, use color-supported-p (see below).

This function used to be called x-color-defined-p, and that name is still supported as an alias.

Function: defined-colors &optional frame

This function returns a list of the color names that are defined and supported on frame frame (default, the selected frame). If frame does not support colors, the value is nil.

This function used to be called x-defined-colors, and that name is still supported as an alias.

Function: color-supported-p color &optional frame background-p

This returns t if frame can really display the color color (or at least something close to it). If frame is omitted or nil, the question applies to the selected frame.

Some terminals support a different set of colors for foreground and background. If background-p is non-nil, that means you are asking whether color can be used as a background; otherwise you are asking whether it can be used as a foreground.

The argument color must be a valid color name.

Function: color-gray-p color &optional frame

This returns t if color is a shade of gray, as defined on frame’s display. If frame is omitted or nil, the question applies to the selected frame. If color is not a valid color name, this function returns nil.

Function: color-values color &optional frame

This function returns a value that describes what color should ideally look like on frame. If color is defined, the value is a list of three integers, which give the amount of red, the amount of green, and the amount of blue. Each integer ranges in principle from 0 to 65535, but some displays may not use the full range. This three-element list is called the rgb values of the color.

If color is not defined, the value is nil.

(color-values "black")
     ⇒ (0 0 0)
(color-values "white")
     ⇒ (65280 65280 65280)
(color-values "red")
     ⇒ (65280 0 0)
(color-values "pink")
     ⇒ (65280 49152 51968)
(color-values "hungry")
     ⇒ nil

The color values are returned for frame’s display. If frame is omitted or nil, the information is returned for the selected frame’s display. If the frame cannot display colors, the value is nil.

This function used to be called x-color-values, and that name is still supported as an alias.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.23 Text Terminal Colors

Text terminals usually support only a small number of colors, and the computer uses small integers to select colors on the terminal. This means that the computer cannot reliably tell what the selected color looks like; instead, you have to inform your application which small integers correspond to which colors. However, Emacs does know the standard set of colors and will try to use them automatically.

The functions described in this section control how terminal colors are used by Emacs.

Several of these functions use or return rgb values, described in Color Names.

These functions accept a display (either a frame or the name of a terminal) as an optional argument. We hope in the future to make Emacs support different colors on different text terminals; then this argument will specify which terminal to operate on (the default being the selected frame’s terminal; see section Input Focus). At present, though, the frame argument has no effect.

Function: tty-color-define name number &optional rgb frame

This function associates the color name name with color number number on the terminal.

The optional argument rgb, if specified, is an rgb value, a list of three numbers that specify what the color actually looks like. If you do not specify rgb, then this color cannot be used by tty-color-approximate to approximate other colors, because Emacs will not know what it looks like.

Function: tty-color-clear &optional frame

This function clears the table of defined colors for a text terminal.

Function: tty-color-alist &optional frame

This function returns an alist recording the known colors supported by a text terminal.

Each element has the form (name number . rgb) or (name number). Here, name is the color name, number is the number used to specify it to the terminal. If present, rgb is a list of three color values (for red, green, and blue) that says what the color actually looks like.

Function: tty-color-approximate rgb &optional frame

This function finds the closest color, among the known colors supported for display, to that described by the rgb value rgb (a list of color values). The return value is an element of tty-color-alist.

Function: tty-color-translate color &optional frame

This function finds the closest color to color among the known colors supported for display and returns its index (an integer). If the name color is not defined, the value is nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.24 X Resources

This section describes some of the functions and variables for querying and using X resources, or their equivalent on your operating system. See X Resources in The GNU Emacs Manual, for more information about X resources.

Function: x-get-resource attribute class &optional component subclass

The function x-get-resource retrieves a resource value from the X Window 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’ (where instance is the name under which Emacs was invoked), and using ‘Emacs.class’ 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.class.subclass’.

Variable: x-resource-class

This variable specifies the application name that x-get-resource should look up. The default value is "Emacs". You can examine X resources for other application names by binding this variable to some other string, around a call to x-get-resource.

Variable: x-resource-name

This variable specifies the instance name that x-get-resource should look up. The default value is the name Emacs was invoked with, or the value specified with the ‘-name’ or ‘-rn’ switches.

To illustrate some of the above, suppose that you have the line:

xterm.vt100.background: yellow

in your X resources file (whose name is usually ‘~/.Xdefaults’ or ‘~/.Xresources’). Then:

(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
  (x-get-resource "vt100.background" "VT100.Background"))
     ⇒ "yellow"
(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
  (x-get-resource "background" "VT100" "vt100" "Background"))
     ⇒ "yellow"
Variable: inhibit-x-resources

If this variable is non-nil, Emacs does not look up X resources, and X resources do not have any effect when creating new frames.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.25 Display Feature Testing

The functions in this section describe the basic capabilities of a particular display. Lisp programs can use them to adapt their behavior to what the display can do. For example, a program that ordinarily uses a popup menu could use the minibuffer if popup menus are not supported.

The optional argument display in these functions specifies which display to ask the question about. It can be a display name, a frame (which designates the display that frame is on), or nil (which refers to the selected frame’s display, see section Input Focus).

See section Color Names, Text Terminal Colors, for other functions to obtain information about displays.

Function: display-popup-menus-p &optional display

This function returns t if popup menus are supported on display, nil if not. Support for popup menus requires that the mouse be available, since the menu is popped up by clicking the mouse on some portion of the Emacs display.

Function: display-graphic-p &optional display

This function returns t if display is a graphic display capable of displaying several frames and several different fonts at once. This is true for displays that use a window system such as X, and false for text terminals.

Function: display-mouse-p &optional display

This function returns t if display has a mouse available, nil if not.

Function: display-color-p &optional display

This function returns t if the screen is a color screen. It used to be called x-display-color-p, and that name is still supported as an alias.

Function: display-grayscale-p &optional display

This function returns t if the screen can display shades of gray. (All color displays can do this.)

Function: display-supports-face-attributes-p attributes &optional display

This function returns non-nil if all the face attributes in attributes are supported (@pxref{Face Attributes}).

The definition of “supported” is somewhat heuristic, but basically means that a face containing all the attributes in attributes, when merged with the default face for display, can be represented in a way that’s

  1. different in appearance than the default face, and
  2. close in spirit to what the attributes specify, if not exact.

Point (2) implies that a :weight black attribute will be satisfied by any display that can display bold, as will :foreground "yellow" as long as some yellowish color can be displayed, but :slant italic will not be satisfied by the tty display code’s automatic substitution of a dim face for italic.

Function: display-selections-p &optional display

This function returns t if display supports selections. Windowed displays normally support selections, but they may also be supported in some other cases.

Function: display-images-p &optional display

This function returns t if display can display images. Windowed displays ought in principle to handle images, but some systems lack the support for that. On a display that does not support images, Emacs cannot display a tool bar.

Function: display-screens &optional display

This function returns the number of screens associated with the display.

Function: display-pixel-height &optional display

This function returns the height of the screen in pixels. On a character terminal, it gives the height in characters.

For graphical terminals, note that on multi-monitor setups this refers to the pixel height for all physical monitors associated with display. See section Multiple Terminals.

Function: display-pixel-width &optional display

This function returns the width of the screen in pixels. On a character terminal, it gives the width in characters.

For graphical terminals, note that on multi-monitor setups this refers to the pixel width for all physical monitors associated with display. See section Multiple Terminals.

Function: display-mm-height &optional display

This function returns the height of the screen in millimeters, or nil if Emacs cannot get that information.

For graphical terminals, note that on multi-monitor setups this refers to the height for all physical monitors associated with display. See section Multiple Terminals.

Function: display-mm-width &optional display

This function returns the width of the screen in millimeters, or nil if Emacs cannot get that information.

For graphical terminals, note that on multi-monitor setups this refers to the width for all physical monitors associated with display. See section Multiple Terminals.

User Option: display-mm-dimensions-alist

This variable allows the user to specify the dimensions of graphical displays returned by display-mm-height and display-mm-width in case the system provides incorrect values.

Function: display-backing-store &optional display

This function returns the backing store capability of the display. Backing store means recording the pixels of windows (and parts of windows) that are not exposed, so that when exposed they can be displayed very quickly.

Values can be the symbols always, when-mapped, or not-useful. The function can also return nil when the question is inapplicable to a certain kind of display.

Function: display-save-under &optional display

This function returns non-nil if the display supports the SaveUnder feature. That feature is used by pop-up windows to save the pixels they obscure, so that they can pop down quickly.

Function: display-planes &optional display

This function returns the number of planes the display supports. This is typically the number of bits per pixel. For a tty display, it is log to base two of the number of colors supported.

Function: display-visual-class &optional display

This function returns the visual class for the screen. The value is one of the symbols static-gray (a limited, unchangeable number of grays), gray-scale (a full range of grays), static-color (a limited, unchangeable number of colors), pseudo-color (a limited number of colors), true-color (a full range of colors), and direct-color (a full range of colors).

Function: display-color-cells &optional display

This function returns the number of color cells the screen supports.

These functions obtain additional information about the window system in use where Emacs shows the specified display. (Their names begin with x- for historical reasons.)

Function: x-server-version &optional display

This function returns the list of version numbers of the GUI window system running on display, such as the X server on GNU and Unix systems. The value is a list of three integers: the major and minor version numbers of the protocol, and the distributor-specific release number of the window system software itself. On GNU and Unix systems, these are normally the version of the X protocol and the distributor-specific release number of the X server software. On MS-Windows, this is the version of the Windows OS.

Function: x-server-vendor &optional display

This function returns the vendor that provided the window system software (as a string). On GNU and Unix systems this really means whoever distributes the X server. On MS-Windows this is the vendor ID string of the Windows OS (Microsoft).

When the developers of X labeled software distributors as “vendors”, they showed their false assumption that no system could ever be developed and distributed noncommercially.


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 28, 2018 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on May 28, 2018 using texi2html.