| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A frame is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window), which you can subdivide vertically or horizontally into smaller windows.
When Emacs runs on a text-only terminal, it starts with one terminal frame. If you create additional ones, Emacs displays one and only one at any given time--on the terminal screen, of course.
When Emacs communicates directly with a supported window system, such as X, it does not have a terminal frame; instead, it starts with a single window frame, but you can create more, and Emacs can display several such frames at once as is usual for window systems.
nil value if object is a
frame, and nil otherwise. For a frame, the value indicates which
kind of display the frame uses:
x
t
mac
w32
pc
29.1 Creating Frames Creating additional frames. 29.2 Multiple Displays Creating frames on other displays. 29.3 Frame Parameters Controlling frame size, position, font, etc. 29.4 Frame Titles Automatic updating of frame titles. 29.5 Deleting Frames Frames last until explicitly deleted. 29.6 Finding All Frames How to examine all existing frames. 29.7 Frames and Windows A frame contains windows; display of text always works through windows. 29.8 Minibuffers and Frames How a frame finds the minibuffer to use. 29.9 Input Focus Specifying the selected frame. 29.10 Visibility of Frames Frames may be visible or invisible, or icons. 29.11 Raising and Lowering Frames Raising a frame makes it hide other windows; lowering it makes the others hide them. 29.12 Frame Configurations Saving the state of all frames. 29.13 Mouse Tracking Getting events that say when the mouse moves. 29.14 Mouse Position Asking where the mouse is, or moving it. 29.15 Pop-Up Menus Displaying a menu for the user to select from. 29.16 Dialog Boxes Displaying a box to ask yes or no. 29.17 Pointer Shapes Specifying the shape of the mouse pointer. 29.18 Window System Selections Transferring text to and from other X clients. 29.19 Color Names Getting the definitions of color names. 29.20 Text Terminal Colors Defining colors for text-only terminals. 29.21 X Resources Getting resource values from the server. 29.22 Display Feature Testing Determining the features of a terminal.
See section 38. Emacs Display, for information about the related topic of controlling Emacs redisplay.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To create a new frame, call the function make-frame.
The argument is an alist specifying frame parameters. Any parameters
not mentioned in alist default according to the value of the
variable default-frame-alist; parameters not specified even there
default from the standard X resources or whatever is used instead on
your system.
The set of possible parameters depends in principle on what kind of window system Emacs uses to display its frames. See section 29.3.3 Window Frame Parameters, for documentation of individual parameters you can specify.
make-frame before it actually creates the
frame.
make-frame after it creates the frame.
Each function in after-make-frame-functions receives one argument, the
frame just created.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A single Emacs can talk to more than one X display.
Initially, Emacs uses just one display--the one chosen with the
DISPLAY environment variable or with the `--display' option
(see section `Initial Options' in The GNU Emacs Manual). To connect to
another display, use the command make-frame-on-display or specify
the display frame parameter when you create the frame.
Emacs treats each X server as a separate terminal, giving each one its own selected frame and its own minibuffer windows. However, only one of those frames is "the selected frame" at any given moment, see 29.9 Input Focus.
A few Lisp variables are terminal-local; that is, they have a
separate binding for each terminal. The binding in effect at any time
is the one for the terminal that the currently selected frame belongs
to. These variables include default-minibuffer-frame,
defining-kbd-macro, last-kbd-macro, and
system-key-alist. They are always terminal-local, and can never
be buffer-local (see section 11.10 Buffer-Local Variables) or frame-local.
A single X server can handle more than one screen. A display name `host:server.screen' has three parts; the last part specifies the screen number for a given server. When you use two screens belonging to one server, Emacs knows by the similarity in their names that they share a single keyboard, and it treats them as a single terminal.
make-frame (see section 29.1 Creating Frames).
The optional argument xrm-string, if not nil, is a
string of resource names and values, in the same format used in the
`.Xresources' file. The values you specify override the resource
values recorded in the X server itself; they apply to all Emacs frames
created on this display. Here's an example of what this string might
look like:
"*BorderWidth: 3\n*InternalBorder: 2\n" |
See section 29.21 X Resources.
If must-succeed is non-nil, failure to open the connection
terminates Emacs. Otherwise, it is an ordinary Lisp error.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
29.3.1 Access to Frame Parameters How to change a frame's parameters. 29.3.2 Initial Frame Parameters Specifying frame parameters when you make a frame. 29.3.3 Window Frame Parameters List of frame parameters for window systems. 29.3.4 Frame Size And Position Changing the size and position of a frame.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions let you read and change the parameter values of a frame.
nil, it returns the
selected frame's parameter.
frame-parameters returns an alist listing all the
parameters of frame and their values.
(parm . value), where parm is a symbol naming a
parameter. If you don't mention a parameter in alist, its value
doesn't change.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can specify the parameters for the initial startup frame
by setting initial-frame-alist in your init file (see section 40.1.2 The Init File, `.emacs').
(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 section `X Resources' in The GNU Emacs Manual.
X resource settings typically apply to all frames. If you want to
specify some X resources solely for the sake of the initial frame, and
you don't want them to apply to subsequent frames, here's how to achieve
this. Specify parameters in default-frame-alist to override the
X resources for subsequent frames; then, to prevent these from affecting
the initial frame, specify the same parameters in
initial-frame-alist with values that match the X resources.
If these parameters specify a separate minibuffer-only frame with
(minibuffer . nil), and you have not created one, Emacs creates
one for you.
See also special-display-frame-alist, in 28.8 Choosing a Window for Display.
If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to default-frame-alist. One
exception is `-geometry', which adds the specified position to
initial-frame-alist instead. See section `Command Arguments' in The GNU Emacs Manual.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Just what parameters a frame has depends on what display mechanism it
uses. Here is a table of the parameters that have special meanings in a
window frame; of these, name, title, height,
width, buffer-list and buffer-predicate provide
meaningful information in terminal frames.
display
"host:dpy.screen", just like the
DISPLAY environment variable.
title
nil title, it appears in the window system's
border for the frame, and also in the mode line of windows in that frame
if mode-line-frame-identification uses `%F'
(see section 23.3.3 %-Constructs in the Mode Line). This is normally the case when Emacs is not
using a window system, and can only display one frame at a time.
See section 29.4 Frame Titles.
name
title parameter is unspecified or nil. If
you don't specify a name, Emacs sets the frame name automatically
(see section 29.4 Frame Titles).
If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame.
left
(+ pos) which permits specifying a
negative pos value.
A negative number -pos, or a list of the form (-
pos), actually specifies the position of the right edge of the
window with respect to the right edge of the screen. A positive value
of pos counts toward the left. Reminder: if the
parameter is a negative integer -pos, then pos is
positive.
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
non-nil value for the user-position parameter as well.
top
(+ pos) which permits specifying a
negative pos value.
A negative number -pos, or a list of the form (-
pos), actually specifies the position of the bottom edge of the
window with respect to the bottom edge of the screen. A positive value
of pos counts toward the top. Reminder: if the
parameter is a negative integer -pos, then pos is
positive.
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
non-nil value for the user-position parameter as well.
icon-left
icon-top
user-position
left and top parameters, use this parameter to say whether
the specified position was user-specified (explicitly requested in some
way by a human user) or merely program-specified (chosen by a program).
A non-nil value says the position was user-specified.
Window managers generally heed user-specified positions, and some heed
program-specified positions too. But many ignore program-specified
positions, placing the window in a default fashion or letting the user
place it with the mouse. Some window managers, including twm,
let the user specify whether to obey program-specified positions or
ignore them.
When you call make-frame, you should specify a non-nil
value for this parameter if the values of the left and top
parameters represent the user's stated preference; otherwise, use
nil.
height
frame-pixel-height; see 29.3.4 Frame Size And Position.)
width
frame-pixel-width; see 29.3.4 Frame Size And Position.)
window-id
outer-window-id
minibuffer
t means
yes, nil means no, only means this frame is just a
minibuffer. If the value is a minibuffer window (in some other frame),
the new frame uses that minibuffer.
buffer-predicate
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
font
auto-raise
nil means yes).
auto-lower
nil means yes).
vertical-scroll-bars
left,
right, and nil for no scroll bars.
horizontal-scroll-bars
nil means yes). (Horizontal scroll bars are not currently
implemented.)
scroll-bar-width
icon-type
nil value specifies the default bitmap icon (a
picture of a gnu); nil specifies a text icon.
icon-name
nil, the frame's title is used.
foreground-color
default on the frame in question.
background-color
default on the frame in question.
background-mode
dark or light, according
to whether the background color is a light one or a dark one.
mouse-color
mouse.
cursor-color
cursor.
border-color
border.
scroll-bar-foreground
nil, the color for the foreground of scroll bars.
Changing this parameter is equivalent to setting the foreground color of
face scroll-bar.
scroll-bar-background
nil, the color for the background of scroll bars.
Changing this parameter is equivalent to setting the foreground color of
face scroll-bar.
display-type
color, grayscale or
mono.
cursor-type
bar,
box, and (bar . width). The symbol box
specifies an ordinary black box overlaying the character after point;
that is the default. The symbol bar specifies a vertical bar
between characters as the cursor. (bar . width) specifies
a bar width pixels wide.
The buffer-local variable cursor-type overrides the value of
the cursor-type frame parameter, and can in addition have
values t (use the cursor specified for the frame) and
nil (don't display a cursor).
border-width
internal-border-width
unsplittable
nil, this frame's window is never split automatically.
visibility
nil for invisible, t for visible, and icon for
iconified. See section 29.10 Visibility of Frames.
menu-bar-lines
screen-gamma
tool-bar-lines
nil means
don't display a tool bar.
line-spacing
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 29.9 Input Focus.)
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.
frame-height and
frame-width. When you are using a non-window terminal, the size
of the frame is normally the same as the size of the terminal screen.
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.
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.
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.
x-parse-geometry converts a standard X window
geometry string to an alist that you can use as part of the argument to
make-frame.
The alist describes which parameters were specified in geom, and
gives the values specified for them. Each element looks like
(parameter . value). The possible parameter
values are left, top, width, and height.
For the size parameters, the value must be an integer. The position
parameter names left and top are not totally accurate,
because some values indicate the position of the right or bottom edges
instead. These are the value possibilities for the position
parameters:
(+ position)
(- position)
Here is an example:
(x-parse-geometry "35x70+0-0")
=> ((height . 70) (width . 35)
(top - 0) (left . 0))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
mode-line-format. See section 23.3.1 The Data Structure of the Mode Line.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Frames remain potentially visible until you explicitly delete them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a frame aside from restoring a saved frame configuration (see section 29.12 Frame Configurations); this is similar to the way windows behave.
delete-frame-hook. 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 the force is non-nil, then you are allowed to do so.
frame-live-p returns non-nil if the frame
frame has not been deleted.
Some window managers provide a command to delete a window. These work
by sending a special message to the program that operates the window.
When Emacs gets one of these commands, it generates a
delete-frame event, whose normal definition is a command that
calls the function delete-frame. See section 21.6.10 Miscellaneous Window System Events.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
frame-list returns a list of all the frames 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.
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 section 29.9 Input Focus).
The second argument, minibuf, says which frames to consider:
nil
visible
next-frame, but cycles through all frames in the opposite
direction.
See also next-window and previous-window, in 28.5 Cyclic Ordering of Windows.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Each window is part of one and only one frame; you can get the frame
with window-frame.
All the non-minibuffer windows in a frame are arranged in a cyclic order. The order runs from the frame's top window, which is at the upper left corner, down and to the right, until it reaches the window at the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top. See section 28.5 Cyclic Ordering of Windows.
At any time, exactly one window on any frame is selected within the
frame. The significance of this designation is that selecting the
frame also selects this window. You can get the frame's current
selected window with frame-selected-window.
Conversely, selecting a window for Emacs with select-window also
makes that window selected within its frame. See section 28.4 Selecting Windows.
Another function that (usually) returns one of the windows in a given
frame is minibuffer-window. See section 20.9 Minibuffer Miscellany.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Normally, each frame has its own minibuffer window at the bottom, which
is used whenever that frame is selected. If the frame has a minibuffer,
you can get it with minibuffer-window (see section 20.9 Minibuffer Miscellany).
However, you can also create a frame with no minibuffer. Such a frame
must use the minibuffer window of some other frame. When you create the
frame, you can specify explicitly the minibuffer window to use (in some
other frame). If you don't, then the minibuffer is found in the frame
which is the value of the variable default-minibuffer-frame. Its
value should be a frame that does have a minibuffer.
If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer. If so, set the variable
minibuffer-auto-raise to t. See section 29.11 Raising and Lowering Frames.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section 29.2 Multiple Displays), 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 displayed is the selected frame's display.
Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to shift the focus to various window objects. Either way, Emacs automatically keeps track of which frame has the focus.
Lisp programs can also switch frames "temporarily" by calling the
function select-frame. This does not alter the window system's
concept of focus; rather, it escapes from the window manager's control
until that control is somehow reasserted.
When using a text-only terminal, only the selected terminal frame is
actually displayed on the terminal. switch-frame is the only way
to switch frames, and the change lasts until overridden by a subsequent
call to switch-frame. Each terminal screen except for the
initial one has a number, and the number of the selected frame appears
in the mode line before the buffer name (see section 23.3.2 Variables Used in the Mode Line).
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 section 21.6.9 Focus Events.
Focus events normally do their job by invoking this command. Don't call it for any other reason.
last-event-frame will be focus-frame. Also, switch-frame
events specifying frame will instead select focus-frame.
If focus-frame is nil, that cancels any existing
redirection for frame, which therefore once again receives its own
events.
One use of focus redirection is for frames that don't have minibuffers. These frames use minibuffers on other frames. Activating a minibuffer on another frame redirects focus to that frame. This puts the focus on the minibuffer's frame, where it belongs, even though the mouse remains in the frame that activated the minibuffer.
Selecting a frame can also change focus redirections. Selecting frame
bar, when foo had been selected, changes any redirections
pointing to foo so that they point to bar instead. This
allows focus redirection to work properly when the user switches from
one frame to another using select-window.
This means that a frame whose focus is redirected to itself is treated
differently from a frame whose focus is not redirected.
select-frame affects the former but not the latter.
The redirection lasts until redirect-frame-focus is called to
change it.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A window frame may be visible, invisible, or iconified. If it is visible, you can see its contents. If it is iconified, the frame's contents do not appear on the screen, but an icon does. If the frame is invisible, it doesn't show on the screen, not even as an icon.
Visibility is meaningless for terminal frames, since only the selected one is actually displayed in any case.
t if frame is visible, nil if it is invisible, and
icon if it is iconified.
The visibility status of a frame is also available as a frame parameter. You can read or change it as such. See section 29.3.3 Window Frame Parameters.
The user can iconify and deiconify frames with the window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. See section 21.6.10 Miscellaneous Window System Events.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Most window systems use a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from "highest" to "lowest". Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it.
A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. Raising a window means moving it "up", to the top of the stack. Lowering a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen.
You can raise and lower Emacs frame Windows with these functions:
nil, activation of the minibuffer raises the frame
that the minibuffer window is in.
You can also enable auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected) for any frame using frame parameters. See section 29.3.3 Window Frame Parameters.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A frame configuration records the current arrangement of frames, all their properties, and the window configuration of each one. (See section 28.17 Window Configurations.)
Ordinarily, this function deletes all existing frames not listed in
configuration. But if nodelete is non-nil, the
unwanted frames are iconified instead.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
read-event to
read the motion events and modify the display accordingly. See section 21.6.8 Motion Events, for the format of mouse motion events.
The value of track-mouse is that of the last form in body.
You should design body to return when it sees the up-event that
indicates the release of the button, or whatever kind of event means
it is time to stop tracking.
The usual purpose of tracking mouse motion is to indicate on the screen the consequences of pushing or releasing a button at the current position.
In many cases, you can avoid the need to track the mouse by using
the mouse-face text property (see section 32.19.4 Properties with Special Meanings).
That works at a much lower level and runs more smoothly than
Lisp-level mouse tracking.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The functions mouse-position and set-mouse-position
give access to the current position of the mouse.
(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.
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.
mouse-position except that it returns
coordinates in units of pixels rather than units of characters.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When using a window system, a Lisp program can pop up a menu so that the user can choose an alternative with the mouse.
The argument position specifies where on the screen to put the menu. It can be either a mouse button event (which says to put the menu where the user actuated the button) or a list of this form:
((xoffset yoffset) window) |
where xoffset and yoffset are coordinates, measured in pixels, counting from the top left corner of window's frame.
If position is t, it means to use the current mouse
position. If position is nil, it means to precompute the
key binding equivalents for the keymaps specified in menu,
without actually displaying or popping up the menu.
The argument menu says what to display in the menu. It can be a keymap or a list of keymaps (see section 22.12 Menu Keymaps). Alternatively, it can have the following form:
(title pane1 pane2...) |
where each pane is a list of form
(title (line . item)...) |
Each line should be a string, and each item should be the value to return if that line is chosen.
Usage note: Don't use x-popup-menu to display a menu
if you could do the job with a prefix key defined with a menu keymap.
If you use a menu keymap to implement a menu, C-h c and C-h
a can see the individual items in that menu and provide help for them.
If instead you implement the menu by defining a command that calls
x-popup-menu, the help facilities cannot know what happens inside
that command, so they cannot give any help for the menu's items.
The menu bar mechanism, which lets you switch between submenus by
moving the mouse, cannot look within the definition of a command to see
that it calls x-popup-menu. Therefore, if you try to implement a
submenu using x-popup-menu, it cannot work with the menu bar in
an integrated fashion. This is why all menu bar submenus are
implemented with menu keymaps within the parent menu, and never with
x-popup-menu. See section 22.12.5 The Menu Bar,
If you want a menu bar submenu to have contents that vary, you should
still use a menu keymap to implement it. To make the contents vary, add
a hook function to menu-bar-update-hook to update the contents of
the menu keymap as necessary.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A dialog box is a variant of a pop-up menu--it looks a little
different, it always appears in the center of a frame, and it has just
one level and one pane. The main use of dialog boxes is for asking
questions that the user can answer with "yes", "no", and a few other
alternatives. The functions y-or-n-p and yes-or-no-p use
dialog boxes instead of the keyboard, when called from commands invoked
by mouse clicks.
(title (string . value)...) |
which looks like the list that specifies a single pane for
x-popup-menu.
The return value is value from the chosen alternative.
An element of the list may be just a string instead of a cons cell
(string . value). That makes a box that cannot
be selected.
If nil appears in the list, it separates the left-hand items from
the right-hand items; items that precede the nil appear on the
left, and items that follow the nil appear on the right. If you
don't include a nil in the list, then approximately half the
items appear on each side.
Dialog boxes always appear in the center of a frame; the argument
position specifies which frame. The possible values are as in
x-popup-menu, but the precise coordinates don't matter; only the
frame matters.
In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the frame.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These variables specify which shape to use for the mouse pointer in various situations, when using the X Window System:
x-pointer-shape
x-sensitive-text-pointer-shape
These variables affect newly created frames. They do not normally affect existing frames; however, if you set the mouse color of a frame, that also updates its pointer shapes based on the current values of these variables. See section 29.3.3 Window Frame Parameters.
The values you can use, to specify either of these pointer shapes, are defined in the file `lisp/term/x-win.el'. Use M-x apropos RET x-pointer RET to see a list of them.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The X server records a set of selections which permit transfer of data between application programs. The various selections are distinguished by selection types, represented in Emacs by symbols. X clients including Emacs can read or set the selection for any given type.
nil, it means to clear out the
selection. Otherwise, data may be a string, a symbol, an integer
(or a cons of two integers or list of two integers), an overlay, or a
cons of two markers pointing to the same buffer. An overlay or a pair
of markers stands for text in the overlay or between the markers.
The argument data may also be a vector of valid non-vector selection values.
Each possible type has its own selection value, which changes
independently. The usual values of type are PRIMARY and
SECONDARY; these are symbols with upper-case names, in accord
with X Window System conventions. The default is PRIMARY.
PRIMARY.
The data-type argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into Lisp
data. Meaningful values include TEXT, STRING,
TARGETS, LENGTH, DELETE, FILE_NAME,
CHARACTER_POSITION, LINE_NUMBER, COLUMN_NUMBER,
OWNER_OS, HOST_NAME, USER, CLASS,
NAME, ATOM, and INTEGER. (These are symbols with
upper-case names in accord with X conventions.) The default for
data-type is STRING.
The X server also has a set of numbered cut buffers which can store text or other data being moved between applications. Cut buffers are considered obsolete, but Emacs supports them for the sake of X clients that still use them.
nil, only the first cut buffer is changed.
If push is non-nil, that says to move the values down
through the series of cut buffers, much like the way successive kills in
Emacs move down the kill ring. In other words, the previous value of
the first cut buffer moves into the second cut buffer, and the second to
the third, and so on through all eight cut buffers.
compound-text, 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.
nil, the Emacs yank functions consult the
clipboard before the primary selection, and the kill functions store in
the clipboard as well as the primary selection. Otherwise they do not
access the clipboard at all. The default is nil on most systems,
but t on MS-Windows.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 29.9 Input Focus, for the meaning of the term "selected frame".
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.
This function used to be called x-defined-colors,
and that name is still supported as an alias.
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.
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. The argument color must
be a valid color name.
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.
This function used to be called x-color-values,
and that name is still supported as an alias.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Emacs can display color on text-only terminals, starting with version 21. These terminals 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.
Several of these functions use or return rgb values. An rgb 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 the largest value used is 65280.
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 more than one text-only terminal at one time; then this argument will specify which terminal to operate on (the default being the selected frame's terminal; see section 29.9 Input Focus). At present, though, the display argument has no effect.
The optional argument rgb, if specified, is an rgb value; it says
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 does not know what it looks
like.
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 an rgb value that says what the color
actually looks like.
nil.
color can be an X-style "#xxxyyyzzz" specification
instead of an actual name. The format
"RGB:xx/yy/zz" is also supported.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
x-get-resource retrieves a resource value from the X
Windows defaults database.
Resources are indexed by a combination of a key and a class. This function searches using a key of the form `instance.attribute' (where instance is the name under which Emacs was invoked), and using `Emacs.class' as the class.
The optional arguments component and subclass add to the key and the class, respectively. You must specify both of them or neither. If you specify them, the key is `instance.component.attribute', and the class is `Emacs.class.subclass'.
x-get-resource
should look up. The default value is "Emacs". You can examine X
resources for application names other than "Emacs" by binding this
variable to some other string, around a call to x-get-resource.
See section `X Resources' in The GNU Emacs Manual.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 ordinarly 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 section 29.9 Input Focus).
See section 29.19 Color Names, 29.20 Text Terminal Colors, for other functions to obtain information about displays.
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.
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.
t if display has a mouse available,
nil if not.
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.
t if the screen can display shades of gray.
(All color displays can do this.)
t if display supports selections.
Windowed displays normally support selections, but they may also be
supported in some other cases.
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.
nil if Emacs cannot get that information.
nil if Emacs cannot get that information.
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.
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.
static-gray, gray-scale,
static-color, pseudo-color, true-color, and
direct-color.
These functions obtain additional information specifically about X displays.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |