Go to the first, previous, next, last section, table of contents.


Frames

A frame is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window), which you can subdivide vertically or horizontally into smaller windows.

When Emacs runs on a text-only terminal, it starts with one terminal frame. If you create additional ones, Emacs displays one and only one at any given time--on the terminal screen, of course.

When Emacs communicates directly with a supported window system, such as X Windows, it does not have a terminal frame; instead, it starts with a single window frame, but you can create more, and Emacs can display several such frames at once as is usual for window systems.

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

See section Emacs Display, for information about the related topic of controlling Emacs redisplay.

Creating Frames

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

Function: make-frame &optional alist
This function creates a new frame. If you are using a supported window system, it makes a window frame; otherwise, it makes a terminal frame.

The argument is an alist specifying frame parameters. Any parameters not mentioned in alist default according to the value of the variable default-frame-alist; parameters not specified even there default from the standard X resources or whatever is used instead on your system.

The set of possible parameters depends in principle on what kind of window system Emacs uses to display its frames. See section Window Frame Parameters, for documentation of individual parameters you can specify.

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

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

Multiple Displays

A single Emacs can talk to more than one X display. Initially, Emacs uses just one display--the one chosen with the DISPLAY environment variable or with the `--display' option (see section `Initial Options' in The GNU Emacs Manual). To connect to another display, use the command make-frame-on-display or specify the display frame parameter when you create the frame.

Emacs treats each X server as a separate terminal, giving each one its own selected frame and its own minibuffer windows.

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

A single X server can handle more than one screen. A display name `host:server.screen' has three parts; the last part specifies the screen number for a given server. When you use two screens belonging to one server, Emacs knows by the similarity in their names that they share a single keyboard, and it treats them as a single terminal.

Command: make-frame-on-display display &optional parameters
This creates a new frame on display display, taking the other frame parameters from parameters. Aside from the display argument, it is like make-frame (see section Creating Frames).

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

Function: x-open-connection display &optional xrm-string
This function opens a connection to the X display display. It does not create a frame on that display, but it permits you to check that communication can be established with that 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. The values you specify override the resource values recorded in the X server itself; they apply to all Emacs frames created on this display. Here's an example of what this string might look like:

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

See section X Resources.

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

Frame Parameters

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

Frame parameters exist for the sake of window systems. A terminal frame has a few parameters, mostly for compatibility's sake; only the height, width, name, title, buffer-list and buffer-predicate parameters do something special.

Access to Frame Parameters

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

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

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

Initial Frame Parameters

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

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

(parameter . value)

Emacs creates the initial frame before it reads your `~/.emacs' file. After reading that file, Emacs checks initial-frame-alist, and applies the parameter settings in the altered value to the already created initial frame.

If these settings affect the frame geometry and appearance, you'll see the frame appear with the wrong ones and then change to the specified ones. If that bothers you, you can specify the same geometry and appearance with X resources; those do take affect before the frame is created. See section `X Resources' in The GNU Emacs Manual.

X resource settings typically apply to all frames. If you want to specify some X resources solely for the sake of the initial frame, and you don't want them to apply to subsequent frames, here's how to achieve this. Specify parameters in default-frame-alist to override the X resources for subsequent frames; then, to prevent these from affecting the initial frame, specify the same parameters in initial-frame-alist with values that match the X resources.

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

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

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

See also special-display-frame-alist, in section Choosing a Window for Display.

If you use options that specify window appearance when you invoke Emacs, they take effect by adding elements to default-frame-alist. One exception is `-geometry', which adds the specified position to initial-frame-alist instead. See section `Command Arguments' in The GNU Emacs Manual.

Window Frame Parameters

Just what parameters a frame has depends on what display mechanism it uses. Here is a table of the parameters that have special meanings in a window frame; of these, name, title, height, width, buffer-list and buffer-predicate provide meaningful information in terminal frames.

