Next: Multiple Terminals, Up: Frames   [Contents][Index]

30.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 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. See 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 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 Multiple Terminals), the window manager might position the frame differently than specified by the positional parameters in parameters (see 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 Input Focus. The previously selected frame remains selected. On graphical terminals, however, the window system may select the new frame for its own reasons.

By default this function does not display the current buffer in the new frame if the buffer is hidden, that is, if its name starts with a space. In this case it will show another buffer—one that could be returned by the function other-buffer (see The Buffer List)—instead. However, if the variable expose-hidden-buffer is non-nil, this function will display the current buffer even if it is hidden.

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.

You can consult the frame parameters cloned-from and undeleted in your function to determine if a frame was cloned using clone-frame, or if it was undeleted using undelete-frame. See Frame Parameters.

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 Minibuffers and Frames), the functions will be run for both, the minibuffer-less and the minibuffer frame. Alternatively, you can add functions to these hooks in your “early init file” (see The Init File), in which case they will be in effect for the initial frame as well.

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.

User Option: server-after-make-frame-hook ¶

A normal hook run when the Emacs server starts using a client frame. When this hook is called, the client frame is the selected one. Note that, depending on how emacsclient was invoked (see Invoking emacsclient in The GNU Emacs Manual), this client frame could be a new frame created for the client, or it could be an existing frame that the server reused for handling the client commands. See Emacs Server in The GNU Emacs Manual.

Next: Frame Geometry, Previous: Creating Frames, Up: Frames   [Contents][Index]

30.2 Multiple Terminals ¶

