Frames
******

A frame is a screen object that contains one or more Emacs windows (see Windows).  It is the kind of object called a ``window'' in the terminology of graphical environments; but we can't call it a ``window'' here, because Emacs uses that word in a different way.  In Emacs Lisp, a frame object is a Lisp object that represents a frame on the screen.  See Frame Type.

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

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

There are two classes of terminals: text-only terminals and graphical terminals.  Text-only terminals are non-graphics-capable display devices, including ``terminal emulators'' such as xterm.  On text-only terminals, each frame occupies the entire terminal screen; although you can create additional frames and switch between them, only one frame can be shown at any given time.  We refer to frames on text-only terminals as terminal frames.  Graphical terminals, on the other hand, are graphics-capable windowing systems, such as the X Window System.  On a graphical terminal, Emacs can display multiple frames simultaneously.  We refer to such frames as window frames.

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

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

     x
          The frame is displayed in an X window.

     t
          A terminal frame on a character display.

     w32
          The frame is displayed on MS-Windows 9X/NT.

     ns
          The frame is displayed on a GNUstep or Macintosh Cocoa display.

     pc
          The frame is displayed on an MS-DOS terminal.

 -- Function: frame-terminal &optional frame
     This function returns the terminal object that displays FRAME. If FRAME is nil or unspecified, it defaults to the selected frame.

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

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

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

 -- Function: make-frame &optional alist
     This function creates and returns a new frame, displaying the current buffer.

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

     Any parameters not mentioned in ALIST default to the values in the alist default-frame-alist (see Initial Parameters); parameters not specified there default from the X resources or its equivalent on your operating system (see X Resources (The GNU Emacs Manual)).  After the frame is created, Emacs applies any parameters listed in frame-inherited-parameters (see below) and not present in the argument, taking the values from the frame that was selected when make-frame was called.

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

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

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

 -- Variable: frame-inherited-parameters
     This variable specifies the list of frame parameters that a newly created frame inherits from the currently selected frame.  For each parameter (a symbol) that is an element in the list and is not present in the argument to make-frame, the function sets the value of that parameter in the created frame to its value in the selected frame.

Multiple Terminals
==================

Emacs represents each terminal, whether graphical or text-only, as a terminal object data type (see Terminal Type).  On GNU and Unix systems, Emacs can use multiple terminals simultaneously in each session.  On other systems, it can only use a single terminal.  Each terminal object has the following attributes:

  * The name of the device used by the terminal (e.g., :0.0 or /dev/tty).

  * The terminal and keyboard coding systems used on the terminal. See Terminal I/O Encoding.

  * The kind of display associated with the terminal.  This is the symbol returned by the function terminal-live-p (i.e., x, t, w32, ns, or pc).  See Frames.

  * A list of terminal parameters.  See Terminal Parameters.

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

 -- Function: terminal-name &optional terminal
     This function returns the file name of the device used by TERMINAL.  If TERMINAL is omitted or nil, it defaults to the selected frame's terminal.  TERMINAL can also be a frame, meaning that frame's terminal.

 -- Function: terminal-list
     This function returns a list of all terminal objects currently in use.

 -- Function: get-device-terminal device
     This function returns a terminal whose device name is given by DEVICE.  If DEVICE is a string, it can be either the file name of a terminal device, or the name of an X display of the form HOST:SERVER.SCREEN.  If DEVICE is a frame, this function returns that frame's terminal; nil means the selected frame.  Finally, if DEVICE is a terminal object that represents a live terminal, that terminal is returned.  The function signals an error if its argument is none of the above.

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

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

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

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

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

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

A single X server can handle more than one display.  Each X display has a three-part name, HOST:SERVER.SCREEN. The first two parts, HOST and SERVER, identify the X server; the third part, SCREEN, identifies a screen number 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.