display
The display on which to open this frame. It should be a string of the form "host:dpy.screen", just like the DISPLAY environment variable.
title
If a frame has a non-nil title, it appears in the window system's border for the frame, and also in the mode line of windows in that frame if mode-line-frame-identification uses `%F' (see section %-Constructs in the Mode Line). This is normally the case when Emacs is not using a window system, and can only display one frame at a time. See section Frame Titles.
name
The name of the frame. The frame name serves as a default for the frame title, if the title parameter is unspecified or nil. If you don't specify a name, Emacs sets the frame name automatically (see section Frame Titles). If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame.
left
The screen position of the left edge, in pixels, with respect to the left edge of the screen. The value may be a positive number pos, or a list of the form (+ pos) which permits specifying a negative pos value. A negative number -pos, or a list of the form (- pos), actually specifies the position of the right edge of the window with respect to the right edge of the screen. A positive value of pos counts toward the left. Reminder: if the parameter is a negative integer -pos, then pos is positive. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as well.
top
The screen position of the top edge, in pixels, with respect to the top edge of the screen. The value may be a positive number pos, or a list of the form (+ pos) which permits specifying a negative pos value. A negative number -pos, or a list of the form (- pos), actually specifies the position of the bottom edge of the window with respect to the bottom edge of the screen. A positive value of pos counts toward the top. Reminder: if the parameter is a negative integer -pos, then pos is positive. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as well.
icon-left
The screen position of the left edge of the frame's icon, in pixels, counting from the left edge of the screen. This takes effect if and when the frame is iconified.
icon-top
The screen position of the top edge of the frame's icon, in pixels, counting from the top edge of the screen. This takes effect if and when the frame is iconified.
user-position
When you create a frame and specify its screen position with the left and top parameters, use this parameter to say whether the specified position was user-specified (explicitly requested in some way by a human user) or merely program-specified (chosen by a program). A non-nil value says the position was user-specified. Window managers generally heed user-specified positions, and some heed program-specified positions too. But many ignore program-specified positions, placing the window in a default fashion or letting the user place it with the mouse. Some window managers, including twm, let the user specify whether to obey program-specified positions or ignore them. When you call make-frame, you should specify a non-nil value for this parameter if the values of the left and top parameters represent the user's stated preference; otherwise, use nil.
height
The height of the frame contents, in characters. (To get the height in pixels, call frame-pixel-height; see section Frame Size And Position.)
width
The width of the frame contents, in characters. (To get the height in pixels, call frame-pixel-width; see section Frame Size And Position.)
window-id
The number of the window-system window used by the frame.
minibuffer
Whether this frame has its own minibuffer. The value t means yes, nil means no, only means this frame is just a minibuffer. If the value is a minibuffer window (in some other frame), the new frame uses that minibuffer.
buffer-predicate
The buffer-predicate function for this frame. The function other-buffer uses this predicate (from the selected frame) to decide which buffers it should consider, if the predicate is not nil. It calls the predicate with one argument, a buffer, once for each buffer; if the predicate returns a non-nil value, it considers that buffer.
buffer-list
A list of buffers that have been selected in this frame, ordered most-recently-selected first.
font
The name of the font for displaying text in the frame. This is a string, either a valid font name for your system or the name of an Emacs fontset (see section Fontsets).
auto-raise
Whether selecting the frame raises it (non-nil means yes).
auto-lower
Whether deselecting the frame lowers it (non-nil means yes).
vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are left, right, and nil for no scroll bars.
horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling (non-nil means yes). (Horizontal scroll bars are not currently implemented.)
scroll-bar-width
The width of the vertical scroll bar, in pixels.
icon-type
The type of icon to use for this frame when it is iconified. If the value is a string, that specifies a file containing a bitmap to use. Any other non-nil value specifies the default bitmap icon (a picture of a gnu); nil specifies a text icon.
icon-name
The name to use in the icon for this frame, when and if the icon appears. If this is nil, the frame's title is used.
foreground-color
The color to use for the image of a character. This is a string; the window system defines the meaningful color names. If you set the foreground-color frame parameter, you should call frame-update-face-colors to update faces accordingly.
background-color
The color to use for the background of characters. If you set the background-color frame parameter, you should call frame-update-face-colors to update faces accordingly. See section Functions for Working with Faces.
background-mode
This parameter is either dark or light, according to whether the background color is a light one or a dark one.
mouse-color
The color for the mouse pointer.
cursor-color
The color for the cursor that shows point.
border-color
The color for the border of the frame.
display-type
This parameter describes the range of possible colors that can be used in this frame. Its value is color, grayscale or mono.
cursor-type
The way to display the cursor. The legitimate values are bar, box, and (bar . width). The symbol box specifies an ordinary black box overlaying the character after point; that is the default. The symbol bar specifies a vertical bar between characters as the cursor. (bar . width) specifies a bar width pixels wide.
border-width
The width in pixels of the window border.
internal-border-width
The distance in pixels between text and border.
unsplittable
If non-nil, this frame's window is never split automatically.
visibility
The state of visibility of the frame. There are three possibilities: nil for invisible, t for visible, and icon for iconified. See section Visibility of Frames.
menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar. The default is 1. See section The Menu Bar. (In Emacs versions that use the X toolkit, there is only one menu bar line; all that matters about the number you specify is whether it is greater than zero.)

