annotate lispref/frames.texi @ 9763:296cd41d2601

(XTclear_end_of_line): Finish the line dance here too, just as was done in XTwrite_glyphs.

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
@node Frames, Positions, Windows, Top
@chapter Frames
@cindex frame

  A @var{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.

@cindex terminal frame
@cindex X window frame
  When Emacs runs on a text-only terminal, it has just one frame, a
@dfn{terminal frame}.  There is no way to create another terminal frame
after startup.  If Emacs has an X display, it does not have a terminal
frame; instead, it starts with a single @dfn{X window frame}.  You can
create more; see @ref{Creating Frames}.

@defun framep object
This predicate returns @code{t} if @var{object} is a frame, and
@code{nil} otherwise.
@end defun

@menu
* Creating Frames::		Creating additional X Window frames.
* Frame Parameters::		Controlling frame size, position, font, etc.
* Deleting Frames::		Frames last until explicitly deleted.
* Finding All Frames::		How to examine all existing frames.
* Frames and Windows::		A frame contains windows;
				  display of text always works through windows.
* Minibuffers and Frames::	How a frame finds the minibuffer to use.
* Input Focus::			Specifying the selected frame.
* Visibility of Frames::	Frames may be visible or invisible, or icons.
* Raising and Lowering::	Raising a frame makes it hide other X windows;
				  lowering it makes the others hide them.
* Frame Configurations::	Saving the state of all frames.
* Mouse Tracking::		Getting events that say when the mouse moves.
* Mouse Position::		Asking where the mouse is, or moving it.
* Pop-Up Menus::		Displaying a menu for the user to select from.
* Dialog Boxes::                Displaying a box to ask yes or no.
* Pointer Shapes::              Specifying the shape of the mouse pointer.
* X Selections::		Transferring text to and from other X clients.
* X Connections::	        Opening and closing the X server connection.
* Resources::		        Getting resource values from the server.
* Server Data::		        Getting info about the X server.
@end menu

  @xref{Display}, for related information.

@node Creating Frames
@section Creating Frames

To create a new frame, call the function @code{make-frame}.

@defun make-frame alist
This function creates a new frame, if the display mechanism permits
creation of frames.  (An X server does; an ordinary terminal does not.)

The argument is an alist specifying frame parameters.  Any parameters
not mentioned in @var{alist} default according to the value of the
variable @code{default-frame-alist}; parameters not specified there
either default from the standard X defaults file and X resources.

The set of possible parameters depends in principle on what kind of
window system Emacs uses to display its frames.  @xref{X Frame
Parameters}, for documentation of individual parameters you can specify
when creating an X window frame.
@end defun

@defvar before-make-frame-hook
A normal hook run by @code{make-frame} before it actually creates the
frame.
@end defvar

@defvar after-make-frame-hook
A normal hook run by @code{make-frame} after it creates the frame.
@end defvar

@node Frame Parameters
@section 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, for compatibility's sake only.  You can't change
these parameters directly; the only ones that ever change are the height
and width.

@menu
* Parameter Access::       How to change a frame's parameters.
* Initial Parameters::	   Specifying frame parameters when you make a frame.
* X Frame Parameters::     Individual parameters documented.
* Size and Position::      Changing the size and position of a frame.
@end menu

@node Parameter Access
@subsection Access to Frame Parameters

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

@defun frame-parameters frame
The function @code{frame-parameters} returns an alist listing all the
parameters of @var{frame} and their values.
@end defun

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

@node Initial Parameters
@subsection Initial Frame Parameters

You can specify the parameters for the initial startup frame
by setting @code{initial-frame-alist} in your @file{.emacs} file.

@defvar initial-frame-alist
This variable's value is an alist of parameter values used when creating
the initial X window frame.  Each element has the form:

@example
(@var{parameter} . @var{value})
@end example

Emacs creates the initial frame before it reads your @file{~/.emacs}
file.  After reading that file, Emacs checks @code{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, you'll see the frame appear
with the wrong geometry and then change to the specified one.  If you
like, you can specify the same geometry with X resources; those do take
affect before the frame is created.  @xref{Resources X,, X Resources,
emacs, 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 @code{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
@code{initial-frame-alist} with values that match the X resources.
@end defvar

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

@defvar 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.
@end defvar

@defvar special-display-frame-alist
The variable @code{special-display-frame-alist} specifies the frame
parameters for special display frames.
@end defvar

@defvar default-frame-alist
This is an alist specifying default values of frame parameters for
subsequent Emacs frames (not the initial ones).
@end defvar

If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to @code{default-frame-alist}.  One
exception is @samp{-geometry}, which adds to @code{initial-frame-alist}
instead.  @xref{Command Arguments,,, emacs, The GNU Emacs Manual}.

@node X Frame Parameters
@subsection X Window Frame Parameters

Just what parameters a frame has depends on what display mechanism it
uses.  Here is a table of the parameters of an X window frame:

@table @code
@item name
The name of the frame.  Most window managers display the frame's name in
the frame's border, at the top of the frame.  If you don't specify a
name, and you have more than one frame, Emacs sets the frame name based
on the buffer displayed in the frame's selected window.

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.

@item left
The screen position of the left edge, in pixels.  The value may be
@code{-} instead of a number; that represents @samp{-0} in a geometry
specification.

@item top
The screen position of the top edge, in pixels.  The value may be
@code{-} instead of a number; that represents @samp{-0} in a geometry
specification.

@item user-position
Non-@code{nil} if the screen position of the frame was explicitly
requested by the user (for example, with the @samp{-geometry} option).
Nothing automatically makes this parameter non-@code{nil}; it is up to
Lisp programs that call @code{make-frame} to specify this parameter as
well as specifying the @code{left} and @code{top} parameters.

@item height
The height of the frame contents, in characters.  (To get the height in
pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)

@item width
The width of the frame contents, in characters.  (To get the height in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)

@item window-id
The number of the X window for the frame.

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

@item font
The name of the font for displaying text in the frame.  This is a
string.

@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).

@item auto-lower
Whether deselecting the frame lowers it (non-@code{nil} means yes).

@item vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling
(non-@code{nil} means yes).

@item horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling
(non-@code{nil} means yes).  (Horizontal scroll bars are not currently
implemented.)

@item icon-type
The type of icon to use for this frame when it is iconified.
Non-@code{nil} specifies a bitmap icon, @code{nil} a text icon.

@item foreground-color
The color to use for the image of a character.  This is a string; the X
server defines the meaningful color names.

@item background-color
The color to use for the background of characters.

@item mouse-color
The color for the mouse pointer.

@item cursor-color
The color for the cursor that shows point.

@item border-color
The color for the border of the frame.

@item cursor-type
The way to display the cursor.  There are two legitimate values:
@code{bar} and @code{box}.  The symbol @code{bar} specifies a vertical
bar between characters as the cursor.  The symbol @code{box} specifies
an ordinary black box overlaying the character after point; that is the
default.

@item border-width
The width in pixels of the window border.

@item internal-border-width
The distance in pixels between text and border.

@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.

@item visibility
The state of visibility of the frame.  There are three possibilities:
@code{nil} for invisible, @code{t} for visible, and @code{icon} for
iconified.  @xref{Visibility of Frames}.

@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar.
The default is 1.  @xref{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.)

@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
Specifying this lets you create an Emacs window inside some other
application's window.  (It is not certain this will be implemented; try
it and see if it works.)
@end table

@node Size and Position
@subsection Frame Size And Position

  You can read or change the size and position of a frame using the
frame parameters @code{left}, @code{top}, @code{height}, and
@code{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:

@defun set-frame-position frame left top
This function sets the position of the top left corner of
@var{frame} to @var{left} and @var{top}.  These arguments are measured
in pixels, counting from the top left corner of the screen.
@end defun

@defun frame-height &optional frame
@defunx frame-width &optional frame
These functions return the height and width of @var{frame}, measured in
characters.  If you don't supply @var{frame}, they use the selected
frame.
@end defun

@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional frame
These functions return the height and width of @var{frame}, measured in
pixels.  If you don't supply @var{frame}, they use the selected frame.
@end defun

@defun frame-char-height &optional frame
@defunx frame-char-width &optional frame
These functions return the height and width of a character in
@var{frame}, measured in pixels.  The values depend on the choice of
font.  If you don't supply @var{frame}, these functions use the selected
frame.
@end defun

@defun set-frame-size frame cols rows
This function sets the size of @var{frame}, measured in characters;
@var{cols} and @var{rows} specify the new width and height.

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

  The old-fashioned functions @code{set-screen-height} and
@code{set-screen-width}, which were used to specify the height and width
of the screen in Emacs versions that did not support multiple frames,
are still usable.  They apply to the selected frame.  @xref{Screen
Size}.

@defun x-parse-geometry geom
@cindex geometry specification
The function @code{x-parse-geometry} converts a standard X windows
geometry string to an alist that you can use as part of the argument to
@code{make-frame}.

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

@smallexample
(x-parse-geometry "35x70+0-0")
     @result{} ((width . 35) (height . 70) (left . 0) (top . -1))
@end smallexample
@end defun

@ignore
New functions @code{set-frame-height} and @code{set-frame-width} set the
size of a specified frame.  The frame is the first argument; the size is
the second.
@end ignore

@node Deleting Frames
@section Deleting Frames
@cindex deletion of frames

Frames remain potentially visible until you explicitly @dfn{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 (@pxref{Frame Configurations}); this is similar to the
way windows behave.

@deffn Command delete-frame &optional frame
This function deletes the frame @var{frame}.  By default, @var{frame} is
the selected frame.
@end deffn

@defun frame-live-p frame
The function @code{frame-live-p} returns non-@code{nil} if the frame
@var{frame} has not been deleted.
@end defun

@node Finding All Frames
@section Finding All Frames

@defun frame-list
The function @code{frame-list} returns a list of all the frames that
have not been deleted.  It is analogous to @code{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.
@end defun

@defun visible-frame-list
This function returns a list of just the currently visible frames.
@xref{Visibility of Frames}.
@end defun

@defun next-frame &optional frame minibuf
The function @code{next-frame} lets you cycle conveniently through all
the frames from an arbitrary starting point.  It returns the ``next''
frame after @var{frame} in the cycle.  If @var{frame} is omitted or
@code{nil}, it defaults to the selected frame.

The second argument, @var{minibuf}, says which frames to consider:

@table @asis
@item @code{nil}
Exclude minibuffer-only frames.
@item @code{visible}
Consider all visible frames.
@item a window
Consider only the frames using that particular window as their
minibuffer.
@item anything else
Consider all frames.
@end table
@end defun

@defun previous-frame &optional frame minibuf
Like @code{next-frame}, but cycles through all frames in the opposite
direction.
@end defun

@node Frames and Windows
@section Frames and Windows

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

@defun window-frame window
This function returns the frame that @var{window} is on.
@end defun

  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.

@defun frame-top-window frame
This returns the topmost, leftmost window of frame @var{frame}.
@end defun

At any time, exactly one window on any frame is @dfn{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 @code{frame-selected-window}.

@defun frame-selected-window frame
This function returns the window on @var{frame} that is selected within
@var{frame}.
@end defun

Conversely, selecting a window for Emacs with @code{select-window} also
makes that window selected within its frame.  @xref{Selecting Windows}.

@node Minibuffers and Frames
@section 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 @code{minibuffer-window} (@pxref{Minibuffer Misc}).

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 frame on which to find the
minibuffer to use.  If you don't, then the minibuffer is found in the
frame which is the value of the variable
@code{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
@code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.

@node Input Focus
@section Input Focus
@cindex input focus
@cindex selected frame

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

@defun selected-frame
This function returns the selected frame.
@end defun

The X server normally directs keyboard input to the X window that the
mouse is in.  Some window managers use mouse clicks or keyboard events
to @dfn{shift the focus} to various X windows, overriding the normal
behavior of the server.

Lisp programs can switch frames ``temporarily'' by calling
the function @code{select-frame}.  This does not override the window
manager; rather, it escapes from the window manager's control until
that control is somehow reasserted.

@c ??? This is not yet implemented properly.
@defun select-frame frame
This function selects frame @var{frame}, temporarily disregarding the
focus of the X server.  The selection of @var{frame} lasts until the
next time the user does something to select a different frame, or until
the next time this function is called.
@end defun

Emacs cooperates with the X server and the window managers by arranging
to select frames according to what the server and window manager ask
for.  It does so by generating a special kind of input event, called a
@dfn{focus} event.  The command loop handles a focus event by calling
@code{handle-select-frame}.  @xref{Focus Events}.

@deffn Command handle-switch-frame frame
This function handles a focus event by selecting frame @var{frame}.

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

@defun redirect-frame-focus frame focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
This means that @var{focus-frame} will receive subsequent keystrokes
intended for @var{frame}.  After such an event, the value of
@code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
events specifying @var{frame} will instead select @var{focus-frame}.

If @var{focus-frame} is @code{nil}, that cancels any existing
redirection for @var{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
@code{bar}, when @code{foo} had been selected, changes any redirections
pointing to @code{foo} so that they point to @code{bar} instead.  This
allows focus redirection to work properly when the user switches from
one frame to another using @code{select-window}.

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

The redirection lasts until @code{redirect-frame-focus} is called to
change it.
@end defun

@node Visibility of Frames
@section Visibility of Frames
@cindex visible frame
@cindex invisible frame
@cindex iconified frame
@cindex frame visibility

A frame may be @dfn{visible}, @dfn{invisible}, or @dfn{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.

@deffn Command make-frame-visible &optional frame
This function makes frame @var{frame} visible.  If you omit @var{frame},
it makes the selected frame visible.
@end deffn

@deffn Command make-frame-invisible &optional frame
This function makes frame @var{frame} invisible.  If you omit
@var{frame}, it makes the selected frame invisible.
@end deffn

@deffn Command iconify-frame &optional frame
This function iconifies frame @var{frame}.  If you omit @var{frame}, it
iconifies the selected frame.
@end deffn

@defun frame-visible-p frame
This returns the visibility status of frame @var{frame}.  The value is
@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
@code{icon} if it is iconified.
@end defun

  The visibility status of a frame is also available as a frame
parameter.  You can read or change it as such.  @xref{X Frame
Parameters}.

@node Raising and Lowering
@section Raising and Lowering Frames

The X Window System uses 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.

@cindex raising a frame
@cindex lowering a frame
A window's place in this ordering is not fixed; in fact, users tend to
change the order frequently.  @dfn{Raising} a window means moving it
``up'', to the top of the stack.  @dfn{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's X windows with these functions:

@defun raise-frame frame
This function raises frame @var{frame}.
@end defun

@defun lower-frame frame
This function lowers frame @var{frame}.
@end defun

@defopt minibuffer-auto-raise
If this is non-@code{nil}, activation of the minibuffer raises the frame
that the minibuffer window is in.
@end defopt

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.  @xref{X Frame Parameters}.

@node Frame Configurations
@section Frame Configurations
@cindex frame configuration

  A @dfn{frame configuration} records the current arrangement of frames,
all their properties, and the window configuration of each one.

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

@defun set-frame-configuration configuration
This function restores the state of frames described in
@var{configuration}.
@end defun

@node Mouse Tracking
@section Mouse Tracking
@cindex mouse tracking
@cindex tracking the mouse

Sometimes it is useful to @dfn{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.

@defspec track-mouse body@dots{}
Execute @var{body}, meanwhile generating input events for mouse motion.
The code in @var{body} can read these events with @code{read-event} or
@code{read-key-sequence}.  @xref{Motion Events}, for the format of mouse
motion events.

The value of @code{track-mouse} is that of the last form in @var{body}.
@end defspec

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.

@ignore
@c These are not implemented yet.

These functions change the screen appearance instantaneously.  The
effect is transient, only until the next ordinary Emacs redisplay.  That
is ok for mouse tracking, since it doesn't make sense for mouse tracking
to change the text, and the body of @code{track-mouse} normally reads
the events itself and does not do redisplay.

@defun x-contour-region window beg end
This function draws lines to make a box around the text from @var{beg}
to @var{end}, in window @var{window}.
@end defun

@defun x-uncontour-region window beg end
This function erases the lines that would make a box around the text
from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
a contour that you previously made by calling @code{x-contour-region}.
@end defun

@defun x-draw-rectangle frame left top right bottom
This function draws a hollow rectangle on frame @var{frame} with the
specified edge coordinates, all measured in pixels from the inside top
left corner.  It uses the cursor color, the one used for indicating the
location of point.
@end defun

@defun x-erase-rectangle frame left top right bottom
This function erases a hollow rectangle on frame @var{frame} with the
specified edge coordinates, all measured in pixels from the inside top
left corner.  Erasure means redrawing the text and background that
normally belong in the specified rectangle.
@end defun
@end ignore

@node Mouse Position
@section Mouse Position
@cindex mouse position
@cindex position of mouse

  The functions @code{mouse-position} and @code{set-mouse-position}
give access to the current position of the mouse.

@defun mouse-position
This function returns a description of the position of the mouse.  The
value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
and @var{y} are integers giving the position in characters relative to
the top left corner of the inside of @var{frame}.
@end defun

@defun set-mouse-position frame x y
This function @dfn{warps the mouse} to position @var{x}, @var{y} in
frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
giving the position in characters relative to the top left corner of the
inside of @var{frame}.
@end defun

@defun mouse-pixel-position
This function is like @code{mouse-position} except that it returns
coordinates in units of pixels rather than units of characters.
@end defun

@defun set-mouse-pixel-position frame x y
This function warps the mouse like @code{set-mouse-position} except that
@var{x} and @var{y} are in units of pixels rather than units of
characters.  These coordinates are not required to be within the frame.
@end defun

@need 3000

@node Pop-Up Menus
@section Pop-Up Menus

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

The argument @var{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:

@example
((@var{xoffset} @var{yoffset}) @var{window})
@end example

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

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

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

@example
(@var{title} @var{pane1} @var{pane2}...)
@end example

@noindent
where each pane is a list of form

@example
(@var{title} (@var{line} @var{item})...)
@end example

Each @var{line} should be a string, and each @var{item} should be the
value to return if that @var{line} is chosen.
@end defun

@strong{Usage note:} Don't use @code{x-popup-menu} to display a menu if
a prefix key with a menu keymap would do the job.  If you use a menu
keymap to implement a menu, @kbd{C-h c} and @kbd{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 @code{x-popup-menu},
the help facilities cannot know what happens inside that command, so
they cannot give any help for the menu's items.  This is the reason why
all the menu bar items except @samp{Buffers} are implemented with menu
keymaps (@pxref{Menu Keymaps}).

@node Dialog Boxes
@section Dialog Boxes
@cindex dialog boxes

  A dialog box is a variant of a pop-up menu.  It looks a little
different (if Emacs uses an X toolkit), 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
@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
keyboard, when called from commands invoked by mouse clicks.

@defun 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 @var{contents} specifies
the alternatives to offer; it has this format:

@example
(@var{title} (@var{string} . @var{value})@dots{})
@end example

@noindent
which looks like the list that specifies a single pane for
@code{x-popup-menu}.

The return value is @var{value} from the chosen alternative.

An element of the list may be just a string instead of a cons cell
@code{(@var{string} . @var{value})}.  That makes a box that cannot
be selected.

If @code{nil} appears in the list, it separates the left-hand items from
the right-hand items; items that precede the @code{nil} appear on the
left, and items that follow the @code{nil} appear on the right.  If you
don't include a @code{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
@var{position} specifies which frame.  The possible values are as in
@code{x-popup-menu}, but the precise coordinates don't matter; only the
frame matters.

If your Emacs executable does not use an X toolkit, then it cannot
display a real dialog box; so instead it displays the same items in a
pop-up menu in the center of the frame.
@end defun

@node Pointer Shapes
@section Pointer Shapes
@cindex pointer shape
@cindex mouse pointer shape

  These variables specify which mouse pointer shape to use in various
situations:

@table @code
@item x-pointer-shape
@vindex x-pointer-shape
This variable specifies the pointer shape to use ordinarily in the Emacs
frame.

@item x-sensitive-text-pointer-shape
@vindex x-sensitive-text-pointer-shape
This variable specifies the pointer shape to use when the mouse
is over mouse-sensitive text.
@end table

  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.  @xref{X Frame Parameters}.

  The values you can use, to specify either of these pointer shapes, are
defined in the file @file{lisp/x-win.el}.  Use @kbd{M-x apropos
@key{RET} x-pointer @key{RET}} to see a list of them.

@node X Selections
@section X Selections
@cindex selection (for X windows)

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

@defun x-set-selection type data
This function sets a ``selection'' in the X server.  It takes two
arguments: a selection type @var{type}, and the value to assign to it,
@var{data}.  If @var{data} is @code{nil}, it means to clear out the
selection.  Otherwise, @var{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 data may also be a vector of valid non-vector selection values.

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

@defun 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, @var{type} and
@var{data-type}.  The default for @var{type}, the selection type, is
@code{PRIMARY}.

The @var{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 @code{TEXT}, @code{STRING},
@code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
@code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
@code{NAME}, @code{ATOM}, and @code{INTEGER}.  (These are symbols with
upper-case names in accord with X conventions.)  The default for
@var{data-type} is @code{STRING}.
@end defun

@cindex cut buffer
The X server also has a set of numbered @dfn{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.

@defun x-get-cut-buffer n
This function returns the contents of cut buffer number @var{n}.
@end defun

@defun x-set-cut-buffer string
This function stores @var{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.
@end defun

@node X Connections
@section X Connections

You can close the connection with the X server with the function
@code{x-close-current-connection}, and open a new one with
@code{x-open-connection} (perhaps with a different server and display).

@defun x-close-current-connection
This function closes the connection to the X server.  It deletes all
frames, making Emacs effectively inaccessible to the user; therefore, a
Lisp program that closes the connection should open another one.
@end defun

@defun x-open-connection display &optional resource-string
This function opens a connection to an X server, for use of display
@var{display}.

The optional argument @var{resource-string} is a string of resource
names and values, in the same format used in the @file{.Xresources}
file.  The values you specify override the resource values recorded in
the X server itself.  Here's an example of what this string might look
like:

@example
"*BorderWidth: 3\n*InternalBorder: 2\n"
@end example

@xref{Resources}.
@end defun

@defun x-display-color-p
This returns @code{t} if the connected X display has color, and
@code{nil} otherwise.
@end defun

@defun x-color-defined-p color
This function reports whether a color name is meaningful.  It returns
@code{t} if so; otherwise, @code{nil}.

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 @var{color}:

@example
(defun x-color-supported-p (color)
  (and (x-color-defined-p color)
       (or (x-display-color-p)
           (member color '("black" "white"))
           (and (> (x-display-planes) 1)
                (equal color "gray")))))
@end example
@end defun

@defun x-color-values color
This function returns a value that describes what @var{color} should
ideally look like.  If @var{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 @var{color} is not
defined, the value is @code{nil}.

@example
(x-color-values "black")
     @result{} (0 0 0)
(x-color-values "white")
     @result{} (65280 65280 65280)
(x-color-values "red")
     @result{} (65280 0 0)
(x-color-values "pink")
     @result{} (65280 49152 51968)
(x-color-values "hungry")
     @result{} nil
@end example
@end defun

@defun x-synchronize flag
The function @code{x-synchronize} enables or disables synchronous
communication with the X server.  It enables synchronous communication
if @var{flag} is non-@code{nil}, and disables it if @var{flag} is
@code{nil}.

In synchronous mode, Emacs waits for a response to each X protocol
command before doing anything else.  This is useful for debugging Emacs,
because protocol errors are reported right away, which helps you find
the erroneous command.  Synchronous mode is not the default because it
is much slower.
@end defun

@node Resources
@section X Resources

@defun x-get-resource attribute &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
Windows defaults database.

Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
This function searches using a key of the form
@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
under which Emacs was invoked), and using @samp{Emacs} as the class.

The optional arguments @var{component} and @var{subclass} add to the key
and the class, respectively.  You must specify both of them or neither.
If you specify them, the key is
@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
@samp{Emacs.@var{subclass}}.
@end defun

  @xref{Resources X, X Resources,, emacs, The GNU Emacs Manual}.

@node Server Data
@section Data about the X Server

  This section describes functions and a variable that you can use to
get information about the capabilities and origin of the X server that
Emacs is displaying its frames on.

@defun x-display-screens
This function returns the number of screens associated with the current
display.
@end defun

@defun x-server-version
This function returns the list of version numbers of the X server in
use.
@end defun

@defun x-server-vendor
This function returns the vendor supporting the X server in use.
@end defun

@defun x-display-pixel-height
This function returns the height of this X screen in pixels.
@end defun

@defun x-display-mm-height
This function returns the height of this X screen in millimeters.
@end defun

@defun x-display-pixel-width
This function returns the width of this X screen in pixels.
@end defun

@defun x-display-mm-width
This function returns the width of this X screen in millimeters.
@end defun

@defun x-display-backing-store
This function returns the backing store capability of this screen.
Values can be the symbols @code{always}, @code{when-mapped}, or
@code{not-useful}.
@end defun

@defun x-display-save-under
This function returns non-@code{nil} if this X screen supports the
SaveUnder feature.
@end defun

@defun x-display-planes
This function returns the number of planes this display supports.
@end defun

@defun x-display-visual-class
This function returns the visual class for this X screen.  The value is
one of the symbols @code{static-gray}, @code{gray-scale},
@code{static-color}, @code{pseudo-color}, @code{true-color}, and
@code{direct-color}.
@end defun

@defun x-display-color-p
This function returns @code{t} if the X screen in use is a color
screen.
@end defun

@defun x-display-color-cells
This function returns the number of color cells this X screen supports.
@end defun

@ignore
@defvar x-no-window-manager
This variable's value is is @code{t} if no X window manager is in use.
@end defvar
@end ignore

@ignore
@item
The functions @code{x-pixel-width} and @code{x-pixel-height} return the
width and height of an X Window frame, measured in pixels.
@end ignore