On some ``multi-monitor'' setups, a single X display outputs to more than one monitor.  Currently, there is no way for Emacs to distinguish between the different physical monitors.

 -- Command: make-frame-on-display display &optional parameters
     This function creates and returns a new frame on DISPLAY, taking the other frame parameters from the alist PARAMETERS. DISPLAY should be the name of an X display (a string).

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

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

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

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

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

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

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

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

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

Frame parameters exist mostly for the sake of window systems.  A terminal frame has a few parameters, mostly for compatibility's sake; 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.

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

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

 -- Function: frame-parameter frame parameter
     This function returns the value of the parameter PARAMETER (a symbol) of FRAME.  If FRAME is nil, it returns the selected frame's parameter.  If FRAME has no setting for PARAMETER, this function returns nil.

 -- Function: frame-parameters &optional frame
     The function frame-parameters returns an alist listing all the parameters of FRAME and their values.  If FRAME is nil or omitted, this returns the selected frame's parameters

 -- Function: modify-frame-parameters frame alist
     This function alters the 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.  If FRAME is nil, it defaults to the selected frame.

 -- Function: set-frame-parameter frame parm value
     This function sets the frame parameter PARM to the specified VALUE.  If FRAME is nil, it defaults to the selected frame.

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

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

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

 -- User Option: 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 init file.  After reading that file, Emacs checks initial-frame-alist, and applies the parameter settings in the altered value to the already created initial frame.

     If these settings affect the frame geometry and appearance, you'll see the frame appear with the wrong ones and then change to the specified ones.  If that bothers you, you can specify the same geometry and appearance with X resources; those do take effect before the frame is created.  See X Resources (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.

 -- User Option: minibuffer-frame-alist
     This variable's value is an alist of parameter values used when creating an initial minibuffer-only frame.  This is the minibuffer-only frame that Emacs creates if initial-frame-alist specifies a frame with no minibuffer.

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

     Setting this variable does not affect existing frames.

Functions that display a buffer in a separate frame can override the default parameters by supplying their own parameters.  See Definition of special-display-frame-alist.

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 Command Line Arguments for Emacs Invocation (The GNU Emacs Manual).

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

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

Basic Parameters
................

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

display
     The display on which to open this frame.  It should be a string of the form "HOST:DPY.SCREEN", just like the DISPLAY environment variable.

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

title
     If a frame has a non-nil title, it appears in the window system's title bar at the top of the frame, and also in the mode line of windows in that frame if mode-line-frame-identification uses %F (see %-Constructs).  This is normally the case when Emacs is not using a window system, and can only display one frame at a time.  See 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 Frame Titles).

     If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame.

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

Position Parameters
...................

Position parameters' values are normally measured in pixels, but on text-only terminals they count characters or lines instead.

left
     The position, in pixels, of the left (or right) edge of the frame with respect to the left (or right) edge of the screen.  The value may be:

     an integer
          A positive integer relates the left edge of the frame to the left edge of the screen.  A negative integer relates the right frame edge to the right screen edge.

     (+ POS)
          This specifies the position of the left frame edge relative to the left screen edge.  The integer POS may be positive or negative; a negative value specifies a position outside the screen.

     (- POS)
          This specifies the position of the right frame edge relative to the right screen edge.  The integer POS may be positive or negative; a negative value specifies a position outside the screen.

     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 (or bottom) edge, in pixels, with respect to the top (or bottom) edge of the screen.  It works just like left, except vertically instead of horizontally.

icon-left
     The screen position of the left edge of the frame's icon, in pixels, counting from the left edge of the screen.  This takes effect if and when the frame is iconified.

     If you specify a value for this parameter, then you must also specify a value for icon-top and vice versa.  The window manager may ignore these two parameters.

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.

Size Parameters
...............

Size parameters' values are normally measured in pixels, but on text-only terminals they count characters or lines instead.

height
     The height of the frame contents, in characters.  (To get the height in pixels, call frame-pixel-height; see Size and Position.)

width
     The width of the frame contents, in characters.  (To get the width in pixels, call frame-pixel-width; see Size and Position.)

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