Frame Size And Position

You can read or change the size and position of a frame using the frame parameters left, top, height, and width. Whatever geometry parameters you don't specify are chosen by the window manager in its usual fashion.

Here are some special features for working with sizes and positions:

Function: set-frame-position frame left top
This function sets the position of the top left corner of frame to left and top. These arguments are measured in pixels, and normally count from the top left corner of the screen.

Negative parameter values position the bottom edge of the window up from the bottom edge of the screen, or the right window edge to the left of the right edge of the screen. It would probably be better if the values were always counted from the left and top, so that negative arguments would position the frame partly off the top or left edge of the screen, but it seems inadvisable to change that now.

Function: frame-height &optional frame
Function: frame-width &optional frame
These functions return the height and width of frame, measured in lines and columns. If you don't supply frame, they use the selected frame.

Function: screen-height
Function: screen-width
These functions are old aliases for frame-height and frame-width. When you are using a non-window terminal, the size of the frame is normally the same as the size of the terminal screen.

Function: frame-pixel-height &optional frame
Function: frame-pixel-width &optional frame
These functions return the height and width of frame, measured in pixels. If you don't supply frame, they use the selected frame.

Function: frame-char-height &optional frame
Function: frame-char-width &optional frame
These functions return the height and width of a character in frame, measured in pixels. The values depend on the choice of font. If you don't supply frame, these functions use the selected frame.

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

To set the size based on values measured in pixels, use frame-char-height and frame-char-width to convert them to units of characters.

Function: set-frame-height frame lines &optional pretend
This function resizes frame to a height of lines lines. The sizes of existing windows in frame are altered proportionally to fit.

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

Function: set-frame-width frame width &optional pretend
This function sets the width of frame, measured in characters. The argument pretend has the same meaning as in set-frame-height.

The older functions set-screen-height and set-screen-width were used to specify the height and width of the screen, in Emacs versions that did not support multiple frames. They are semi-obsolete, but still work; they apply to the selected frame.

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

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

For the size parameters, the value must be an integer. The position parameter names left and top are not totally accurate, because some values indicate the position of the right or bottom edges instead. These are the value possibilities for the position parameters:

an integer
A positive integer relates the left edge or top edge of the window to the left or top edge of the screen. A negative integer relates the right or bottom edge of the window to the right or bottom edge of the screen.
(+ position)
This specifies the position of the left or top edge of the window relative to the left or top edge of the screen. The integer position may be positive or negative; a negative value specifies a position outside the screen.
(- position)
This specifies the position of the right or bottom edge of the window relative to the right or bottom edge of the screen. The integer position may be positive or negative; a negative value specifies a position outside the screen.

Here is an example:

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

Frame Titles

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

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

