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

Command make-frame

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. 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. 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 (Initial Parameters); parameters not specified there default from the X resources or its equivalent on your operating system (X Resources). 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 (Multiple Terminals), the window manager might position the frame differently than specified by the positional parameters in parameters (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. Input Focus. The previously selected frame remains selected. On graphical terminals, however, the window system may select the new frame for its own reasons.

before-make-frame-hook

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

after-make-frame-functions

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

Note that any functions added to these hooks by your initial file are usually not run for the initial frame, since Emacs reads the initial file only after creating that frame. However, if the initial frame is specified to use a separate minibuffer frame (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" (Init File), in which case they will be in effect for the initial frame as well.

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.

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 (Invoking emacsclient), 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. Emacs Server.

Emacs represents each terminal as a terminal object data type (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. 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, or pgtk). Frames.
• A list of terminal parameters. 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).

terminal-name

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.

terminal-list

This function returns a list of all live terminal objects.

get-device-terminal

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.

delete-terminal

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 (Deleting Frames).

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 (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 (Initial Options). 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 (Input Focus). Emacs can even connect to other text terminals, by interacting with the emacsclient program. Emacs Server. 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

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 (Creating Frames).

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.

x-open-connection

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

x-close-connection

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

display-monitor-attributes-list

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

geometry

Position of the top-left corner of the monitor's screen and its size, in pixels, as (X Y WIDTH HEIGHT). Note that, if the monitor is not the primary monitor, some of the coordinates might be negative.

workarea

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

mm-size

Width and height in millimeters as (WIDTH HEIGHT)

frames

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

name

Name of the physical monitor as string.

source

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

x, y, width, and height are integers. name and source may be absent. A frame is dominated by a physical monitor when either the largest area of the frame resides in that monitor, or (if the frame does not intersect any physical monitors) that monitor is the closest to the frame. Every (non-tooltip) frame (whether visible or not) in a graphical display is dominated by exactly one physical monitor at a time, though the frame can span multiple (or no) physical monitors. Here's an example of the data produced by this function on a 2-monitor display:

(display-monitor-attributes-list)
  =>
  (((geometry 0 0 1920 1080) ;; Left-hand
    (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)))

frame-monitor-attributes

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

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

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.

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

<------------ 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 __________|  | v
     v |___________ External/Outer Border __________|
           <-------- Native Frame Width -------->

A frame has many parameters that control its appearance and behavior. Just what parameters a frame has depends on what display mechanism it uses. Frame parameters exist mostly for the sake of graphical displays. Most frame parameters have no effect when applied to a frame on a text terminal; only the height, width, name, title, menu-bar-lines, buffer-list and buffer-predicate parameters do something special. If the terminal supports colors, the parameters foreground-color, background-color, background-mode and display-type are also meaningful. If the terminal supports frame transparency, the parameter alpha is also meaningful. By default, frame parameters are saved and restored by the desktop library functions (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.

(PARAMETER . VALUE)

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

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.

terminal-parameters

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

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.

set-terminal-parameter

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. DEL Does Not Delete.

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.

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.

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; 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. Mode Line Data.

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.

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.

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

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 (Child Frames) and any frame whose delete-before frame parameter (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 (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.

frame-live-p

This function returns non-nil if the frame frame has not been deleted. The possible non-nil return values are like those of framep. 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. Misc Events.

Command delete-other-frames

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

frame-list

This function returns a list of all the live frames, i.e., those that have not been deleted. It is analogous to buffer-list for buffers, and includes frames on all terminals. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of Emacs.

visible-frame-list

This function returns a list of just the currently visible frames. Visibility of Frames. Frames on text terminals always count as visible, even though only the selected one is actually displayed.

frame-list-z-order

This function returns a list of Emacs' frames, in Z (stacking) order (Raising and Lowering). 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.

next-frame

This function lets you cycle conveniently through all the frames on a specific terminal from an arbitrary starting point. It returns the frame following frame, in the list of all live frames, on frame's terminal. The argument frame must specify a live frame and defaults to the selected frame. It never returns a frame whose no-other-frame parameter (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.

previous-frame

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

See also next-window and previous-window, in Cyclic Window Ordering. Some Lisp programs need to find one or more frames that satisfy a given criteria. The function filtered-frame-list is provided for this purpose.

filtered-frame-list

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.

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 (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 (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 (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. Raising and Lowering.

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

At any time, one frame in Emacs is the selected frame. The selected window (Selecting Windows) always resides on the selected frame. When Emacs displays its frames on several terminals (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.

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 (Mode Line Variables).

select-frame-set-input-focus

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.

x-focus-frame

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

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). Selecting Windows. This function returns frame, or nil if frame has been deleted. In general, you should never use select-frame in a way that could switch to a different terminal without switching back when you're done.

Emacs cooperates with the window system by arranging to select frames as the server and window manager request. 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

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

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.

redirect-frame-focus

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.

frame-focus-state

This function retrieves the last known focus state of 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.)

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.

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

A frame on a graphical display may be visible, invisible, or iconified. If it is visible, its contents are displayed in the usual manner. If it is iconified, its contents are not displayed, but there is a little icon somewhere to bring the frame back into view (some window managers refer to this state as minimized rather than iconified, but from Emacs' point of view they are the same thing). If a frame is invisible, it is not displayed at all. The concept of visibility is strongly related to that of (un-)mapped frames. A frame (or, more precisely, its window-system window) is and becomes mapped when it is displayed for the first time and whenever it changes its state of visibility from iconified or invisible to visible. Conversely, a frame is and becomes unmapped whenever it changes its status from visible to iconified or invisible. Visibility is meaningless on text terminals, since only the selected frame is actually displayed in any case.

frame-visible-p

This function returns the visibility status of frame frame. The value is t if frame is visible, nil if it is invisible, and icon if it is iconified. On a text terminal, all frames are considered visible for the purposes of this function, even though only one frame is displayed. Raising and Lowering.

Command iconify-frame

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

Command make-frame-visible

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 (Raising and Lowering). Making a frame visible usually makes all its child frames (and their descendants) visible as well (Child Frames).

Command make-frame-invisible

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 (Child Frames). Unless force is non-nil, this function refuses to make frame invisible if all other frames are invisible.

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

x-double-buffered-p

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

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

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 (Child Frames), this raises frame above all other child frames of its parent.

Command lower-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 (Child Frames), this lowers frame below all other child frames of its parent.

frame-restack

This function restacks frame1 below frame2. This implies that if both frames are visible and their display areas overlap, frame2 will (partially) obscure frame1. If the optional third argument above is non-nil, this function restacks frame1 above frame2. This means that if both frames are visible and their display areas overlap, frame1 will (partially) obscure frame2. Technically, this function may be thought of as an atomic action performed in two steps: The first step removes frame1's window-system window from the display. The second step reinserts frame1's window into the display below (above if above is true) that of frame2. Hence the position of frame2 in its display's Z (stacking) order relative to all other frames excluding frame1 remains unaltered. Some window managers may refuse to restack windows.

Note that the effect of restacking will only hold as long as neither of the involved frames is iconified or made invisible. You can use the z-group (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 (Finding All Frames).

minibuffer-auto-raise

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

On window systems, you can also enable auto-raising (on frame selection) or auto-lowering (on frame deselection) using frame parameters. Management Parameters. The concept of raising and lowering frames also applies to text terminal frames. On each text terminal, only the top frame is displayed at any one time.

tty-top-frame

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

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

current-frame-configuration

This function returns a frame configuration list that describes the current arrangement of frames and their contents.

set-frame-configuration

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.

Child frames are objects halfway between windows (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 (Frame Parameters) without any specialized functions or customizable variables. Note that child frames are meaningful on graphical terminals only. To create a new child frame or to convert a normal frame into a child frame, set that frame's parent-frame parameter (Frame Interaction Parameters) to that of an already existing frame. The frame specified by that parameter will then be the frame's parent frame as long as the parameter is not changed or reset. Technically, this makes the child frame's window-system window a child window of the parent frame's window-system window. The parent-frame parameter can be changed at any time. Setting it to another frame reparents the child frame. Setting it to another child frame makes the frame a nested child frame. Setting it to nil restores the frame's status as a top-level frame—a frame whose window-system window is a child of its display's root window.(On Haiku) Since child frames can be arbitrarily nested, a frame can be both a child and a parent frame. Also, the relative roles of child and parent frame may be reversed at any time (though it's usually a good idea to keep the size of a child frame sufficiently smaller than that of its parent). An error will be signaled for the attempt to make a frame an ancestor of itself. Most window-systems clip a child frame at the native edges (Frame Geometry) of its parent frame—everything outside these edges is usually invisible. A child frame's left and top parameters specify a position relative to the top-left corner of its parent's native frame. When the parent frame is resized, this position remains conceptually unaltered. NS builds do not clip child frames at the parent frame's edges, allowing them to be positioned so they do not obscure the parent frame while still being visible themselves. Usually, moving a parent frame moves along all its child frames and their descendants as well, keeping their relative positions unaltered. Note that the hook move-frame-functions (Frame Position) is run for a child frame only when the position of the child frame relative to its parent frame changes. When a parent frame is resized, its child frames conceptually retain their previous sizes and their positions relative to the left upper corner of the parent. This means that a child frame may become (partially) invisible when its parent frame shrinks. The parameter keep-ratio (Frame Interaction Parameters) can be used to resize and reposition a child frame proportionally whenever its parent frame is resized. This may avoid obscuring parts of a frame when its parent frame is shrunk. A visible child frame always appears on top of its parent frame thus obscuring parts of it, except on NS builds where it may be positioned beneath the parent. This is comparable to the window-system window of a top-level frame which also always appears on top of its parent window—the desktop's root window. When a parent frame is iconified or made invisible (Visibility of Frames), its child frames are made invisible. When a parent frame is deiconified or made visible, its child frames are made visible. When a parent frame is about to be deleted (Deleting Frames), its child frames are recursively deleted before it. There is one exception to this rule: When the child frame serves as a surrogate minibuffer frame (Minibuffers and Frames) for another frame, it is retained until the parent frame has been deleted. If, at this time, no remaining frame uses the child frame as its minibuffer frame, Emacs will try to delete the child frame too. If that deletion fails for whatever reason, the child frame is made a top-level frame. Whether a child frame can have a menu or tool bar is window-system or window manager dependent. Most window-systems explicitly disallow menu bars for child frames. It seems advisable to disable both, menu and tool bars, via the frame's initial parameters settings. Usually, child frames do not exhibit window manager decorations like a title bar or external borders (Frame Geometry). When the child frame does not show a menu or tool bar, any other of the frame's borders (Layout Parameters) can be used instead of the external borders. In particular, under X (but not when building with GTK+), the frame's outer border can be used. On MS-Windows, specifying a non-zero outer border width will show a one-pixel wide external border. Under all window-systems, the internal border can be used. In either case, it's advisable to disable a child frame's window manager decorations with the undecorated frame parameter (Management Parameters). To resize or move an undecorated child frame with the mouse, special frame parameters (Mouse Dragging Parameters) have to be used. The internal border of a child frame, if present, can be used to resize the frame with the mouse, provided that frame has a non-nil drag-internal-border parameter. If set, the snap-width parameter indicates the number of pixels where the frame snaps at the respective edge or corner of its parent frame. There are two ways to drag an entire child frame with the mouse: The drag-with-mode-line parameter, if non-nil, allows to drag a frame without minibuffer window (Minibuffer Windows) via the mode line area of its bottommost window. The drag-with-header-line parameter, if non-nil, allows to drag the frame via the header line area of its topmost window. In order to give a child frame a draggable header or mode line, the window parameters mode-line-format and header-line-format are handy (Window Parameters). These allow to remove an unwanted mode line (when drag-with-header-line is chosen) and to remove mouse-sensitive areas which might interfere with frame dragging. When the user drags a frame with a mouse and overshoots, it's easy to drag a frame out of the screen area of its parent. Retrieving such a frame can be hairy once the mouse button has been released. To prevent such a situation, it is advisable to set the frame's top-visible or bottom-visible parameter (Mouse Dragging Parameters). Set the top-visible parameter of a child frame to a number when you intend to allow the user dragging that frame by its header line. Setting top-visible to a number inhibits dragging the top edge of the child frame above the top edge of its parent. Set the bottom-visible parameter to a number when you intend to drag that frame via its mode line; this inhibits dragging the bottom edge of the child frame beneath the bottom edge of its parent. In either case, that number also specifies width and height (in pixels) of the area of the child frame that remains visible during dragging. When a child frame is used for displaying a buffer via display-buffer-in-child-frame (Buffer Display Action Functions), the frame's auto-hide-function parameter (Frame Interaction Parameters) can be set to a function, in order to appropriately deal with the frame when the window displaying the buffer shall be quit. When a child frame is used during minibuffer interaction, for example, to display completions in a separate window, the minibuffer-exit parameter (Frame Interaction Parameters) is useful in order to deal with the frame when the minibuffer is exited. The behavior of child frames deviates from that of top-level frames in a number of other ways as well. Here we sketch a few of them:

• The semantics of maximizing and iconifying child frames is highly window-system dependent. As a rule, applications should never invoke these operations on child frames. By default, invoking iconify-frame on a child frame will try to iconify the top-level frame corresponding to that child frame instead. To obtain a different behavior, users may customize the option iconify-child-frame described below.
• Raising, lowering and restacking child frames (Raising and Lowering) or changing the z-group (Position Parameters) of a child frame changes only the stacking order of child frames with the same parent.
• Many window-systems are not able to change the opacity (Font and Color Parameters) of child frames.
• Transferring focus from a child frame to an ancestor that is not its parent by clicking with the mouse in a visible part of that ancestor's window may fail with some window-systems. You may have to click into the direct parent's window-system window first.
• Window managers might not bother to extend their focus follows mouse policy to child frames. Customizing mouse-autoselect-window can help in this regard (Mouse Window Auto-selection).
• Dropping (Drag and Drop) on child frames is not guaranteed to work on all window-systems. Some will drop the object on the parent frame or on some ancestor instead.

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

frame-parent

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

frame-ancestor-p

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

Note also the function window-largest-empty-rectangle (Coordinates and Windows) which can be used to inscribe a child frame in the largest empty area of an existing window. This can be useful to avoid that a child frame obscures any text shown in that window. Customizing the following option can be useful to tweak the behavior of iconify-frame for child frames.

iconify-child-frame

This option tells Emacs how to proceed when it is asked to iconify a child frame. If it is nil, iconify-frame will do nothing when invoked on a child frame. If it is iconify-top-level, Emacs will try to iconify the top-level frame that is the ancestor of this child frame instead. If it is make-invisible, Emacs will try to make this child frame invisible instead of iconifying it. Any other value means to try iconifying the child frame. Since such an attempt may not be honored by all window managers and can even lead to making the child frame unresponsive to user actions, the default is to iconify the top level frame instead.

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.

track-mouse

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

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

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

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.

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.

set-mouse-position

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

mouse-pixel-position

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

set-mouse-pixel-position

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.

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.

set-mouse-absolute-pixel-position

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:

frame-pointer-visible-p

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

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.

x-popup-menu

This function displays a pop-up menu and returns an indication of what selection the user makes. The argument position specifies where on the screen to put the top left corner of the menu. It can be either a mouse button event (which says to put the menu where the user actuated the button) or a list of this form:

((XOFFSET YOFFSET) WINDOW)

where xoffset and yoffset are coordinates, measured in pixels, counting from the top left corner of window. window may be a window or a frame. If position is t, it means to use the current mouse position (or the top-left corner of the frame if the mouse is not available on a text terminal). If position is nil, it means to precompute the key binding equivalents for the keymaps specified in menu, without actually displaying or popping up the menu. The argument menu says what to display in the menu. It can be a keymap or a list of keymaps (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 (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. 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.

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.

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.

x-popup-dialog

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

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.

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.

x-pointer-shape

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

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

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

Command gui-set-selection

This function sets a window-system selection. It takes two arguments: a selection type type, and the value to assign to it, data. type should be a symbol; it is usually one of PRIMARY, SECONDARY or CLIPBOARD. These are symbols with upper-case names, in accord with X Window System conventions. If type is nil, that stands for PRIMARY. If data is nil, it means to clear out the selection. Otherwise, data may be a string, a symbol, an integer, 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.

gui-get-selection

This function accesses selections set up by Emacs or by other programs. It takes two optional arguments, type and data-type. The default for type, the selection type, is PRIMARY. The data-type argument specifies the form of data conversion to use, to convert the raw data obtained from another program into Lisp data. Meaningful values include TEXT, STRING, UTF8_STRING, TARGETS, LENGTH, DELETE, FILE_NAME, CHARACTER_POSITION, NAME, LINE_NUMBER, COLUMN_NUMBER, OWNER_OS, HOST_NAME, USER, CLASS, ATOM, and INTEGER. (These are symbols with upper-case names in accord with X conventions.) The default for data-type is STRING. Window systems other than X usually support only a small subset of these types, in addition to STRING.

selection-coding-system

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

When Emacs runs on MS-Windows, it does not implement X selections in general, but it does support the clipboard. gui-get-selection and gui-set-selection on MS-Windows support the text data type only; if the clipboard holds other types of data, Emacs treats the clipboard as empty. The supported data type is STRING. For backward compatibility, there are obsolete aliases x-get-selection and x-set-selection, which were the names of gui-get-selection and gui-set-selection before Emacs 25.1.

If you choose, for instance, "Copy Image" in a web browser, that image is put onto the clipboard, and Emacs can access it via gui-get-selection. But in general, inserting image data into an arbitrary buffer isn't very useful—you can't really do much with it by default. So Emacs has a system to let modes register handlers for these "complicated" selections.

yank-media-handler

types can be a MIME media type symbol, a regexp to match these, 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)

A mode can register as many handlers as required. The handler function is called with two parameters: The MIME media type symbol and the data (as a string). The handler should then insert the object into the buffer, or save it, or do whatever is appropriate for the mode. The yank-media command will consult the registered handlers in the current buffer, compare that with the available media types on the clipboard, and then pass on the matching selection to the handler (if any). If there's more than one matching selection, the user is queried first. The yank-media-types command can be used to explore the clipboard/primary selection. It lists all the media types that are currently available, and can be handy when creating handlers—to see what data is actually available. Some applications put a surprising amount of different data types on the clipboard.

When the user drops something from another application over Emacs, Emacs will try to insert any text and open any URL that was dropped. If text was dropped, then it will always be inserted at the location of the mouse pointer where the drop happened, or saved in the kill ring if insertion failed, which could happen if the buffer was read-only. If a URL was dropped instead, then Emacs will first try to call an appropriate handler function by matching the URL against regexps defined in the variable dnd-protocol-alist, and then against those defined in the variables browse-url-handlers and browse-url-default-handlers. Should no suitable handler be located, Emacs will fall back to inserting the URL as plain text.

dnd-protocol-alist

This variable is a list of cons cells of the form (PATTERN . ACTION). pattern is a regexp that URLs are matched against after being dropped. action is a function that is called with two arguments, should a URL being dropped match pattern: the URL being dropped, and the action being performed for the drop, which is one of the symbols copy, move, link, private or ask. If action is private, then it means the program that initiated the drop wants Emacs to perform an unspecified action with the URL; a reasonable action to perform in that case is to open the URL or copy its contents into the current buffer. Otherwise, action has the same meaning as the action argument to dnd-begin-file-drag.

Emacs implements receiving text and URLs individually for each window system, and does not by default support receiving other kinds of data as drops. To support receiving other kinds of data, use the X-specific interface described below. When a user drags something from another application over Emacs under the X Window System, that other application expects Emacs to tell it if Emacs understands the data being dragged. The function in the variable x-dnd-test-function is called by Emacs to determine what to reply to any such inquiry. The default value is x-dnd-default-test-function, which accepts drops if the type of the data to be dropped is present in x-dnd-known-types. Changing the variables x-dnd-test-function and x-dnd-known-types can make Emacs accept or reject drops based on some other criteria. If you want to change the way Emacs receives drops of different data types, or you want to enable it to understand a new type, change the variable x-dnd-types-alist. Doing so correctly requires detailed knowledge of what data types other applications use for drag and drop. These data types are typically implemented as special data types that can be obtained from an X selection provided by the other application. In most cases, they are either the same data types that are typically accepted by gui-set-selection, or MIME types, depending on the specific drag-and-drop protocol being used. For example, the data type used for plain text may be either "STRING" or "text/plain". When Emacs runs on X window system, it supports the X Direct Save (XDS) protocol, which allows users to save a file by dragging and dropping it onto an Emacs window, such as a Dired window. To comply with the unique requirements of XDS, these drag-and-drop requests are processed specially: instead of being handled according to x-dnd-types-alist, they are handled by the direct-save function that is the value of the variable x-dnd-direct-save-function. The value should be a function of two arguments, need-name and filename. The XDS protocol uses a two-step procedure for dragging files:

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.

The default value of x-dnd-direct-save-function is x-dnd-save-direct.

x-dnd-save-direct

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 (Visiting Functions).

x-dnd-save-direct-immediately

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 (File Name Expansion). (It still asks for confirmation if a file by that name already exists in the default directory.)

On capable window systems, Emacs also supports dragging contents from its frames to windows of other applications.

dnd-begin-text-drag

This function begins dragging text from frame to another program (known as the drop target), and returns the result of drag-and-drop operation when the text is dropped or the drag-and-drop operation is canceled. text is the text that will be inserted by the drop target. 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 in addition the caller may have to delete text from its source as explained below. frame is the frame where the mouse is currently held down, or nil, which means to use the selected frame. This function may return immediately if no mouse buttons are held down, so it should be only called immediately after a down-mouse-1 or similar event (Mouse Events), with frame set to the frame where that event was generated (Click Events). allow-same-frame specifies whether or not drops on top of frame itself are to be ignored. The return value specifies the action that the drop target actually performed, and optionally what the caller should do. It can be one of the following symbols:

copy

The drop target inserted the dropped text.

move

The drop target inserted the dropped text, but in addition the caller should delete text from wherever it originated, such as its buffer.

private

The drop target performed some other unspecified action.

nil

The drag-and-drop operation was canceled.

dnd-begin-file-drag

This function begins dragging file from frame to another program, and returns the result of the drag-and-drop operation when the file is dropped or the drag-and-drop operation is canceled. If file is a remote file, then a temporary 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 have the same meaning as in dnd-begin-text-drag. The return value is the action that the drop target actually performed, which can be 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.

dnd-begin-drag-files

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.

dnd-direct-save

This function is similar to dnd-begin-file-drag (with the default action of copy), but instead of specifying the action you specify the name of the copy created by the target program in name.

The high-level interfaces described above are implemented on top of a lower-level primitive. If you need to drag content other than files or text, use the low-level interface x-begin-drag instead. However, using it will require detailed knowledge of the data types and actions used by the programs to transfer content via drag-and-drop on each platform you want to support.

x-begin-drag

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 describing selection targets, much like the data-type argument to gui-get-selection, that the drop target can request from Emacs (Window System Selections). action is a symbol describing the action recommended to the target. It can either be XdndActionCopy, which means to copy the contents of the selection XdndSelection to the drop target; or XdndActionMove, which means copy as with XdndActionCopy, and in addition the caller should delete whatever was stored in that selection after copying it. action may also be an alist which associates between symbols describing the available actions, and strings that the drop target is expected to present to the user to choose between the available 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 underneath 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 being able to drag content to other programs, but it is not guaranteed to work on all systems and with all window managers. If follow-tooltip is non-nil, the position of any tooltip (such as one shown by tooltip-show) will follow the location of the mouse pointer whenever 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 describing the action the target chose to perform, 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 means that the drop target chose to perform an unspecified action, and no further processing is required by the caller. The caller must cooperate with the target to fully perform the action chosen by the target. For example, callers should delete the buffer text that was dragged if this function returns XdndActionMove.

On X Windows, several different drag-and-drop protocols are supported by x-begin-drag. When dragging content that is known to not be supported by a specific drag-and-drop protocol, it might be desirable to turn that protocol off, by changing the values of the following variables:

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.

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.

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. If that is not desired, then the drop emulation can be disabled by setting this variable to nil.

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 (read-color).

color-defined-p

This function reports whether a color name is meaningful. It returns t if so; otherwise, nil. The argument frame says which frame's display to ask about; if frame is omitted or nil, the selected frame is used. Note that this does not tell you whether the display you are using really supports that color. When using X, you can ask for any defined color on any kind of display, and you will get some result—typically, the closest it can do. To determine whether a frame can really display a certain color, use color-supported-p (see below). This function used to be called x-color-defined-p, and that name is still supported as an alias.

defined-colors

This function returns a list of the color names that are defined and supported on frame frame (default, the selected frame). If frame does not support colors, the value is nil. This function used to be called x-defined-colors, and that name is still supported as an alias.

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

color-gray-p

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.

color-values

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. This function used to be called x-color-values, and that name is still supported as an alias.

color-name-to-rgb

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

color-dark-p

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.

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; Input Focus). At present, though, the frame argument has no effect.

tty-color-define

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.

tty-color-clear

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

tty-color-alist

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.

tty-color-approximate

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.

tty-color-translate

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.

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

x-get-resource

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.

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.

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"

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.

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, Input Focus). Color Names, Text Terminal Colors, for other functions to obtain information about displays.

display-popup-menus-p

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.

display-graphic-p

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.

display-mouse-p

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

display-color-p

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

display-grayscale-p

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

display-supports-face-attributes-p

This function returns non-nil if all the face attributes in attributes are supported (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.

display-selections-p

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

display-images-p

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.

display-screens

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

display-pixel-height

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

display-pixel-width

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

display-mm-height

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

display-mm-width

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

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.

display-backing-store

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.

display-save-under

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.

display-planes

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.

display-visual-class

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

display-color-cells

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

x-server-version

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.

x-server-vendor

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.