fullscreen
     Specify that width, height or both shall be maximized.  The value fullwidth specifies that width shall be as wide as possible. The value fullheight specifies that height shall be as tall as possible.  The value fullboth specifies that both the width and the height shall be set to the size of the screen.  The value maximized specifies that the frame shall be maximized.  The difference between maximized and fullboth is that the former still has window manager decorations while the latter really covers the whole screen.

Layout Parameters
.................

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

border-width
     The width in pixels of the frame's border.

internal-border-width
     The distance in pixels between text (or fringe) and the frame's border.

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.

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

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

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

     The combined fringe widths must add up to an integral number of columns, so the actual default fringe widths for the frame, as reported by frame-parameter, may be larger than what you specify.  Any extra width is distributed evenly between the left and right fringe.  However, you can force one fringe or the other to a precise width by specifying that width as a negative integer.  If both widths are negative, only the left fringe gets the specified width.

menu-bar-lines
     The number of lines to allocate at the top of the frame for a menu bar.  The default is 1 if Menu Bar mode is enabled, and 0 otherwise. See Menu Bars (The GNU Emacs Manual).

tool-bar-lines
     The number of lines to use for the tool bar.  The default is 1 if Tool Bar mode is enabled, and 0 otherwise.  See Tool Bars (The GNU Emacs Manual).

tool-bar-position
     The position of the tool bar.  Currently only for the GTK tool bar. Value can be one of top, bottom left, right. The default is  top.

line-spacing
     Additional space to leave below each text line, in pixels (a positive integer).  See Line Height, for more information.

Buffer Parameters
.................

These frame parameters, meaningful on all kinds of terminals, deal with which buffers have been, or should, be displayed in the frame.

minibuffer
     Whether this frame has its own minibuffer.  The value t means yes, nil means no, only means this frame is just a minibuffer.  If the value is a minibuffer window (in some other frame), the frame uses that minibuffer.

     This frame parameter takes effect when the frame is created, and can not be changed afterwards.

buffer-predicate
     The buffer-predicate function for this frame.  The function other-buffer uses this predicate (from the selected frame) to decide which buffers it should consider, if the predicate is not nil.  It calls the predicate with one argument, a buffer, once for each buffer; if the predicate returns a non-nil value, it considers that buffer.

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

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

Window Management Parameters
............................

These frame parameters, meaningful only on window system displays, interact with the window manager.

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

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

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

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

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

window-id
     The number of the window-system window used by the frame to contain the actual Emacs windows.

outer-window-id
     The number of the outermost window-system window used for the whole frame.

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

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

Cursor Parameters
.................

This frame parameter controls the way the cursor looks.

cursor-type
     How to display the cursor.  Legitimate values are:

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

     hollow
          Display a hollow box.

     nil
          Don't display a cursor.

     bar
          Display a vertical bar between characters.

     (bar . WIDTH)
          Display a vertical bar WIDTH pixels wide between characters.

     hbar
          Display a horizontal bar.

     (hbar . HEIGHT)
          Display a horizontal bar HEIGHT pixels high.

The buffer-local variable cursor-type overrides the value of the cursor-type frame parameter, but if it is t, that means to use the cursor specified for the frame.

 -- User Option: blink-cursor-alist
     This variable specifies how to blink the cursor.  Each element has the form (ON-STATE . OFF-STATE).  Whenever the cursor type equals ON-STATE (comparing using equal), the corresponding OFF-STATE specifies what the cursor looks like when it blinks ``off.''  Both ON-STATE and OFF-STATE should be suitable values for the cursor-type frame parameter.

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

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

Font and Color Parameters
.........................