Variable: frame-title-format
This variable specifies how to compute a name for a frame when you have not explicitly specified one. The variable's value is actually a mode line construct, just like mode-line-format. See section The Data Structure of the Mode Line.

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

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

Deleting Frames

Frames remain potentially visible until you explicitly delete them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a frame aside from restoring a saved frame configuration (see section Frame Configurations); this is similar to the way windows behave.

Command: delete-frame &optional frame
This function deletes the frame frame. By default, frame is the selected frame.

Function: frame-live-p frame
The function frame-live-p returns non-nil if the frame frame has not been deleted.

Some window managers provide a command to delete a window. These work by sending a special message to the program that operates the window. When Emacs gets one of these commands, it generates a delete-frame event, whose normal definition is a command that calls the function delete-frame. See section Miscellaneous Window System Events.

Finding All Frames

Function: frame-list
The function frame-list returns a list of all the frames that have not been deleted. It is analogous to buffer-list for buffers. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of Emacs.

Function: visible-frame-list
This function returns a list of just the currently visible frames. See section Visibility of Frames. (Terminal frames always count as "visible", even though only the selected one is actually displayed.)

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

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

nil
Exclude minibuffer-only frames.
visible
Consider all visible frames.
0
Consider all visible or iconified frames.
a window
Consider only the frames using that particular window as their minibuffer.
anything else
Consider all frames.

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

See also next-window and previous-window, in section Cyclic Ordering of Windows.

Frames and Windows

Each window is part of one and only one frame; you can get the frame with window-frame.

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

All the non-minibuffer windows in a frame are arranged in a cyclic order. The order runs from the frame's top window, which is at the upper left corner, down and to the right, until it reaches the window at the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top. See section Cyclic Ordering of Windows.

Function: frame-top-window frame
This returns the topmost, leftmost window of frame frame.

At any time, exactly one window on any frame is selected within the frame. The significance of this designation is that selecting the frame also selects this window. You can get the frame's current selected window with frame-selected-window.

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

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

Another function that (usually) returns one of the windows in a given frame is minibuffer-window. See section Minibuffer Miscellany.

Minibuffers and Frames

Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. If the frame has a minibuffer, you can get it with minibuffer-window (see section Minibuffer Miscellany).

However, you can also create a frame with no minibuffer. Such a frame must use the minibuffer window of some other frame. When you create the frame, you can specify explicitly the minibuffer window to use (in some other frame). If you don't, then the minibuffer is found in the frame which is the value of the variable default-minibuffer-frame. Its value should be a frame that does have a minibuffer.

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

Variable: default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by default. It is always local to the current terminal and cannot be buffer-local. See section Multiple Displays.

Input Focus

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

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

Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to shift the focus to various window objects. Either way, Emacs automatically keeps track of which frame has the focus.

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

When using a text-only terminal, only the selected terminal frame is actually displayed on the terminal. switch-frame is the only way to switch frames, and the change lasts until overridden by a subsequent call to switch-frame. Each terminal screen except for the initial one has a number, and the number of the selected frame appears in the mode line before the buffer name (see section Variables Used in the Mode Line).

Function: select-frame frame
This function selects frame frame, temporarily disregarding the focus of the X server if any. The selection of frame lasts until the next time the user does something to select a different frame, or until the next time this function is called.

Emacs cooperates with the window system by arranging to select frames as the server and window manager request. It does so by generating a special kind of input event, called a focus event, when appropriate. The command loop handles a focus event by calling handle-switch-frame. See section Focus Events.

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

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

Function: redirect-frame-focus frame focus-frame
This function redirects focus from frame to focus-frame. This means that focus-frame will receive subsequent keystrokes and 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 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.

User Option: focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers focus when the user moves the mouse. Non-nil says that it does. When this is so, the command other-frame moves the mouse to a position consistent with the new selected frame.

Visibility of Frames

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

Visibility is meaningless for terminal frames, since only the selected one is actually displayed in any case.

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

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

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

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

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

The user can iconify and deiconify frames with the window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. See section Miscellaneous Window System Events.

Raising and Lowering Frames

Most window systems use a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from "highest" to "lowest". Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it.

A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. Raising a window means moving it "up", to the top of the stack. Lowering a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen.

You can raise and lower Emacs frame Windows with these functions:

Command: raise-frame &optional frame
This function raises frame frame (default, the selected frame).

Command: lower-frame &optional frame
This function lowers frame frame (default, the selected frame).

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

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

Frame Configurations

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

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

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

Mouse Tracking

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

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

Special Form: track-mouse body...
This special form executes body, with generation of mouse motion events enabled. Typically body would use read-event to read the motion events and modify the display accordingly. See section Motion Events, for the format of mouse motion events.

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

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

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

Mouse Position

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

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

Function: set-mouse-position frame x y
This function warps the mouse to position x, y in frame frame. The arguments x and y are integers, giving the position in characters relative to the top left corner of the inside of frame. If frame is not visible, this function does nothing. The return value is not significant.

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

Function: set-mouse-pixel-position frame x y
This function warps the mouse like set-mouse-position except that x and y are in units of pixels rather than units of characters. These coordinates are not required to be within the frame.

If frame is not visible, this function does nothing. The return value is not significant.

Pop-Up Menus

When using a window system, a Lisp program can pop up a menu so that the user can choose an alternative with the mouse.

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

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

((xoffset yoffset) window)

where xoffset and yoffset are coordinates, measured in pixels, counting from the top left corner of window's frame.

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

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

(title pane1 pane2...)

where each pane is a list of form

(title (line . item)...)

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

Usage note: Don't use x-popup-menu to display a menu if you could do the job with a prefix key defined with a menu keymap. If you use a menu keymap to implement a menu, C-h c and C-h a can see the individual items in that menu and provide help for them. If instead you implement the menu by defining a command that calls x-popup-menu, the help facilities cannot know what happens inside that command, so they cannot give any help for the menu's items.

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

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

Dialog Boxes

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

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

(title (string . value)...)

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

The return value is value from the chosen alternative.

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 don't matter; only the frame matters.

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.

Pointer Shapes

These variables specify which shape to use for the mouse pointer in various situations, when using the X Window System:

x-pointer-shape
This variable specifies the pointer shape to use ordinarily in the Emacs frame.
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 updates its pointer shapes based on the current values of these variables. See section Window Frame 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.

Window System Selections

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

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

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

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

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

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

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

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

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

Variable: selection-coding-system
This variable specifies the coding system to use when reading and writing a selections, the clipboard, or a cut buffer. See section Coding Systems. The default is compound-text.

Looking up Font Names

Function: x-list-font pattern &optional face frame maximum
This function returns a list of available font names that match pattern. If the optional arguments face and frame are specified, then the list is limited to fonts that are the same size as face currently is on frame.

The argument pattern should be a string, perhaps with wildcard characters: the `*' character matches any substring, and the `?' character matches any single character. Pattern matching of font names ignores case.

If you specify face and frame, face should be a face name (a symbol) and frame should be a frame.

The optional argument maximum sets a limit on how many fonts to return. If this is non-nil, then the return value is truncated after the first maximum matching fonts. Specifying a small value for maximum can make this function much faster, in cases where many fonts match the pattern.

Fontsets

A fontset is a list of fonts, each assigned to a range of character codes. An individual font cannot display the whole range of characters that Emacs supports, but a fontset can. Fontsets have names, just as fonts do, and you can use a fontset name in place of a font name when you specify the "font" for a frame or a face. Here is information about defining a fontset under Lisp program control.

Function: create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
This function defines a new fontset according to the specification string fontset-spec. The string should have this format:

fontpattern, [charsetname:fontname]...

Whitespace characters before and after the commas are ignored.

The first part of the string, fontpattern, should have the form of a standard X font name, except that the last two fields should be `fontset-alias'.

The new fontset has two names, one long and one short. The long name is fontpattern in its entirety. The short name is `fontset-alias'. You can refer to the fontset by either name. If a fontset with the same name already exists, an error is signaled, unless noerror is non-nil, in which case this function does nothing.