Emacs represents each terminal as a terminal object data type (see 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:

• The name of the device used by the terminal (e.g., ‘:0.0’ or /dev/tty).
• The terminal and keyboard coding systems used on the terminal. See Terminal I/O Encoding.
• The kind of display associated with the terminal. This is the symbol returned by the function terminal-live-p (i.e., x, t, w32, ns, pc, haiku, pgtk, or android). See Frames.
• A list of terminal parameters. See Terminal Parameters.

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 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 (see 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 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 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 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; on X, it could be ‘XRandR 1.5’, ‘XRandr’, ‘Xinerama’, ‘Gdk’, or ‘fallback’. The last value of ‘source’ means that Emacs was built without GTK and without XRandR or Xinerama extensions, in which case the information about multiple physical monitors will be provided as if they all as a whole formed a single monitor.

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.

On multi-monitor displays it is possible to use the command make-frame-on-monitor to make frames on the specified monitor.

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

This function creates and returns a new frame on monitor located on display, taking the other frame parameters from the alist parameters. monitor should be the name of the physical monitor, the same string as returned by the function display-monitor-attributes-list in the attribute name. display should be the name of an X display (a string).

Variable: display-monitors-changed-functions ¶

This variable is an abnormal hook run when the monitor configuration changes, which can happen if a monitor is rotated, moved, added or removed from a multiple-monitor setup, if the primary monitor changes, or if the resolution of a monitor changes. It is called with a single argument consisting of the terminal on which the monitor configuration changed. Programs should call display-monitor-attributes-list with the terminal as the argument to retrieve the new monitor configuration on that terminal.

Next: Frame Parameters, Previous: Multiple Terminals, Up: Frames   [Contents][Index]

30.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 Deleting Frames). If omitted or nil, it specifies the selected frame (see Input Focus).

• Frame Layout
• Frame Font
• Frame Position
• Frame Size
• Implied Frame Resizing

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

Next: Terminal Parameters, Previous: Frame Geometry, Up: Frames   [Contents][Index]

30.4 Frame Parameters ¶

A frame has many parameters that control its appearance and behavior. Just what parameters are meaningful for a frame depends on what display mechanism it uses. Many frame parameters exist mostly for the sake of graphical displays and have no effect when applied to the top frame (see Frames) of a text terminal.

By default, frame parameters are saved and restored by the desktop library functions (see 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.

• Access to Frame Parameters
• Initial Frame Parameters
• Window Frame Parameters
• Geometry

Next: Frame Titles, Previous: Frame Parameters, Up: Frames   [Contents][Index]

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

Next: Deleting Frames, Previous: Terminal Parameters, Up: Frames   [Contents][Index]

30.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 (via the frame’s parameters; see Basic Parameters). 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. See The Data Structure of the Mode Line.

Variable: icon-title-format ¶

This variable specifies how to compute the name for an iconified frame when you have not explicitly specified the frame’s name via the frame’s parameters. The resulting title appears in the frame’s icon itself. If the value is a string, is should be a mode line construct like that of frame-title-format. The value can also be t, which means to use frame-title-format instead; this avoids problems with some window managers and desktop environments, where a change in a frame’s title (when a frame is iconified) is interpreted as a request to raise the frame and/or give it input focus. It is also useful if you want the frame’s title to be the same no matter if the frame is iconified or not. The default value is a string identical to the default value of frame-title-format.

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.

Next: Finding All Frames, Previous: Frame Titles, Up: Frames   [Contents][Index]

30.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 Child Frames) and any frame whose delete-before frame parameter (see 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. After actually killing the frame and removing the frame from the frame list, delete-frame runs after-delete-frame-functions.

Note that a frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (see 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. Also, the initial terminal frame of an Emacs process running as daemon (see daemon in The GNU Emacs Manual) can be deleted if and only if force is non-nil.

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 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. See Miscellaneous System Events.

Command: delete-other-frames &optional frame iconify ¶

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 Child Frames). If frame is a child frame, it deletes frame’s siblings only.

With the prefix argument iconify, the frames are iconified rather than deleted.

The following function checks whether a frame can be safely deleted. It is useful for avoiding the situation whereby a subsequent call of delete-frame fails to delete its argument frame and/or signals an error. To that end, your Lisp program should call delete-frame only if the following function returns non-nil.

Function: frame-deletable-p &optional frame ¶

This function returns non-nil if the frame specified by frame can be safely deleted. frame must be a live frame and defaults to the selected frame.

A frame cannot be safely deleted in the following cases:

• It is the only visible or iconified frame (see Visibility of Frames) on its terminal.
• It hosts the active minibuffer window and minibuffer windows do not follow the selected frame (see (emacs)Basic Minibuffer).
• All other visible or iconified frames on the same terminal are either child frames (see Child Frames) or have a non-nil delete-before parameter.
• The frame or one of its descendants hosts the minibuffer window of a frame that is not a descendant of the frame (see Child Frames).

These conditions cover most cases where delete-frame might fail when called from top-level. They do not catch some special cases like, for example, deleting a frame during a drag-and-drop operation (see Drag and Drop). In any such case, it will be better to wrap the delete-frame call in a condition-case form.

When the selected frame gets deleted Emacs has to select another frame instead. The following option lets you choose which one.

User Option: delete-frame-choose-selected ¶

This variable specifies which frame to select after deleting the selected frame. The default value mru means delete-frame should try to select the most recently used frame as returned by get-mru-frame (see Input Focus) on the same terminal. The value nil means that delete-frame will try to select the oldest visible frame on the same terminal as the deleted one.

Next: Splitting and Merging Frames, Previous: Deleting Frames, Up: Frames   [Contents][Index]

30.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 with the exception of tooltip frames (see Tooltips). The list that you get is newly created, so modifying the list doesn’t have any effect on the internals of Emacs.

Function: visible-frame-list ¶

This function returns a list of just the currently visible frames. See Visibility of Frames. Frames on text terminals will 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’s frames, in Z (stacking) order (see 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 does not return a frame whose no-other-frame parameter (see Frame Interaction Parameters) is non-nil.

The second argument, minibuf, says which frames to consider when deciding what the next frame should be:

nil

Consider all frames except minibuffer-only frames.

visible

Consider only visible frames.

0

Consider only visible or iconified frames.

a window

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

anything else

Consider all frames.

If this function does not find a suitable frame, it returns frame even if it would not qualify according to the minibuf argument or its no-other-frame parameter.

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 Cyclic Ordering of Windows.

Some Lisp programs need to find one or more frames that satisfy given criteria. The function filtered-frame-list is provided for this purpose.

Function: filtered-frame-list predicate ¶

This function returns the list of all the live frames which satisfy the specified predicate. The argument predicate must be a function of one argument, a frame to be tested against the filtering criteria, and should return non-nil if the frame satisfies the criteria.

Next: Minibuffers and Frames, Previous: Finding All Frames, Up: Frames   [Contents][Index]

30.9 Splitting and Merging Frames ¶

The following two functions are useful to transfer parts of the window layout (see Basic Concepts of Emacs Windows) of one frame to two separate frames and to merge the window layouts of two separate frames into one frame.

Command: split-frame &optional frame arg ¶

This command transfers some windows of the specified frame to a new frame and subsequently deletes them on frame. frame must be a live frame and defaults to the selected frame. arg specifies the number of windows to transfer and defaults to 1. Interactively, arg is the prefix argument.

In a first step, it divides the child windows (see Windows and Frames) of frame’s main window (see Side Windows) into two parts. The first part includes the first arg child windows if arg is positive, and the −arg last child windows if arg is negative. The second part includes the remaining child windows of frame’s main window.

In a second step, it clones (see Window Configurations) into a newly created frame each of the windows of the part which does not include frame’s selected window (see Selecting Windows) and removes those windows from frame. Note that the original identity (see Basic Concepts of Emacs Windows) of the cloned windows is lost in this step. The identity of the windows retained on frame is preserved, however. In a final step, it deletes the windows that have been cloned from frame and returns the newly created frame.

This function signals an error if arg is either zero or not a number, or if frame’s main window is either live or does not have more child windows than specified by the absolute value of arg.

Command: merge-frames &optional frame1 frame2 vertical ¶

This command transfers the main window (see Side Windows) of frame2 to frame1. Both frame1 and frame2 must specify live frames.

In the first step it splits the main window of frame1. If vertical is non-nil, it makes the new window below the old main window of frame1. Otherwise, it makes the new window on the right of frame1’s main window.

In the second step it makes the new window a clone (see Window Configurations) of the main window of frame2. The original identity (see Basic Concepts of Emacs Windows) of the cloned windows is lost in that step. In the final step, it deletes frame2 if the merge completed successfully and returns frame1.

Interactively, vertical is the prefix argument, frame1 is the selected frame and frame2 is the frame following frame1 in the list of all frames (see Finding All Frames). If frame1 and frame2 are omitted or nil in calls from Lisp, they default to the above values.

In general you cannot “undo” a split-frame call with a subsequent merge-frames call for the following reasons: In its second step merge-frame puts the main window of frame2 into an internal window split off in the first step. No such window was present in the configuration of frame1 before calling split-frame. Also, after merging is complete, the window cloned from the main window of frame2 will occupy as much space as the main window of frame1 before merging. This might not match the space distribution of the original layout.

Hence, if your preferred workflow is to temporarily split off windows for working on them in a separate frame and later continue with the original layout of the original frame, you should proceed as follows: Save the configuration (see Window Configurations) of the original frame, call split-frame to create the separate frame and finally restore the saved configuration of the original frame and delete the separate frame.

Next: Input Focus, Previous: Splitting and Merging Frames, Up: Frames   [Contents][Index]

30.10 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 (see 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 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 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 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 Multiple Terminals.

Next: Visibility of Frames, Previous: Minibuffers and Frames, Up: Frames   [Contents][Index]

30.11 Input Focus ¶

At any time, one frame in Emacs is the selected frame. The selected window (see Selecting Windows) always resides on the selected frame.

When Emacs displays its frames on several terminals (see 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 frames have focus. To explicitly switch to a different frame from a Lisp function, call select-frame-set-input-focus.

The plural “frames” in the previous paragraph is deliberate: while Emacs itself has only one selected frame, Emacs can have frames on many different terminals (recall that a connection to a window system counts as a terminal), and each terminal has its own idea of which frame has input focus. Under the X Window System, where user input is organized into individual “seats” of input, each seat in turn can have its own specific input focus. When you set the input focus to a frame, you set the focus for that frame’s terminal on the last seat which interacted with Emacs, but frames on other terminals and seats may still remain focused.

If the input focus is set before any user interaction has occurred on the specified terminal, then the X server picks a random seat (normally the one with the lowest number) and sets the input focus there.

Lisp programs can 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 (see Variables Used in the Mode Line).

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 window system’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 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). See 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.

Function: frame-use-time &optional frame ¶

This function returns the use time of frame frame. frame must be a live frame and defaults to the selected one.

The use time of a frame is the highest use time as reported by window-use-time of any window on frame.

Function: get-mru-frame &optional all-frames exclude-child-frames exclude-frame ¶

This function returns the frame with the highest use time as reported by frame-use-time. It returns nil if no candidate frames are found which usually happens if frames are excluded with the help of the optional arguments.

By default, tooltip and minibuffer-only frames are never candidates. If the optional argument exclude-child-frames is non-nil, child frames are excluded too. The exclude-frame argument, if present, excludes the frame it specifies too. Since in practice the most recently used frame is always the selected one, it usually makes sense to call this function with a non-nil exclude-frame argument specifying the selected frame.

The optional argument all-frames specifies which frames to consider:

• visible means to consider all visible frames on the current terminal or exclude-frame’s terminal.
• 0 means to consider all visible or iconified frames on the current terminal or exclude-frame’s terminal.
• Anything else means to consider all frames.

Function: get-mru-frames &optional all-frames exclude-child-frames exclude-frame ¶

This function returns a list of frames sorted by highest use time as reported by frame-use-time which is computed using each frame’s most recently used window.

By default, tooltip and minibuffer-only frames are never candidates. If the optional argument exclude-child-frames is non-nil, child frames are excluded too. The exclude-frame argument, if present, excludes the frame it specifies too.

It can return nil which can happen if frames are excluded with the help of the optional arguments, for example, if there is a single frame and exclude-frame is the selected frame.

The optional argument all-frames specifies which frames to consider:

• visible means to consider all visible frames on the current terminal or exclude-frame’s terminal.
• 0 means to consider all visible or iconified frames on the current terminal or exclude-frame’s terminal.
• Anything else means to consider all frames.

Command: select-frame-by-id id &optional noerror ¶

This function searches open and undeletable frames for a matching frame identifier id (see Frames). If found, its frame is undeleted, if necessary, then raised, given focus, and made the selected frame. On a text terminal, raising a frame causes it to occupy the entire terminal display.

This function returns the selected frame or signals an error if id is not found, unless noerror is non-nil, in which case it returns nil.

Command: undelete-frame-by-id id &optional noerror ¶

This function searches undeletable frames for a matching frame identifier id (see Frames). If found, its frame is undeleted, raised, given focus, and made the selected frame. On a text terminal, raising a frame causes it to occupy the entire terminal display.

This function returns the undeleted frame or signals an error if id is not found, unless noerror is non-nil, in which case it returns nil.

Emacs cooperates with the window system by arranging to select frames as the server and window manager request. When a window system informs Emacs that one of its frames has been selected, Emacs internally generates a focus-in event. When an Emacs frame is displayed on a text-terminal emulator, such as xterm, which supports reporting of focus-change notification, the focus-in and focus-out events are available even for text-mode frames. Focus events are normally handled by handle-focus-in.

Command: handle-focus-in event ¶

This function handles focus-in events from window systems and terminals that support explicit focus notifications. It updates the per-frame focus flags that frame-focus-state queries and calls after-focus-change-function. In addition, it generates a switch-frame event in order to switch the Emacs notion of the selected frame to the frame most recently focused in some terminal. It’s important to note that this switching of the Emacs selected frame to the most recently focused frame does not mean that other frames do not continue to have the focus in their respective terminals. Do not invoke this function yourself: instead, attach logic to after-focus-change-function.

Command: handle-switch-frame frame ¶

This function handles a switch-frame event, which Emacs generates for itself upon focus notification or under various other circumstances involving an input event arriving at a different frame from the last event. Do not invoke this function yourself.

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.

Function: frame-focus-state &optional frame ¶

This function retrieves the last known focus state of frame. frame defaults to the selected frame.

It returns nil if the frame is known not to be focused, t if the frame is known to be focused, or unknown if Emacs does not know the focus state of the frame. (You may see this last state in TTY frames running on terminals that do not support explicit focus notifications.)

Variable: after-focus-change-function ¶

This function is called with no arguments when Emacs notices that a frame may have gotten or lost focus. Focus events are delivered asynchronously, and may not be delivered in the expected order, so code that wants to do something depending on the state of focused frames have go through all the frames and check.

For instance, here’s a simple example function that sets the background color based on whether the frame has focus or not:

(add-function :after after-focus-change-function
              #'my-change-background)
(defun my-change-background ()
  (dolist (frame (frame-list))
    (pcase (frame-focus-state frame)
      (`t (set-face-background 'default "black" frame))
      (`nil (set-face-background 'default "#404040" frame)))))

Multiple frames may appear to have input focus simultaneously due to focus event delivery differences, the presence of multiple Emacs terminals, and other factors, and code should be robust in the face of this situation.

Depending on window system, focus events may also be delivered repeatedly and with different focus states before settling to the expected values. Code relying on focus notifications should “debounce” any user-visible updates arising from focus changes, perhaps by deferring work until redisplay.

This function may be called in arbitrary contexts, including from inside read-event, so take the same care as you might when writing a process filter.

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 (see 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-system 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 (see Mouse Window Auto-selection).

Next: Raising, Lowering and Restacking Frames, Previous: Input Focus, Up: Frames   [Contents][Index]

30.12 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’s point of view they are the same thing). If a frame is invisible, it is not displayed at all.

On a text terminal a frame may be only visible or invisible. The top frame (see Frames) of a terminal cannot be invisible.

On graphical displays 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.

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.

Note that the visibility status of a frame as reported by this function (and by the visibility frame parameter, see Frame Interaction Parameters) does not necessarily tell whether the frame is actually seen on display. Any such frame can be partially or completely obscured by other window manager windows on the same graphical terminal. Whether that completely hides the frame may then depend on the transparency of the obscuring window. A frame may also reside on a virtual desktop different from the current one and can be seen only when making that desktop the current one. One notable restriction holds for child frames (see Child Frames): A child frame can be seen if and only if this function returns true for all its ancestors including the frame itself and its root frame.

On a text terminal only that terminal’s top frame and its child frames can be actually seen. Other root frames and their child frames cannot be seen even if they are considered visible by this function.

Command: iconify-frame &optional frame ¶

This function iconifies frame frame. If you omit frame, it iconifies the selected frame. This function also removes any child frames (see Child Frames) of frame and their descendants from display. If frame is a child frame itself, the behavior depends on the value of the variable iconify-child-frame. If frame is the top frame of a text terminal (see Frames), this function has no effect.

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 Raising, Lowering and Restacking Frames).

Making a frame visible makes all its child frames with visible ancestors appear on display again (see 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 Child Frames).

Unless force is non-nil, this function refuses to make frame invisible if all other frames are invisible. On a text terminal this will make frame invisible if and only if it is a child frame (see Child Frames). In this case, if frame is selected, it will select the first visible ancestor of frame instead. In addition, it will remove all child frames with frame as their ancestor from display.

The visibility status of a frame is also available as a frame parameter. You can read or change it as such. See Frame Interaction 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. See Miscellaneous System 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.

Next: Frame Configurations, Previous: Visibility of Frames, Up: Frames   [Contents][Index]

30.13 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 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 Child Frames), this raises frame above all other child frames of its parent. For non-child frames on a text terminal this function has no effect.

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 Child Frames), this lowers frame below all other child frames of its parent. For non-child frames on a text terminal this function has no effect.

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. This function has not been implemented on text terminals yet.

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 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 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. This variable has no effect on text terminals.

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

Next: Child Frames, Previous: Raising, Lowering and Restacking Frames, Up: Frames   [Contents][Index]

30.14 Frame Configurations ¶

A frame configuration records the current arrangement of frames, all their properties, and the window configuration of each one. (See 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.

Next: Mouse Tracking, Previous: Frame Configurations, Up: Frames   [Contents][Index]

30.15 Child Frames ¶

Child frames are objects halfway between windows (see 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 Frame Parameters) without any specialized functions or customizable variables. Child frames are meaningful on graphical and text terminals.

• Child Frame Operations
• Child Frame Properties
• Child Frame Peculiarities

(let* ((selected (selected-frame))
       (mini-only
        (make-frame
         `((parent-frame . ,selected)
           (minibuffer . only)
           (left . 1) (top . -1) (width . 20) (height . 1))))
       (mini-less
        (make-frame
         (append `((parent-frame . ,selected)
                   (minibuffer . ,(minibuffer-window mini-only)))))))
  (set-frame-parameter mini-only 'parent-frame mini-less)
  (set-frame-parameter mini-less 'parent-frame nil)
  (select-frame mini-less)
  (delete-frame selected))

Next: Mouse Position, Previous: Child Frames, Up: Frames   [Contents][Index]

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

Macro: track-mouse body… ¶

This macro 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. See 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. Its value also controls how mouse events are reported while a mouse button is held down: if it is dropping or drag-source, the motion events are reported relative to the frame underneath the pointer. If there is no such frame, the events will be reported relative to the frame the mouse buttons were first pressed on. In addition, the posn-window of the mouse position list will be nil if the value is drag-source. This is useful to determine if a frame is not directly visible underneath the mouse pointer.

The track-mouse macro 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 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 (see Properties with Special Meanings). That works at a much lower level and runs more smoothly than Lisp-level mouse tracking.

Next: Pop-Up Menus, Previous: Mouse Tracking, Up: Frames   [Contents][Index]

30.17 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 Frame Font) relative to the native position of frame (see 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.

Variable: tty-menu-calls-mouse-position-function ¶

If non-nil, TTY menus will call mouse-position-function as described above. This exists for cases where mouse-position-function is not safe to be called by the TTY menus, such as if it could trigger redisplay.

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 Frame Font) relative to the native position of frame (see 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.

Next: On-Screen Keyboards, Previous: Mouse Position, Up: Frames   [Contents][Index]

30.18 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 or touchscreen-begin 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 (see 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 (see 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. See The 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.

Variable: x-pre-popup-menu-hook ¶

A normal hook run immediately before a pop-up menu is displayed, either directly by calling x-popup-menu, or through a menu keymap. It won’t be called if x-popup-menu returns for some other reason without displaying a pop-up menu.

Next: Dialog Boxes, Previous: Pop-Up Menus, Up: Frames   [Contents][Index]

30.19 On-Screen Keyboards ¶

An on-screen keyboard is a special kind of pop up provided by the system, with rows of clickable buttons that act as a real keyboard.

On certain systems (see On-Screen Keyboards in The Emacs Manual), Emacs is supposed to display and hide the on screen keyboard depending on whether or not the user is about to type something.

Function: frame-toggle-on-screen-keyboard frame hide ¶

This function displays or hides the on-screen keyboard on behalf of the frame frame. If hide is non-nil, then the on-screen keyboard is hidden; otherwise, it is displayed.

It returns whether or not the on screen keyboard may have been displayed, which should be used to determine whether or not to hide the on-screen keyboard later.

This has no effect if the system automatically detects when to display the on-screen keyboard, or when it does not provide any on-screen keyboard.

Next: Pointer Shape, Previous: On-Screen Keyboards, Up: Frames   [Contents][Index]

30.20 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 (see 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.

Next: Window System Selections, Previous: Dialog Boxes, Up: Frames   [Contents][Index]

30.21 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 in the table below. The actual shapes may vary between systems; the descriptions are examples.

text

nil

The usual mouse pointer style used over text (an “I”-like shape).

arrow

vdrag

modeline

An arrow that points north-west.

hand

A hand that points upwards.

hdrag

A right-left arrow.

nhdrag

An up-down arrow.

hourglass

A rotating ring.

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 some window systems, 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 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.

Next: Accessing Selections, Previous: Pointer Shape, Up: Frames   [Contents][Index]

30.22 Window System Selections ¶

In window systems, such as X, data can be transferred between different applications by means of selections. Each window system defines an arbitrary number of selection types, all storing their own data; however, only three are commonly used: the clipboard, primary selection, and secondary selection. 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; See Accessing Selections, for documentation concerning selection types and data formats under particular window systems.

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

If data is a string, then its text properties can specify values used for individual data types. For example, if data has a property named text/uri-list, then a call to gui-get-selection with the data type text/uri-list will result in the value of that property being used instead of data itself.

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. It defaults to STRING. See X Selections, for an enumeration of data types valid on X, and see Other Selections for those elsewhere. On X Window system, we recommend to always specify a particular data-type, especially if the selection is expected to be non-ASCII text (in which case Lisp programs should prefer UTF8_STRING as the value of data-type). This is because the default data-type value, STRING, can only support Latin-1 text, which in many cases is nowadays inadequate.

User Option: selection-coding-system ¶

This variable provides a coding system (see Coding Systems) which is used to encode selection data, and takes effect on MS-Windows and X. It is also used in the MS-DOS port when it runs on MS-Windows and can access the Windows clipboard text.

On X, the value of this variable provides the coding system which gui-get-selection will use to decode selection data for a subset of text data types, and also forces replies to selection requests for the polymorphic TEXT data type to be encoded by the compound-text-with-extensions coding system rather than Unicode.

On MS-Windows, this variable is generally ignored, as the MS-Windows clipboard provides the information about decoding as part of the clipboard data, and uses either UTF-16 or locale-specific encoding automatically as appropriate. We recommend to set the value of this variable only on the older Windows 9X, as it is otherwise used only in the very rare cases when the information provided by the clipboard data is unusable for some reason.

The default value of this variable is the system code page under MS-Windows 98 or Me, utf-16le-dos on Windows NT/W2K/XP/Vista/7/8/10/11, iso-latin-1-dos on MS-DOS, and nil elsewhere.

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.

Next: Yanking Media, Previous: Window System Selections, Up: Frames   [Contents][Index]

30.23 Accessing Selections ¶

The data types and selections that gui-get-selection and gui-set-selection understand are not precisely specified and differ subject to the window system on which Emacs is running.

At the same time, gui-set-selection abstracts over plenty of complexity: its data argument is given verbatim to system-specific code to be rendered suitable for transfer to the window system or requesting clients.

The most comprehensive implementation of selections exists under the X Window System. This is both an artifact of history (X was the first window system supported by Emacs) and one occasioned by technical considerations: X selections are not merely an expedient for the transfer of text and multimedia content between clients, but a general inter-client communication system, a design that has yielded a proliferation of selection and data types.

Compounding this confusion, there is another inter-client communication mechanism under X: the Inter-Client Exchange. ICE is only used by Emacs to communicate with session managers, and is a separate topic.

• X Selections
• Other Selections

Next: Drag and Drop, Previous: Accessing Selections, Up: Frames   [Contents][Index]

30.24 Yanking Media ¶

Data saved within window system selections and the MS-Windows clipboard is not restricted to plain text. It is possible for selection data to encompass images or other binary data of the like, as well as rich text content instanced by HTML, and also PostScript. Since the selection data types incident to this data are at variance with those for plain text, the insertion of such data is facilitated by a set of functions dubbed yank-media handlers, which are registered by each major mode undertaking its insertion and called where warranted upon the execution of the yank-media command.

Function: yank-media-handler types handler ¶

Register a yank-media handler which applies to the current buffer.

types can be a symbol designating a selection data type (see Accessing Selections), a regexp against which such types are matched, or a list of these symbols and regexps. For instance:

(yank-media-handler 'text/html #'my-html-handler)
(yank-media-handler "image/.*" #'my-image-handler)

When a selection offers a data type matching types, the function handler is called to insert its data, with the symbol designating the matching selection data type, and the data returned by gui-get-selection.

The yank-media command auto selects the preferred MIME type by default. The rules used for the selection can be controlled through the variables yank-media-autoselect-function and yank-media-preferred-types.

Variable: yank-media-autoselect-function ¶

This variable should specify a function that will be called with the list of MIME types available for the current major mode, and should return a list of preferred MIME types to use. The first MIME type in the list will always be used by the yank-media command when auto selection is requested.

Variable: yank-media-preferred-types ¶

This variable changes the default selection process of yank-media-autoselect-function. It is a list that should contain the sole MIME type to choose in the order of their preference. It can also contain a function in which case it is called with the list of available MIME types and must return a list of preferred MIME types in order of their preference. This list is passed onto the yank-media command so the first element of the returned list is chosen when auto selection is requested.

The yank-media-types command presents a list of selection data types that are currently available, which is useful when implementing yank-media handlers; for programs generally offer an eclectic and seldom consistent medley of data types.

Next: Color Names, Previous: Yanking Media, Up: Frames   [Contents][Index]

30.25 Drag and Drop ¶

Data transferred by drag and drop is generally either plain text or a list of URLs designating files or other resources. When text is dropped, it is inserted at the location of the drop, with recourse to saving it into the kill ring if that is not possible.

URLs dropped are supplied to pertinent DND handler functions in the variable dnd-protocol-alist, or alternatively “URL handlers” as set forth by the variables browse-url-handlers and browse-url-default-handlers; absent matching handlers of either type, they are treated as plain text and inserted in the buffer.

Variable: dnd-protocol-alist ¶

This variable is an alist between regexps against which URLs are matched and DND handler functions called on the dropping of matching URLs.

If a handler function is a symbol whose dnd-multiple-handler property (see Symbol Properties) is set, then upon a drop it is given a list of every URL that matches its regexp; absent this property, it is called once for each of those URLs. Following this first argument is one of the symbols copy, move, link, private or ask identifying the action to be taken.

If action is private, the program that initiated the drop does not insist on any particular behavior on the part of its recipient; a reasonable action to take in that case is to open the URL or copy its contents into the current buffer. The other values of action imply much the same as in the action argument to dnd-begin-file-drag.

Once its work completes, a handler function must return a symbol designating the action it took: either the action it was provided, or the symbol private, which communicates to the source of the drop that the action it prescribed has not been executed.

When multiple handlers match an overlapping subset of items within a drop, the handler matched against by the greatest number of items is called to open that subset. The items it is supplied are subsequently withheld from other handlers, even those they also match.

Emacs does not take measures to accept data besides text and URLs, for the window system interfaces which enable this are too far removed from each other to abstract over consistently. Nor are DND handlers accorded influence over the actions they are meant to take, as particular drag-and-drop protocols deny recipients such control. The X11 drag-and-drop implementation rests on several underlying protocols that make use of selection transfer and share much in common, to which low level access is provided through the following functions and variables:

Variable: x-dnd-test-function ¶

This function is called to ascertain whether Emacs should accept a drop. It is called with three arguments:

• The window under the item being dragged, which is to say the window whose buffer is to receive the drop. If the item is situated over a non-window component of a frame (such as scroll bars, tool bars and things to that effect), the frame itself is provided in its place.
• One of the symbols move, copy, link or ask, representing an action to take on the item data suggested by the drop source. These symbols carry the same implications as in x-begin-drag.
• A vector of selection data types (see X Selections) the item provides.

This function must return nil to reject the drop or a cons of the action that will be taken (such as through transfer to a DND handler function) and the selection data type to be requested. The action returned in that cons may also be the symbol private, which intimates that the action taken is as yet indeterminate.

Variable: x-dnd-known-types ¶

Modifying x-dnd-test-function is generally unwarranted, for its default set of criteria for accepting a drop can be adjusted by changing this list of selection data types. Each element is a string, which if found as the symbol name of an element within the list of data types by the default “test function”, will induce that function to accept the drop.

Introducing a new entry into this list is not useful unless a counterpart handler function is appended to x-dnd-types-alist.

Variable: x-dnd-types-alist ¶

This variable is an alist between strings designating selection data types and functions which are called when things of such types are dropped.

Each such function is supplied three arguments; the first is the window or frame below the location of the drop, as in x-dnd-test-function; the second is the action to be taken, which may be any of the actions returned by test functions, and third is the selection data itself (see Accessing Selections).

Selection data types as provided by X11 drag-and-drop protocols are sometimes distinct from those provided by the ICCCM and conforming clipboard or primary selection owners. Frequently, the name of a MIME type, such as "text/plain;charset=utf-8" (with discrepant capitalization of the “utf-8”), is substituted for a standard X selection name such as UTF8_STRING.

The X Direct Save (XDS) protocol enables programs to devolve responsibility for naming a dropped file upon the recipient. When such a drop transpires, DND handlers and the foregoing X-specific interface are largely circumvented, tasking a different function with responding to the drop.

Variable: x-dnd-direct-save-function ¶

This variable should be set to a function that registers and names files dropped using the XDS protocol in a two-step procedure. It is provided two arguments, need-name and filename.

1. The application from which the file is dragged asks Emacs to provide the full file name under which to save the file. For this purpose, the direct-save function is called with its first argument need-name non-nil, and the second argument filename set to the basename of the file to be saved. It should return the fully-expanded absolute file name under which to save the file. For example, if a file is dragged to a Dired window, the natural directory for the file is the directory of the file shown at location of the drop. If saving the file is not possible for some reason, the function should return nil, which will cancel the drag-and-drop operation.
2. The application from which the file is dragged saves the file under the name returned by the first call to the direct-save function. If it succeeds in saving the file, the direct-save function is called again, this time with the first argument need-name set to nil and the second argument filename set to the full absolute name of the saved file. The function is then expected to do whatever is needed given the fact that file was saved. For example, Dired should update the directory on display by showing the new file there.

Its default x-dnd-direct-save-function is x-dnd-save-direct.

Function: x-dnd-save-direct need-name filename ¶

When called with the need-name argument non-nil, this function prompts the user for the absolute file name under which it should be saved. If the specified file already exists, it additionally asks the user whether to overwrite it, and returns the absolute file name only if the user confirms the overwriting.

When called with the need-name argument nil, it reverts the Dired listing if the current buffer is in Dired mode or one of its descendants, and otherwise visits the file by calling find-file (see Functions for Visiting Files).

Function: x-dnd-save-direct-immediately need-name filename ¶

This function works like x-dnd-save-direct, but when called with its need-name argument non-nil, it doesn’t prompt the user for the full name of the file to be saved; instead, it returns its argument filename expanded against the current buffer’s default directory (see Functions that Expand Filenames). (It still asks for confirmation if a file by that name already exists in the default directory.)

It is also possible to drag content from Emacs to other programs when this is supported by the current window-system. The functions which provide for this are as follows:

Function: dnd-begin-text-drag text &optional frame action allow-same-frame ¶

This function starts a drag-and-drop operation from frame to another program (dubbed the drop target), and returns when text is dropped or the operation is canceled.

action must be one of the symbols copy or move, where copy means that text should be inserted by the drop target, and move means the same as copy, but the caller must also delete text from its source as explained in the list below.

frame is the frame where the mouse is currently held down, or nil, which means to use the selected frame. Since this function might return promptly if no mouse buttons are held down, it should be only called in response to a down-mouse-1 or analogous event (see Mouse Events), with frame set to the frame where that event was generated (see Click Events).

If allow-same-frame is nil, drops on top of frame will be ignored.

The return value reflects the action that the drop target actually performed, and thus also what action, if any, the caller should in turn take. It is one of the following symbols:

copy

The drop target inserted the dropped text.

move

The drop target inserted the dropped text, and the caller should delete text from the buffer where it was extracted from, if applicable.

private

The drop target took some other unspecified action.

nil

The drag-and-drop operation was canceled.

Function: dnd-begin-file-drag file &optional frame action allow-same-frame ¶

This function starts a drag-and-drop operation from frame to another program (dubbed the drop target), and returns when file is dropped or the operation is canceled.

If file is a remote file, then a temporary local copy will be made.

action must be one of the symbols copy, move or link, where copy means that file should be opened or copied by the drop target, move means the drop target should move the file to another location, and link means the drop target should create a symbolic link to file. It is an error to specify link as the action if file is a remote file.

frame and allow-same-frame mean the same as they do in calls to dnd-begin-text-drag.

The return value is the action that the drop target actually performed, which is one of the following symbols:

copy

The drop target opened or copied file to a different location.

move

The drop target moved file to a different location.

link

The drop target (usually a file manager) created a symbolic link to file.

private

The drop target performed some other unspecified action.

nil

The drag-and-drop operation was canceled.

Function: dnd-begin-drag-files files &optional frame action allow-same-frame ¶

This function is like dnd-begin-file-drag, except that files is a list of files. If the drop target doesn’t support dropping multiple files, then the first file will be used instead.

Function: dnd-direct-save file name &optional frame allow-same-frame ¶

The behavior of this function is akin to that of dnd-begin-file-drag (when the default action copy is used), except that it accepts a name under which the copy is meant to be filed.

The high-level interfaces described above are implemented on top of a lower-level primitive. The low-level interface x-begin-drag is also available for dragging content besides text and files. It demands detailed knowledge of the data types and actions understood by programs on each platform its callers wish to support.

Function: x-begin-drag targets &optional action frame return-frame allow-current-frame follow-tooltip ¶

This function begins a drag from frame, and returns when the drag-and-drop operation ends, either because the drop was successful, or because the drop was rejected. The drop occurs when all mouse buttons are released on top of an X window other than frame (the drop target), or any X window if allow-current-frame is non-nil. If no mouse buttons are held down when the drag-and-drop operation begins, this function may immediately return nil.

targets is a list of strings representing selection targets, much like the data-type argument to gui-get-selection, that the drop target can request from Emacs (see Window System Selections).

action is a symbol designating the action recommended to the target. It can either be XdndActionCopy or XdndActionMove; both imply copying the contents of the selection XdndSelection to the drop target, but the latter moreover conveys a promise to delete the contents of the selection after the copying.

action may also be an alist which associates between symbols representing available actions, and strings that the drop target presents to the user for him to select between those actions.

If return-frame is non-nil and the mouse moves over an Emacs frame after first moving out of frame, then the frame to which the mouse moves will be returned immediately. If return-frame is the symbol now, then any frame beneath the mouse pointer will be returned without waiting for the mouse to first move out of frame. return-frame is useful when you want to treat dragging content from one frame to another specially, while also dragging content to other programs, but it is not guaranteed to function on all systems and with all window managers.

If follow-tooltip is non-nil, the position of any tooltip (such as one displayed by tooltip-show) will follow the location of the mouse pointer as it moves during the drag-and-drop operation. The tooltip will be hidden once all mouse buttons are released.

If the drop was rejected or no drop target was found, this function returns nil. Otherwise, it returns a symbol representing the action the target opted to take, which can differ from action if that isn’t supported by the drop target. XdndActionPrivate is also a valid return value in addition to XdndActionCopy and XdndActionMove; it suggests that the drop target opted for an indeterminate action, and no further action is required of the caller.

The caller must cooperate with the target to complete the action selected by the target. For example, callers should delete any buffer text that was dragged if this function returns XdndActionMove, and likewise for other drag data where comparable criteria apply.

The function x-begin-drag leverages several drag-and-drop protocols “behind the scenes”. When dragging content that is known to not be supported by a specific drag-and-drop protocol, that protocol can be disabled by changing the values of the following variables:

Variable: x-dnd-disable-motif-protocol ¶

When this is non-nil, the Motif drag and drop protocols are disabled, and dropping onto programs that only understand them will not work.

Variable: x-dnd-use-offix-drop ¶

When this is nil, the OffiX (old KDE) drag and drop protocol is disabled. When this is the symbol files, the OffiX protocol will only be used if "FILE_NAME" is one of the targets given to x-begin-drag. Any other value means to use the OffiX protocol to drop all supported content.

Variable: x-dnd-use-unsupported-drop ¶

When one of the "STRING", "UTF8_STRING", "COMPOUND_TEXT" or "TEXT" targets is present in the list given to x-begin-drag, Emacs will try to use synthesized mouse events and the primary selection to insert the text if the drop target doesn’t support any drag-and-drop protocol at all.

A side effect is that Emacs will become the owner of the primary selection upon such a drop. Such emulation can be disabled by setting this variable to nil.

Next: Text Terminal Colors, Previous: Drag and Drop, Up: Frames   [Contents][Index]

30.26 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 (see 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).

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.

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")
     ⇒ (65535 65535 65535)
(color-values "red")
     ⇒ (65535 0 0)
(color-values "pink")
     ⇒ (65535 49344 52171)
(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.

Function: color-name-to-rgb color &optional frame ¶

This function does the same as color-values, but it returns color values as floating-point numbers between 0.0 and 1.0 inclusive.

Function: color-dark-p rgb ¶

This function returns non-nil if the color described by its RGB triplet rgb is more readable against white background than against dark background. The argument rgb should be a list of the form (r g b), with each component a floating-point number in the range 0.0 to 1.0 inclusive. You can use color-name-to-rgb to convert a color’s name to such a list.

Next: X Resources, Previous: Color Names, Up: Frames   [Contents][Index]

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

Next: Display Feature Testing, Previous: Text Terminal Colors, Up: Frames   [Contents][Index]

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

Previous: X Resources, Up: Frames   [Contents][Index]

30.29 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 Input Focus).

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

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