These frame parameters control the use of fonts and colors.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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. (For the precise meaning of ``selected frame'' used by these functions, see Input Focus.)

 -- 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: frame-pixel-height &optional frame
 -- Function: frame-pixel-width &optional frame
     These functions return the height and width of the main display area of FRAME, measured in pixels.  If you don't supply FRAME, they use the selected frame.  For a text-only terminal, the results are in characters rather than pixels.

     These values include the internal borders, and windows' scroll bars and fringes (which belong to individual windows, not to the frame itself). The exact value of the heights depends on the window-system and toolkit in use.  With Gtk+, the height does not include any tool bar or menu bar.  With the Motif or Lucid toolkits, it includes the tool bar but not the menu bar.  In a graphical version with no toolkit, it includes both the tool bar and menu bar.  For a text-only terminal, the result includes the menu bar.

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

Geometry
--------

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

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

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

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

     Here is an example:

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

Terminal Parameters
===================

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

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

 -- Function: terminal-parameters &optional terminal
     This function returns an alist listing all the parameters of TERMINAL and their values.

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

 -- Function: set-terminal-parameter terminal parameter value
     This function sets the parameter PARM of TERMINAL to the specified VALUE, and returns the previous value of that parameter.

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

background-mode
     The classification of the terminal's background color, either light or dark.

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

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

Frame Titles
============

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

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

 -- Variable: frame-title-format
     This variable specifies how to compute a name for a frame when you have not explicitly specified one.  The variable's value is actually a mode line construct, just like mode-line-format, except that the %c and %l constructs are ignored.  See Mode Line Data.

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

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

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

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.

 -- Command: delete-frame &optional frame force
     This function deletes the frame FRAME.  Unless FRAME is a tooltip, it first runs the hook delete-frame-functions (each function gets one argument, FRAME).  By default, FRAME is the selected frame.

     A frame cannot be deleted if its minibuffer is used by other frames. Normally, you cannot delete a frame if all other frames are invisible, but if FORCE is non-nil, then you are allowed to do so.

 -- Function: frame-live-p frame
     The function frame-live-p returns non-nil if the frame FRAME has not been deleted.  The possible non-nil return values are like those of framep.  See Frames.

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

Finding All Frames
==================

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

 -- Function: visible-frame-list
     This function returns a list of just the currently visible frames. See 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 on the current display 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 (see Input Focus).

     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 Cyclic Window Ordering.

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 Definition of minibuffer-window).

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

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

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

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

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

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

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

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