If optional argument style-variant-p is non-nil, that says to create bold, italic and bold-italic variants of the fontset as well. These variant fontsets do not have a short name, only a long one, which is made by altering fontpattern to indicate the bold or italic status.

The specification string also says which fonts to use in the fontset. See below for the details.

The construct `charset:font' specifies which font to use (in this fontset) for one particular character set. Here, charset is the name of a character set, and font is the font to use for that character set. You can use this construct any number of times in the specification string.

For the remaining character sets, those that you don't specify explicitly, Emacs chooses a font based on fontpattern: it replaces `fontset-alias' with a value that names one character set. For the ASCII character set, `fontset-alias' is replaced with `ISO8859-1'.

In addition, when several consecutive fields are wildcards, Emacs collapses them into a single wildcard. This is to prevent use of auto-scaled fonts. Fonts made by scaling larger fonts are not usable for editing, and scaling a smaller font is not useful because it is better to use the smaller font in its own size, which Emacs does.

Thus if fontpattern is this,

-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

the font specification for ASCII characters would be this:

-*-fixed-medium-r-normal-*-24-*-ISO8859-1

and the font specification for Chinese GB2312 characters would be this:

-*-fixed-medium-r-normal-*-24-*-gb2312*-*

You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that have `song ti' or `fangsong ti' in the family field. In such a case, `Fontset-n' can be specified as below:

Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

Then, the font specifications for all but Chinese GB2312 characters have `fixed' in the family field, and the font specification for Chinese GB2312 characters has a wild card `*' in the family field.

Color Names

Function: x-color-defined-p color &optional frame
This function reports whether a color name is meaningful. It returns t if so; otherwise, nil. The argument frame says which frame's display to ask about; if frame is omitted or nil, the selected frame is used.

Note that this does not tell you whether the display you are using really supports that color. You can ask for any defined color on any kind of display, and you will get some result--that is how the X server works. Here's an approximate way to test whether your display supports the color color:

(defun x-color-supported-p (color &optional frame)
  (and (x-color-defined-p color frame)
       (or (x-display-color-p frame)
           (member color '("black" "white"))
           (and (> (x-display-planes frame) 1)
                (equal color "gray")))))

Function: x-color-values color &optional frame
This function returns a value that describes what color should ideally look like. 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 in practice no value seems to be above 65280. If color is not defined, the value is nil.

(x-color-values "black")
     => (0 0 0)
(x-color-values "white")
     => (65280 65280 65280)
(x-color-values "red")
     => (65280 0 0)
(x-color-values "pink")
     => (65280 49152 51968)
(x-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.

X Resources

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

Resources are indexed by a combination of a key and a class. This function searches using a key of the form `instance.attribute' (where instance is the name under which Emacs was invoked), and using `Emacs.class' as the class.

The optional arguments component and subclass add to the key and the class, respectively. You must specify both of them or neither. If you specify them, the key is `instance.component.attribute', and the class is `Emacs.class.subclass'.

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

See section `X Resources' in The GNU Emacs Manual.

Data about the X Server

This section describes functions you can use to get information about the capabilities and origin of an X display that Emacs is using. Each of these functions lets you specify the display you are interested in: the display argument can be either a display name, or a frame (meaning use the display that frame is on). If you omit the display argument, or specify nil, that means to use the selected frame's display.

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

Function: x-server-version &optional display
This function returns the list of version numbers of the X server running the display.

Function: x-server-vendor &optional display
This function returns the vendor that provided the X server software.

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

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

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

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

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

Function: x-display-save-under &optional display
This function returns non-nil if the display supports the SaveUnder feature.

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

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

Function: x-display-grayscale-p &optional display
This function returns t if the screen can display shades of gray.

Function: x-display-color-p &optional display
This function returns t if the screen is a color screen.

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


Go to the first, previous, next, last section, table of contents.