When using a text-only 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 terminal frame has a number which appears in the mode line before the buffer name (see Mode Line Variables).

 -- Function: select-frame-set-input-focus frame
     This function selects FRAME, raises it (should it happen to be obscured by other frames) and tries to give it the X server's focus.  On a text-only terminal, the next redisplay displays the new frame on the entire terminal screen.  The return value of this function is not significant.

 -- Function: select-frame frame &optional norecord
     This function selects frame FRAME, temporarily disregarding the focus of the X server if any.  The selection of FRAME lasts until the next time the user does something to select a different frame, or until the next time this function is called.  (If you are using a window system, the previously selected frame may be restored as the selected frame after return to the command loop, because it still may have the window system's input focus.)

     The specified FRAME becomes the selected frame, as explained above, and the terminal that FRAME is on becomes the selected terminal.  The window selected within FRAME becomes the selected window.  This function returns FRAME, or nil if FRAME has been deleted.

     Optional argument NORECORD non-nil means to neither change the order of recently selected windows nor the buffer list.  See The Buffer List.

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

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

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

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

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

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

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

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

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

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

 -- 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, unless other windows cover it.  If it is iconified, the frame's contents do not appear on the screen, but an icon does.  (Note: because of the way in which some window managers implement the concept of multiple workspaces, or desktops, all frames on other workspaces may appear to Emacs to be iconified.)  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.  This does not raise the frame, but you can do that with raise-frame if you wish (see Raising and Lowering).

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

     Unless FORCE is non-nil, this function refuses to make FRAME invisible if all other frames are 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.

     On a text-only terminal, all frames are considered visible, whether they are currently being displayed or not, and this function returns t for all frames.

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

With Emacs, frames constitute the windows in the metaphor sketched above. You can raise and lower frames using these functions:

 -- Command: raise-frame &optional frame
     This function raises frame FRAME (default, the selected frame). If FRAME is invisible or iconified, this makes it visible.

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

Frame Configurations
====================

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

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

 -- Function: set-frame-configuration configuration &optional nodelete
     This function restores the state of frames described in CONFIGURATION.  However, this function does not restore deleted frames.

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

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

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

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

 -- Function: set-mouse-position frame x y
     This function warps the mouse to position X, Y in frame FRAME.  The arguments X and Y are integers, giving the position in 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.

 -- Function: frame-pointer-visible-p &optional frame
     This predicate function returns non-nil if the mouse pointer displayed on FRAME is visible; otherwise it returns nil. FRAME omitted or nil means the selected frame.  This is useful when make-pointer-invisible is set to t: it allows to know if the pointer has been hidden. See Mouse Avoidance (emacs).

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 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.  If POSITION is nil, it means to precompute the key binding equivalents for the keymaps specified in MENU, without actually displaying or popping up the menu.

     The argument MENU says what to display in the menu.  It can be a keymap or a list of keymaps (see Menu Keymaps).  In this case, the return value is the list of events corresponding to the user's choice. This list has more than one element if the choice occurred in a submenu.  (Note that x-popup-menu does not actually execute the command bound to that sequence of events.)  On toolkits that support menu titles, the title is taken from the prompt string of MENU if MENU is a keymap, or from the prompt string of the first keymap in MENU if it is a list of keymaps (see Defining Menus).

     Alternatively, MENU can have the following form:

          (TITLE PANE1 PANE2...)

     where each pane is a list of form

          (TITLE ITEM1 ITEM2...)

     Each item should normally be a cons cell (LINE . VALUE), where LINE is a string, and VALUE is the value to return if that LINE is chosen.  An item can also be a string; this makes a non-selectable line in the menu.

     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 keyboard input, then this normally results in a quit and x-popup-menu does not return.  But if POSITION is a mouse button event (indicating that the user invoked the menu with the mouse) then no quit occurs and x-popup-menu returns nil.

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

The menu bar mechanism, which lets you switch between submenus by moving the mouse, cannot look within the definition of a command to see that it calls x-popup-menu.  Therefore, if you try to implement a submenu using x-popup-menu, it cannot work with the menu bar in an integrated fashion.  This is why all menu bar submenus are implemented with menu keymaps within the parent menu, and never with x-popup-menu.  See 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 or more buttons.  The main use of dialog boxes is for asking questions that the user can answer with ``yes,'' ``no,'' and a few other alternatives.  With a single button, they can also force the user to acknowledge important information.  The functions y-or-n-p and yes-or-no-p use dialog boxes instead of the keyboard, when called from commands invoked by mouse clicks.

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

          (TITLE (STRING . VALUE)...)

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

     The return value is VALUE from the chosen alternative.

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

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

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

     If HEADER is non-nil, the frame title for the box is Information, otherwise it is Question.  The former is used for message-box (see message-box).

     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.

Pointer Shape
=============

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

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

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

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

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

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

These variables affect newly created frames.  They do not normally affect existing frames; however, if you set the mouse color of a frame, that also installs the current value of those two variables. See 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.

Window System Selections
========================

In the X window system, 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.  See Cut and Paste (The GNU Emacs Manual), for Emacs commands that make use of these selections.  This section documents the low-level functions for reading and setting X selections.

 -- Command: x-set-selection type data
     This function sets an X selection.  It takes two arguments: a selection type TYPE, and the value to assign to it, DATA.

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

     If DATA is nil, it means to clear out the selection. Otherwise, DATA may be a string, a symbol, an integer (or a cons of two integers or list of two integers), an overlay, or a cons of two markers pointing to the same buffer.  An overlay or a pair of markers stands for text in the overlay or between the markers.  The argument DATA may also be a vector of valid non-vector selection values.

     This function returns DATA.

 -- Function: 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, 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.

 -- User Option: selection-coding-system
     This variable specifies the coding system to use when reading and writing selections or the clipboard.  See 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.  x-get-selection and x-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.

Drag and Drop
=============

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

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

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

Color Names
===========

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

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

To read user input of color names with completion, use read-color (see read-color).

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

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

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

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

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

 -- Function: color-supported-p color &optional frame background-p
     This returns t if FRAME can really display the color COLOR (or at least something close to it).  If FRAME is omitted or nil, the question applies to the selected frame.

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

     The argument COLOR must be a valid color name.

 -- Function: color-gray-p color &optional frame
     This returns t if COLOR is a shade of gray, as defined on FRAME's display.  If FRAME is omitted or nil, the question applies to the selected frame.  If COLOR is not a valid color name, this function returns nil.

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

     If COLOR is not defined, the value is nil.

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

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

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

Text Terminal Colors
====================

Text-only 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-only terminals; then this argument will specify which terminal to operate on (the default being the selected frame's terminal; see Input Focus).  At present, though, the FRAME argument has no effect.

 -- Function: tty-color-define name number &optional rgb frame
     This function associates the color name NAME with color number NUMBER on the terminal.

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

 -- Function: tty-color-clear &optional frame
     This function clears the table of defined colors for a text-only terminal.

 -- Function: tty-color-alist &optional frame
     This function returns an alist recording the known colors supported by a text-only terminal.

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

 -- Function: tty-color-approximate rgb &optional frame
     This function finds the closest color, among the known colors supported for DISPLAY, to that described by the rgb value RGB (a list of color values).  The return value is an element of tty-color-alist.

 -- Function: tty-color-translate color &optional frame
     This function finds the closest color to COLOR among the known colors supported for DISPLAY and returns its index (an integer). If the name COLOR is not defined, the value is nil.

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

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

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

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

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

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

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

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

     xterm.vt100.background: yellow

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

     (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
       (x-get-resource "vt100.background" "VT100.Background"))
          => "yellow"

     (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
       (x-get-resource "background" "VT100" "vt100" "Background"))
          => "yellow"

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

Display Feature Testing
=======================

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

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

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

 -- Function: display-popup-menus-p &optional display
     This function returns t if popup menus are supported on DISPLAY, nil if not.  Support for popup menus requires that the mouse be available, since the user cannot choose menu items without a mouse.

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

 -- Function: display-mouse-p &optional display
     This function returns t if DISPLAY has a mouse available, nil if not.

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

 -- Function: display-grayscale-p &optional display
     This function returns t if the screen can display shades of gray. (All color displays can do this.)

 -- Function: display-supports-face-attributes-p attributes &optional display
     This function returns non-nil if all the face attributes in ATTRIBUTES are supported (see Face Attributes).

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

      1. different in appearance than the default face, and

      2. `close in spirit' to what the attributes specify, if not exact.

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

 -- Function: display-selections-p &optional display
     This function returns t if DISPLAY supports selections. Windowed displays normally support selections, but they may also be supported in some other cases.

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

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

 -- Function: display-pixel-height &optional display
     This function returns the height of the screen in pixels. On a character terminal, it gives the height in characters.

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

 -- Function: display-pixel-width &optional display
     This function returns the width of the screen in pixels. On a character terminal, it gives the width in characters.

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

 -- Function: display-mm-height &optional display
     This function returns the height of the screen in millimeters, or nil if Emacs cannot get that information.

 -- Function: display-mm-width &optional display
     This function returns the width of the screen in millimeters, or nil if Emacs cannot get that information.

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

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

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

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

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

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

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

These functions obtain additional information specifically about X displays.

 -- Function: x-server-version &optional display
     This function returns the list of version numbers of the X server running the display.  The value is a list of three integers: the major and minor version numbers of the X protocol, and the distributor-specific release number of the X server software itself.

 -- Function: x-server-vendor &optional display
     This function returns the ``vendor'' that provided the X server software (as a string).  Really this means whoever distributes the X server.

     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.