Mercurial > emacs
annotate doc/lispref/frames.texi @ 97366:d2c211c8ceda
(w32_list_system_processes, w32_system_process_attributes): Add prototypes.
(Qeuid, Qegid, Qcomm, Qstate, Qppid, Qpgrp, Qsess, Qttname)
(Qminflt, Qmajflt, Qcminflt, Qcmajflt, Qutime, Qstime, Qcutime)
(Qpri, Qnice, Qthcount, Qstart, Qvsize, Qrss, Qargs, Quser, Qgroup)
(Qetime, Qpcpu, Qpmem, Qtpgid, Qcstime): Add extern declarations.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sat, 09 Aug 2008 17:53:30 +0000 |
parents | 9592c50233ab |
children | 8be1f0e1f72d |
rev | line source |
---|---|
84068 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, | |
87649 | 4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
84068 | 5 @c See the file elisp.texi for copying conditions. |
84116
0ba80d073e27
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84068
diff
changeset
|
6 @setfilename ../../info/frames |
84068 | 7 @node Frames, Positions, Windows, Top |
8 @chapter Frames | |
9 @cindex frame | |
10 | |
11 In Emacs editing, A @dfn{frame} is a screen object that contains one | |
12 or more Emacs windows. It's the kind of object that is called a | |
13 ``window'' in the terminology of graphical environments; but we can't | |
14 call it a ``window'' here, because Emacs uses that word in a different | |
15 way. | |
16 | |
17 A frame initially contains a single main window and/or a minibuffer | |
18 window; you can subdivide the main window vertically or horizontally | |
19 into smaller windows. In Emacs Lisp, a @dfn{frame object} is a Lisp | |
20 object that represents a frame on the screen. | |
21 | |
22 @cindex terminal frame | |
23 When Emacs runs on a text-only terminal, it starts with one | |
24 @dfn{terminal frame}. If you create additional ones, Emacs displays | |
25 one and only one at any given time---on the terminal screen, of course. | |
26 | |
27 @cindex window frame | |
28 When Emacs communicates directly with a supported window system, such | |
29 as X, it does not have a terminal frame; instead, it starts with | |
30 a single @dfn{window frame}, but you can create more, and Emacs can | |
31 display several such frames at once as is usual for window systems. | |
32 | |
33 @defun framep object | |
34 This predicate returns a non-@code{nil} value if @var{object} is a | |
35 frame, and @code{nil} otherwise. For a frame, the value indicates which | |
36 kind of display the frame uses: | |
37 | |
38 @table @code | |
39 @item x | |
40 The frame is displayed in an X window. | |
41 @item t | |
42 A terminal frame on a character display. | |
43 @item w32 | |
44 The frame is displayed on MS-Windows 9X/NT. | |
45 @item pc | |
46 The frame is displayed on an MS-DOS terminal. | |
47 @end table | |
48 @end defun | |
49 | |
50 @menu | |
51 * Creating Frames:: Creating additional frames. | |
52 * Multiple Displays:: Creating frames on other displays. | |
53 * Frame Parameters:: Controlling frame size, position, font, etc. | |
54 * Frame Titles:: Automatic updating of frame titles. | |
55 * Deleting Frames:: Frames last until explicitly deleted. | |
56 * Finding All Frames:: How to examine all existing frames. | |
57 * Frames and Windows:: A frame contains windows; | |
58 display of text always works through windows. | |
59 * Minibuffers and Frames:: How a frame finds the minibuffer to use. | |
60 * Input Focus:: Specifying the selected frame. | |
61 * Visibility of Frames:: Frames may be visible or invisible, or icons. | |
62 * Raising and Lowering:: Raising a frame makes it hide other windows; | |
63 lowering it makes the others hide it. | |
64 * Frame Configurations:: Saving the state of all frames. | |
65 * Mouse Tracking:: Getting events that say when the mouse moves. | |
66 * Mouse Position:: Asking where the mouse is, or moving it. | |
67 * Pop-Up Menus:: Displaying a menu for the user to select from. | |
68 * Dialog Boxes:: Displaying a box to ask yes or no. | |
69 * Pointer Shape:: Specifying the shape of the mouse pointer. | |
70 * Window System Selections:: Transferring text to and from other X clients. | |
71 * Drag and Drop:: Internals of Drag-and-Drop implementation. | |
72 * Color Names:: Getting the definitions of color names. | |
73 * Text Terminal Colors:: Defining colors for text-only terminals. | |
74 * Resources:: Getting resource values from the server. | |
75 * Display Feature Testing:: Determining the features of a terminal. | |
76 @end menu | |
77 | |
78 @xref{Display}, for information about the related topic of | |
79 controlling Emacs redisplay. | |
80 | |
81 @node Creating Frames | |
82 @section Creating Frames | |
83 | |
84 To create a new frame, call the function @code{make-frame}. | |
85 | |
86 @defun make-frame &optional alist | |
87 This function creates and returns a new frame, displaying the current | |
88 buffer. If you are using a supported window system, it makes a window | |
89 frame; otherwise, it makes a terminal frame. | |
90 | |
91 The argument is an alist specifying frame parameters. Any parameters | |
92 not mentioned in @var{alist} default according to the value of the | |
93 variable @code{default-frame-alist}; parameters not specified even there | |
94 default from the standard X resources or whatever is used instead on | |
95 your system. | |
96 | |
97 The set of possible parameters depends in principle on what kind of | |
98 window system Emacs uses to display its frames. @xref{Window Frame | |
99 Parameters}, for documentation of individual parameters you can specify. | |
100 | |
101 This function itself does not make the new frame the selected frame. | |
102 @xref{Input Focus}. The previously selected frame remains selected. | |
103 However, the window system may select the new frame for its own reasons, | |
104 for instance if the frame appears under the mouse pointer and your | |
105 setup is for focus to follow the pointer. | |
106 @end defun | |
107 | |
108 @defvar before-make-frame-hook | |
109 A normal hook run by @code{make-frame} before it actually creates the | |
110 frame. | |
111 @end defvar | |
112 | |
113 @defvar after-make-frame-functions | |
114 An abnormal hook run by @code{make-frame} after it creates the frame. | |
115 Each function in @code{after-make-frame-functions} receives one argument, the | |
116 frame just created. | |
117 @end defvar | |
118 | |
119 @node Multiple Displays | |
120 @section Multiple Displays | |
121 @cindex multiple X displays | |
122 @cindex displays, multiple | |
123 | |
124 A single Emacs can talk to more than one X display. | |
125 Initially, Emacs uses just one display---the one chosen with the | |
126 @code{DISPLAY} environment variable or with the @samp{--display} option | |
127 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to | |
128 another display, use the command @code{make-frame-on-display} or specify | |
129 the @code{display} frame parameter when you create the frame. | |
130 | |
131 Emacs treats each X server as a separate terminal, giving each one its | |
132 own selected frame and its own minibuffer windows. However, only one of | |
133 those frames is ``@emph{the} selected frame'' at any given moment, see | |
134 @ref{Input Focus}. | |
135 | |
136 A few Lisp variables are @dfn{terminal-local}; that is, they have a | |
137 separate binding for each terminal. The binding in effect at any time | |
138 is the one for the terminal that the currently selected frame belongs | |
139 to. These variables include @code{default-minibuffer-frame}, | |
140 @code{defining-kbd-macro}, @code{last-kbd-macro}, and | |
141 @code{system-key-alist}. They are always terminal-local, and can never | |
85688 | 142 be buffer-local (@pxref{Buffer-Local Variables}). |
84068 | 143 |
144 A single X server can handle more than one screen. A display name | |
145 @samp{@var{host}:@var{server}.@var{screen}} has three parts; the last | |
146 part specifies the screen number for a given server. When you use two | |
147 screens belonging to one server, Emacs knows by the similarity in their | |
148 names that they share a single keyboard, and it treats them as a single | |
149 terminal. | |
150 | |
151 Note that some graphical terminals can output to more than a one | |
152 monitor (or other output device) at the same time. On these | |
153 ``multi-monitor'' setups, a single @var{display} value controls the | |
154 output to all the physical monitors. In this situation, there is | |
155 currently no platform-independent way for Emacs to distinguish between | |
156 the different physical monitors. | |
157 | |
158 @deffn Command make-frame-on-display display &optional parameters | |
159 This creates and returns a new frame on display @var{display}, taking | |
160 the other frame parameters from @var{parameters}. Aside from the | |
161 @var{display} argument, it is like @code{make-frame} (@pxref{Creating | |
162 Frames}). | |
163 @end deffn | |
164 | |
165 @defun x-display-list | |
166 This returns a list that indicates which X displays Emacs has a | |
167 connection to. The elements of the list are strings, and each one is | |
168 a display name. | |
169 @end defun | |
170 | |
171 @defun x-open-connection display &optional xrm-string must-succeed | |
172 This function opens a connection to the X display @var{display}. It | |
173 does not create a frame on that display, but it permits you to check | |
174 that communication can be established with that display. | |
175 | |
176 The optional argument @var{xrm-string}, if not @code{nil}, is a | |
177 string of resource names and values, in the same format used in the | |
178 @file{.Xresources} file. The values you specify override the resource | |
179 values recorded in the X server itself; they apply to all Emacs frames | |
180 created on this display. Here's an example of what this string might | |
181 look like: | |
182 | |
183 @example | |
184 "*BorderWidth: 3\n*InternalBorder: 2\n" | |
185 @end example | |
186 | |
187 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. | |
188 | |
189 If @var{must-succeed} is non-@code{nil}, failure to open the connection | |
190 terminates Emacs. Otherwise, it is an ordinary Lisp error. | |
191 @end defun | |
192 | |
193 @defun x-close-connection display | |
194 This function closes the connection to display @var{display}. Before | |
195 you can do this, you must first delete all the frames that were open on | |
196 that display (@pxref{Deleting Frames}). | |
197 @end defun | |
198 | |
199 @node Frame Parameters | |
200 @section Frame Parameters | |
201 @cindex frame parameters | |
202 | |
203 A frame has many parameters that control its appearance and behavior. | |
204 Just what parameters a frame has depends on what display mechanism it | |
205 uses. | |
206 | |
207 Frame parameters exist mostly for the sake of window systems. A | |
208 terminal frame has a few parameters, mostly for compatibility's sake; | |
209 only the @code{height}, @code{width}, @code{name}, @code{title}, | |
210 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate} | |
211 parameters do something special. If the terminal supports colors, the | |
212 parameters @code{foreground-color}, @code{background-color}, | |
213 @code{background-mode} and @code{display-type} are also meaningful. | |
214 | |
215 @menu | |
216 * Parameter Access:: How to change a frame's parameters. | |
217 * Initial Parameters:: Specifying frame parameters when you make a frame. | |
218 * Window Frame Parameters:: List of frame parameters for window systems. | |
219 * Size and Position:: Changing the size and position of a frame. | |
220 * Geometry:: Parsing geometry specifications. | |
221 @end menu | |
222 | |
223 @node Parameter Access | |
224 @subsection Access to Frame Parameters | |
225 | |
226 These functions let you read and change the parameter values of a | |
227 frame. | |
228 | |
229 @defun frame-parameter frame parameter | |
230 This function returns the value of the parameter @var{parameter} (a | |
231 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the | |
232 selected frame's parameter. If @var{frame} has no setting for | |
233 @var{parameter}, this function returns @code{nil}. | |
234 @end defun | |
235 | |
236 @defun frame-parameters &optional frame | |
237 The function @code{frame-parameters} returns an alist listing all the | |
238 parameters of @var{frame} and their values. If @var{frame} is | |
239 @code{nil} or omitted, this returns the selected frame's parameters | |
240 @end defun | |
241 | |
242 @defun modify-frame-parameters frame alist | |
243 This function alters the parameters of frame @var{frame} based on the | |
244 elements of @var{alist}. Each element of @var{alist} has the form | |
245 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a | |
246 parameter. If you don't mention a parameter in @var{alist}, its value | |
247 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected | |
248 frame. | |
249 @end defun | |
250 | |
251 @defun modify-all-frames-parameters alist | |
252 This function alters the frame parameters of all existing frames | |
253 according to @var{alist}, then modifies @code{default-frame-alist} | |
254 (and, if necessary, @code{initial-frame-alist}) to apply the same | |
255 parameter values to frames that will be created henceforth. | |
256 @end defun | |
257 | |
258 @node Initial Parameters | |
259 @subsection Initial Frame Parameters | |
260 | |
261 You can specify the parameters for the initial startup frame | |
262 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}). | |
263 | |
264 @defvar initial-frame-alist | |
265 This variable's value is an alist of parameter values used when creating | |
266 the initial window frame. You can set this variable to specify the | |
267 appearance of the initial frame without altering subsequent frames. | |
268 Each element has the form: | |
269 | |
270 @example | |
271 (@var{parameter} . @var{value}) | |
272 @end example | |
273 | |
274 Emacs creates the initial frame before it reads your init | |
275 file. After reading that file, Emacs checks @code{initial-frame-alist}, | |
276 and applies the parameter settings in the altered value to the already | |
277 created initial frame. | |
278 | |
279 If these settings affect the frame geometry and appearance, you'll see | |
280 the frame appear with the wrong ones and then change to the specified | |
281 ones. If that bothers you, you can specify the same geometry and | |
282 appearance with X resources; those do take effect before the frame is | |
283 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. | |
284 | |
285 X resource settings typically apply to all frames. If you want to | |
286 specify some X resources solely for the sake of the initial frame, and | |
287 you don't want them to apply to subsequent frames, here's how to achieve | |
288 this. Specify parameters in @code{default-frame-alist} to override the | |
289 X resources for subsequent frames; then, to prevent these from affecting | |
290 the initial frame, specify the same parameters in | |
291 @code{initial-frame-alist} with values that match the X resources. | |
292 @end defvar | |
293 | |
294 If these parameters specify a separate minibuffer-only frame with | |
295 @code{(minibuffer . nil)}, and you have not created one, Emacs creates | |
296 one for you. | |
297 | |
298 @defvar minibuffer-frame-alist | |
299 This variable's value is an alist of parameter values used when creating | |
300 an initial minibuffer-only frame---if such a frame is needed, according | |
301 to the parameters for the main initial frame. | |
302 @end defvar | |
303 | |
304 @defvar default-frame-alist | |
305 This is an alist specifying default values of frame parameters for all | |
306 Emacs frames---the first frame, and subsequent frames. When using the X | |
307 Window System, you can get the same results by means of X resources | |
308 in many cases. | |
309 | |
310 Setting this variable does not affect existing frames. | |
311 @end defvar | |
312 | |
313 See also @code{special-display-frame-alist}. @xref{Definition of | |
314 special-display-frame-alist}. | |
315 | |
316 If you use options that specify window appearance when you invoke Emacs, | |
317 they take effect by adding elements to @code{default-frame-alist}. One | |
318 exception is @samp{-geometry}, which adds the specified position to | |
319 @code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command | |
320 Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. | |
321 | |
322 @node Window Frame Parameters | |
323 @subsection Window Frame Parameters | |
324 | |
325 Just what parameters a frame has depends on what display mechanism | |
326 it uses. This section describes the parameters that have special | |
327 meanings on some or all kinds of terminals. Of these, @code{name}, | |
328 @code{title}, @code{height}, @code{width}, @code{buffer-list} and | |
329 @code{buffer-predicate} provide meaningful information in terminal | |
330 frames, and @code{tty-color-mode} is meaningful @emph{only} in | |
331 terminal frames. | |
332 | |
333 @menu | |
334 * Basic Parameters:: Parameters that are fundamental. | |
335 * Position Parameters:: The position of the frame on the screen. | |
336 * Size Parameters:: Frame's size. | |
337 * Layout Parameters:: Size of parts of the frame, and | |
338 enabling or disabling some parts. | |
339 * Buffer Parameters:: Which buffers have been or should be shown. | |
340 * Management Parameters:: Communicating with the window manager. | |
341 * Cursor Parameters:: Controlling the cursor appearance. | |
342 * Color Parameters:: Colors of various parts of the frame. | |
343 @end menu | |
344 | |
345 @node Basic Parameters | |
346 @subsubsection Basic Parameters | |
347 | |
348 These frame parameters give the most basic information about the | |
349 frame. @code{title} and @code{name} are meaningful on all terminals. | |
350 | |
351 @table @code | |
352 @item display | |
353 The display on which to open this frame. It should be a string of the | |
354 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the | |
355 @code{DISPLAY} environment variable. | |
356 | |
357 @item display-type | |
358 This parameter describes the range of possible colors that can be used | |
359 in this frame. Its value is @code{color}, @code{grayscale} or | |
360 @code{mono}. | |
361 | |
362 @item title | |
87453 | 363 If a frame has a non-@code{nil} title, it appears in the window |
364 system's title bar at the top of the frame, and also in the mode line | |
365 of windows in that frame if @code{mode-line-frame-identification} uses | |
366 @samp{%F} (@pxref{%-Constructs}). This is normally the case when | |
367 Emacs is not using a window system, and can only display one frame at | |
368 a time. @xref{Frame Titles}. | |
84068 | 369 |
370 @item name | |
371 The name of the frame. The frame name serves as a default for the frame | |
372 title, if the @code{title} parameter is unspecified or @code{nil}. If | |
373 you don't specify a name, Emacs sets the frame name automatically | |
374 (@pxref{Frame Titles}). | |
375 | |
376 If you specify the frame name explicitly when you create the frame, the | |
377 name is also used (instead of the name of the Emacs executable) when | |
378 looking up X resources for the frame. | |
379 | |
380 @item display-environment-variable | |
381 The value of the @code{DISPLAY} environment variable for the frame. It | |
382 is passed to child processes. | |
383 | |
384 @item term-environment-variable | |
385 The value of the @code{TERM} environment variable for the frame. It | |
386 is passed to child processes. | |
387 @end table | |
388 | |
389 @node Position Parameters | |
390 @subsubsection Position Parameters | |
391 | |
392 Position parameters' values are normally measured in pixels, but on | |
393 text-only terminals they count characters or lines instead. | |
394 | |
395 @table @code | |
396 @item left | |
92098 | 397 The position, in pixels, of the left (or right) edge of the frame with |
398 respect to the left (or right) edge of the screen. The value may be: | |
92096
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
399 |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
400 @table @asis |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
401 @item an integer |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
402 A positive integer relates the left edge of the frame to the left edge |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
403 of the screen. A negative integer relates the right frame edge to the |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
404 right screen edge. |
84068 | 405 |
92096
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
406 @item @code{(+ @var{pos})} |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
407 This specifies the position of the left frame edge relative to the left |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
408 screen edge. The integer @var{pos} may be positive or negative; a |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
409 negative value specifies a position outside the screen. |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
410 |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
411 @item @code{(- @var{pos})} |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
412 This specifies the position of the right frame edge relative to the right |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
413 screen edge. The integer @var{pos} may be positive or negative; a |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
414 negative value specifies a position outside the screen. |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
415 @end table |
84068 | 416 |
417 Some window managers ignore program-specified positions. If you want to | |
418 be sure the position you specify is not ignored, specify a | |
419 non-@code{nil} value for the @code{user-position} parameter as well. | |
420 | |
421 @item top | |
92096
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
422 The screen position of the top (or bottom) edge, in pixels, with respect |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
423 to the top (or bottom) edge of the screen. It works just like |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
424 @code{left}, except vertically instead of horizontally. |
84068 | 425 |
426 @item icon-left | |
427 The screen position of the left edge @emph{of the frame's icon}, in | |
428 pixels, counting from the left edge of the screen. This takes effect if | |
429 and when the frame is iconified. | |
430 | |
431 If you specify a value for this parameter, then you must also specify | |
432 a value for @code{icon-top} and vice versa. The window manager may | |
433 ignore these two parameters. | |
434 | |
435 @item icon-top | |
436 The screen position of the top edge @emph{of the frame's icon}, in | |
437 pixels, counting from the top edge of the screen. This takes effect if | |
438 and when the frame is iconified. | |
439 | |
440 @item user-position | |
441 When you create a frame and specify its screen position with the | |
442 @code{left} and @code{top} parameters, use this parameter to say whether | |
443 the specified position was user-specified (explicitly requested in some | |
444 way by a human user) or merely program-specified (chosen by a program). | |
445 A non-@code{nil} value says the position was user-specified. | |
446 | |
447 Window managers generally heed user-specified positions, and some heed | |
448 program-specified positions too. But many ignore program-specified | |
449 positions, placing the window in a default fashion or letting the user | |
450 place it with the mouse. Some window managers, including @code{twm}, | |
451 let the user specify whether to obey program-specified positions or | |
452 ignore them. | |
453 | |
454 When you call @code{make-frame}, you should specify a non-@code{nil} | |
455 value for this parameter if the values of the @code{left} and @code{top} | |
456 parameters represent the user's stated preference; otherwise, use | |
457 @code{nil}. | |
458 @end table | |
459 | |
460 @node Size Parameters | |
461 @subsubsection Size Parameters | |
462 | |
463 Size parameters' values are normally measured in pixels, but on | |
464 text-only terminals they count characters or lines instead. | |
465 | |
466 @table @code | |
467 @item height | |
468 The height of the frame contents, in characters. (To get the height in | |
469 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) | |
470 | |
471 @item width | |
87453 | 472 The width of the frame contents, in characters. (To get the width in |
84068 | 473 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) |
474 | |
475 @item user-size | |
476 This does for the size parameters @code{height} and @code{width} what | |
477 the @code{user-position} parameter (see above) does for the position | |
478 parameters @code{top} and @code{left}. | |
479 | |
480 @item fullscreen | |
481 Specify that width, height or both shall be set to the size of the screen. | |
482 The value @code{fullwidth} specifies that width shall be the size of the | |
483 screen. The value @code{fullheight} specifies that height shall be the | |
484 size of the screen. The value @code{fullboth} specifies that both the | |
485 width and the height shall be set to the size of the screen. | |
486 @end table | |
487 | |
488 @node Layout Parameters | |
489 @subsubsection Layout Parameters | |
490 | |
491 These frame parameters enable or disable various parts of the | |
492 frame, or control their sizes. | |
493 | |
494 @table @code | |
495 @item border-width | |
496 The width in pixels of the frame's border. | |
497 | |
498 @item internal-border-width | |
499 The distance in pixels between text (or fringe) and the frame's border. | |
500 | |
501 @item vertical-scroll-bars | |
502 Whether the frame has scroll bars for vertical scrolling, and which side | |
503 of the frame they should be on. The possible values are @code{left}, | |
504 @code{right}, and @code{nil} for no scroll bars. | |
505 | |
506 @ignore | |
507 @item horizontal-scroll-bars | |
508 Whether the frame has scroll bars for horizontal scrolling | |
509 (non-@code{nil} means yes). Horizontal scroll bars are not currently | |
510 implemented. | |
511 @end ignore | |
512 | |
513 @item scroll-bar-width | |
514 The width of vertical scroll bars, in pixels, or @code{nil} meaning to | |
515 use the default width. | |
516 | |
517 @item left-fringe | |
518 @itemx right-fringe | |
519 The default width of the left and right fringes of windows in this | |
520 frame (@pxref{Fringes}). If either of these is zero, that effectively | |
521 removes the corresponding fringe. A value of @code{nil} stands for | |
522 the standard fringe width, which is the width needed to display the | |
523 fringe bitmaps. | |
524 | |
525 The combined fringe widths must add up to an integral number of | |
526 columns, so the actual default fringe widths for the frame may be | |
527 larger than the specified values. The extra width needed to reach an | |
528 acceptable total is distributed evenly between the left and right | |
529 fringe. However, you can force one fringe or the other to a precise | |
530 width by specifying that width as a negative integer. If both widths are | |
531 negative, only the left fringe gets the specified width. | |
532 | |
533 @item menu-bar-lines | |
534 The number of lines to allocate at the top of the frame for a menu | |
535 bar. The default is 1. A value of @code{nil} means don't display a | |
536 menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one | |
537 menu bar line; they treat larger values as 1.) | |
538 | |
539 @item tool-bar-lines | |
540 The number of lines to use for the tool bar. A value of @code{nil} | |
541 means don't display a tool bar. (GTK allows at most one tool bar line; | |
542 it treats larger values as 1.) | |
543 | |
544 @item line-spacing | |
545 Additional space to leave below each text line, in pixels (a positive | |
546 integer). @xref{Line Height}, for more information. | |
547 @end table | |
548 | |
549 @node Buffer Parameters | |
550 @subsubsection Buffer Parameters | |
551 | |
552 These frame parameters, meaningful on all kinds of terminals, deal | |
553 with which buffers have been, or should, be displayed in the frame. | |
554 | |
555 @table @code | |
556 @item minibuffer | |
557 Whether this frame has its own minibuffer. The value @code{t} means | |
558 yes, @code{nil} means no, @code{only} means this frame is just a | |
559 minibuffer. If the value is a minibuffer window (in some other frame), | |
560 the new frame uses that minibuffer. | |
561 | |
562 @item buffer-predicate | |
563 The buffer-predicate function for this frame. The function | |
564 @code{other-buffer} uses this predicate (from the selected frame) to | |
565 decide which buffers it should consider, if the predicate is not | |
566 @code{nil}. It calls the predicate with one argument, a buffer, once for | |
567 each buffer; if the predicate returns a non-@code{nil} value, it | |
568 considers that buffer. | |
569 | |
570 @item buffer-list | |
571 A list of buffers that have been selected in this frame, | |
572 ordered most-recently-selected first. | |
573 | |
574 @item unsplittable | |
575 If non-@code{nil}, this frame's window is never split automatically. | |
576 @end table | |
577 | |
578 @node Management Parameters | |
579 @subsubsection Window Management Parameters | |
580 @cindex window manager, and frame parameters | |
581 | |
582 These frame parameters, meaningful only on window system displays, | |
583 interact with the window manager. | |
584 | |
585 @table @code | |
586 @item visibility | |
587 The state of visibility of the frame. There are three possibilities: | |
588 @code{nil} for invisible, @code{t} for visible, and @code{icon} for | |
589 iconified. @xref{Visibility of Frames}. | |
590 | |
591 @item auto-raise | |
592 Whether selecting the frame raises it (non-@code{nil} means yes). | |
593 | |
594 @item auto-lower | |
595 Whether deselecting the frame lowers it (non-@code{nil} means yes). | |
596 | |
597 @item icon-type | |
598 The type of icon to use for this frame when it is iconified. If the | |
599 value is a string, that specifies a file containing a bitmap to use. | |
600 Any other non-@code{nil} value specifies the default bitmap icon (a | |
601 picture of a gnu); @code{nil} specifies a text icon. | |
602 | |
603 @item icon-name | |
604 The name to use in the icon for this frame, when and if the icon | |
605 appears. If this is @code{nil}, the frame's title is used. | |
606 | |
607 @item window-id | |
608 The number of the window-system window used by the frame | |
609 to contain the actual Emacs windows. | |
610 | |
611 @item outer-window-id | |
612 The number of the outermost window-system window used for the whole frame. | |
613 | |
614 @item wait-for-wm | |
615 If non-@code{nil}, tell Xt to wait for the window manager to confirm | |
616 geometry changes. Some window managers, including versions of Fvwm2 | |
617 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to | |
618 prevent hanging with those window managers. | |
619 | |
620 @ignore | |
621 @item parent-id | |
622 @c ??? Not yet working. | |
623 The X window number of the window that should be the parent of this one. | |
624 Specifying this lets you create an Emacs window inside some other | |
625 application's window. (It is not certain this will be implemented; try | |
626 it and see if it works.) | |
627 @end ignore | |
628 @end table | |
629 | |
630 @node Cursor Parameters | |
631 @subsubsection Cursor Parameters | |
632 | |
633 This frame parameter controls the way the cursor looks. | |
634 | |
635 @table @code | |
636 @item cursor-type | |
637 How to display the cursor. Legitimate values are: | |
638 | |
639 @table @code | |
640 @item box | |
641 Display a filled box. (This is the default.) | |
642 @item hollow | |
643 Display a hollow box. | |
644 @item nil | |
645 Don't display a cursor. | |
646 @item bar | |
647 Display a vertical bar between characters. | |
648 @item (bar . @var{width}) | |
649 Display a vertical bar @var{width} pixels wide between characters. | |
650 @item hbar | |
651 Display a horizontal bar. | |
652 @item (hbar . @var{height}) | |
653 Display a horizontal bar @var{height} pixels high. | |
654 @end table | |
655 @end table | |
656 | |
657 @vindex cursor-type | |
658 The buffer-local variable @code{cursor-type} overrides the value of | |
659 the @code{cursor-type} frame parameter, but if it is @code{t}, that | |
660 means to use the cursor specified for the frame. | |
661 | |
662 @defvar blink-cursor-alist | |
663 This variable specifies how to blink the cursor. Each element has the | |
664 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor | |
665 type equals @var{on-state} (comparing using @code{equal}), the | |
666 corresponding @var{off-state} specifies what the cursor looks like | |
667 when it blinks ``off.'' Both @var{on-state} and @var{off-state} | |
668 should be suitable values for the @code{cursor-type} frame parameter. | |
669 | |
670 There are various defaults for how to blink each type of cursor, if | |
671 the type is not mentioned as an @var{on-state} here. Changes in this | |
85114 | 672 variable do not take effect immediately, only when you specify the |
673 @code{cursor-type} frame parameter. | |
674 @end defvar | |
675 | |
676 @defvar cursor-in-non-selected-windows | |
677 This variable controls how the cursor looks in a window that is not | |
678 selected. It supports the same values as the @code{cursor-type} frame | |
679 parameter; also, @code{nil} means don't display a cursor in | |
680 nonselected windows, and @code{t} (the default) means use a standard | |
681 modificatoin of the usual cursor type (solid box becomes hollow box, | |
682 and bar becomes a narrower bar). | |
84068 | 683 @end defvar |
684 | |
685 @node Color Parameters | |
686 @subsubsection Color Parameters | |
687 | |
688 These frame parameters control the use of colors. | |
689 | |
690 @table @code | |
691 @item background-mode | |
692 This parameter is either @code{dark} or @code{light}, according | |
693 to whether the background color is a light one or a dark one. | |
694 | |
695 @item tty-color-mode | |
696 @cindex standard colors for character terminals | |
697 This parameter overrides the terminal's color support as given by the | |
698 system's terminal capabilities database in that this parameter's value | |
699 specifies the color mode to use in terminal frames. The value can be | |
700 either a symbol or a number. A number specifies the number of colors | |
701 to use (and, indirectly, what commands to issue to produce each | |
702 color). For example, @code{(tty-color-mode . 8)} specifies use of the | |
703 ANSI escape sequences for 8 standard text colors. A value of -1 turns | |
704 off color support. | |
705 | |
706 If the parameter's value is a symbol, it specifies a number through | |
707 the value of @code{tty-color-mode-alist}, and the associated number is | |
708 used instead. | |
709 | |
710 @item screen-gamma | |
711 @cindex gamma correction | |
712 If this is a number, Emacs performs ``gamma correction'' which adjusts | |
713 the brightness of all colors. The value should be the screen gamma of | |
714 your display, a floating point number. | |
715 | |
716 Usual PC monitors have a screen gamma of 2.2, so color values in | |
717 Emacs, and in X windows generally, are calibrated to display properly | |
718 on a monitor with that gamma value. If you specify 2.2 for | |
719 @code{screen-gamma}, that means no correction is needed. Other values | |
720 request correction, designed to make the corrected colors appear on | |
721 your screen the way they would have appeared without correction on an | |
722 ordinary monitor with a gamma value of 2.2. | |
723 | |
724 If your monitor displays colors too light, you should specify a | |
725 @code{screen-gamma} value smaller than 2.2. This requests correction | |
726 that makes colors darker. A screen gamma value of 1.5 may give good | |
727 results for LCD color displays. | |
728 @end table | |
729 | |
730 These frame parameters are semi-obsolete in that they are automatically | |
731 equivalent to particular face attributes of particular faces. | |
732 @xref{Standard Faces,,, emacs, The Emacs Manual}. | |
733 | |
734 @table @code | |
735 @item font | |
736 The name of the font for displaying text in the frame. This is a | |
737 string, either a valid font name for your system or the name of an Emacs | |
738 fontset (@pxref{Fontsets}). It is equivalent to the @code{font} | |
739 attribute of the @code{default} face. | |
740 | |
741 @item foreground-color | |
742 The color to use for the image of a character. It is equivalent to | |
743 the @code{:foreground} attribute of the @code{default} face. | |
744 | |
745 @item background-color | |
746 The color to use for the background of characters. It is equivalent to | |
747 the @code{:background} attribute of the @code{default} face. | |
748 | |
749 @item mouse-color | |
750 The color for the mouse pointer. It is equivalent to the @code{:background} | |
751 attribute of the @code{mouse} face. | |
752 | |
753 @item cursor-color | |
754 The color for the cursor that shows point. It is equivalent to the | |
755 @code{:background} attribute of the @code{cursor} face. | |
756 | |
757 @item border-color | |
758 The color for the border of the frame. It is equivalent to the | |
759 @code{:background} attribute of the @code{border} face. | |
760 | |
761 @item scroll-bar-foreground | |
762 If non-@code{nil}, the color for the foreground of scroll bars. It is | |
763 equivalent to the @code{:foreground} attribute of the | |
764 @code{scroll-bar} face. | |
765 | |
766 @item scroll-bar-background | |
767 If non-@code{nil}, the color for the background of scroll bars. It is | |
768 equivalent to the @code{:background} attribute of the | |
769 @code{scroll-bar} face. | |
770 @end table | |
771 | |
772 @node Size and Position | |
773 @subsection Frame Size And Position | |
774 @cindex size of frame | |
775 @cindex screen size | |
776 @cindex frame size | |
777 @cindex resize frame | |
778 | |
779 You can read or change the size and position of a frame using the | |
780 frame parameters @code{left}, @code{top}, @code{height}, and | |
781 @code{width}. Whatever geometry parameters you don't specify are chosen | |
782 by the window manager in its usual fashion. | |
783 | |
784 Here are some special features for working with sizes and positions. | |
785 (For the precise meaning of ``selected frame'' used by these functions, | |
786 see @ref{Input Focus}.) | |
787 | |
788 @defun set-frame-position frame left top | |
789 This function sets the position of the top left corner of @var{frame} to | |
790 @var{left} and @var{top}. These arguments are measured in pixels, and | |
791 normally count from the top left corner of the screen. | |
792 | |
793 Negative parameter values position the bottom edge of the window up from | |
794 the bottom edge of the screen, or the right window edge to the left of | |
795 the right edge of the screen. It would probably be better if the values | |
796 were always counted from the left and top, so that negative arguments | |
797 would position the frame partly off the top or left edge of the screen, | |
798 but it seems inadvisable to change that now. | |
799 @end defun | |
800 | |
801 @defun frame-height &optional frame | |
802 @defunx frame-width &optional frame | |
803 These functions return the height and width of @var{frame}, measured in | |
804 lines and columns. If you don't supply @var{frame}, they use the | |
805 selected frame. | |
806 @end defun | |
807 | |
808 @defun screen-height | |
809 @defunx screen-width | |
810 These functions are old aliases for @code{frame-height} and | |
811 @code{frame-width}. When you are using a non-window terminal, the size | |
812 of the frame is normally the same as the size of the terminal screen. | |
813 @end defun | |
814 | |
815 @defun frame-pixel-height &optional frame | |
816 @defunx frame-pixel-width &optional frame | |
87453 | 817 These functions return the height and width of the main display area |
818 of @var{frame}, measured in pixels. If you don't supply @var{frame}, | |
819 they use the selected frame. | |
820 | |
821 These values include the internal borders, and windows' scroll bars | |
822 and fringes (which belong to individual windows, not to the frame | |
823 itself), but do not include menu bars or tool bars (except when using | |
824 X without an X toolkit). | |
84068 | 825 @end defun |
826 | |
827 @defun frame-char-height &optional frame | |
828 @defunx frame-char-width &optional frame | |
829 These functions return the height and width of a character in | |
830 @var{frame}, measured in pixels. The values depend on the choice of | |
831 font. If you don't supply @var{frame}, these functions use the selected | |
832 frame. | |
833 @end defun | |
834 | |
835 @defun set-frame-size frame cols rows | |
836 This function sets the size of @var{frame}, measured in characters; | |
837 @var{cols} and @var{rows} specify the new width and height. | |
838 | |
839 To set the size based on values measured in pixels, use | |
840 @code{frame-char-height} and @code{frame-char-width} to convert | |
841 them to units of characters. | |
842 @end defun | |
843 | |
844 @defun set-frame-height frame lines &optional pretend | |
845 This function resizes @var{frame} to a height of @var{lines} lines. The | |
846 sizes of existing windows in @var{frame} are altered proportionally to | |
847 fit. | |
848 | |
849 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines} | |
850 lines of output in @var{frame}, but does not change its value for the | |
851 actual height of the frame. This is only useful for a terminal frame. | |
852 Using a smaller height than the terminal actually implements may be | |
853 useful to reproduce behavior observed on a smaller screen, or if the | |
854 terminal malfunctions when using its whole screen. Setting the frame | |
855 height ``for real'' does not always work, because knowing the correct | |
856 actual size may be necessary for correct cursor positioning on a | |
857 terminal frame. | |
858 @end defun | |
859 | |
860 @defun set-frame-width frame width &optional pretend | |
861 This function sets the width of @var{frame}, measured in characters. | |
862 The argument @var{pretend} has the same meaning as in | |
863 @code{set-frame-height}. | |
864 @end defun | |
865 | |
866 @findex set-screen-height | |
867 @findex set-screen-width | |
868 The older functions @code{set-screen-height} and | |
869 @code{set-screen-width} were used to specify the height and width of the | |
870 screen, in Emacs versions that did not support multiple frames. They | |
871 are semi-obsolete, but still work; they apply to the selected frame. | |
872 | |
873 @node Geometry | |
874 @subsection Geometry | |
875 | |
876 Here's how to examine the data in an X-style window geometry | |
877 specification: | |
878 | |
879 @defun x-parse-geometry geom | |
880 @cindex geometry specification | |
881 The function @code{x-parse-geometry} converts a standard X window | |
882 geometry string to an alist that you can use as part of the argument to | |
883 @code{make-frame}. | |
884 | |
885 The alist describes which parameters were specified in @var{geom}, and | |
886 gives the values specified for them. Each element looks like | |
887 @code{(@var{parameter} . @var{value})}. The possible @var{parameter} | |
888 values are @code{left}, @code{top}, @code{width}, and @code{height}. | |
889 | |
890 For the size parameters, the value must be an integer. The position | |
891 parameter names @code{left} and @code{top} are not totally accurate, | |
892 because some values indicate the position of the right or bottom edges | |
92096
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
893 instead. The @var{value} possibilities for the position parameters are: |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
894 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})}; |
6cc4c897d108
(Position Parameters): Clarify the description of `left' and `top',
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
895 as previously described (@pxref{Position Parameters}). |
84068 | 896 |
897 Here is an example: | |
898 | |
899 @example | |
900 (x-parse-geometry "35x70+0-0") | |
901 @result{} ((height . 70) (width . 35) | |
902 (top - 0) (left . 0)) | |
903 @end example | |
904 @end defun | |
905 | |
906 @node Frame Titles | |
907 @section Frame Titles | |
908 @cindex frame title | |
909 | |
910 Every frame has a @code{name} parameter; this serves as the default | |
911 for the frame title which window systems typically display at the top of | |
912 the frame. You can specify a name explicitly by setting the @code{name} | |
913 frame property. | |
914 | |
915 Normally you don't specify the name explicitly, and Emacs computes the | |
916 frame name automatically based on a template stored in the variable | |
917 @code{frame-title-format}. Emacs recomputes the name each time the | |
918 frame is redisplayed. | |
919 | |
920 @defvar frame-title-format | |
921 This variable specifies how to compute a name for a frame when you have | |
922 not explicitly specified one. The variable's value is actually a mode | |
923 line construct, just like @code{mode-line-format}, except that the | |
924 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line | |
925 Data}. | |
926 @end defvar | |
927 | |
928 @defvar icon-title-format | |
929 This variable specifies how to compute the name for an iconified frame, | |
930 when you have not explicitly specified the frame title. This title | |
931 appears in the icon itself. | |
932 @end defvar | |
933 | |
934 @defvar multiple-frames | |
935 This variable is set automatically by Emacs. Its value is @code{t} when | |
936 there are two or more frames (not counting minibuffer-only frames or | |
937 invisible frames). The default value of @code{frame-title-format} uses | |
938 @code{multiple-frames} so as to put the buffer name in the frame title | |
939 only when there is more than one frame. | |
940 | |
941 The value of this variable is not guaranteed to be accurate except | |
942 while processing @code{frame-title-format} or | |
943 @code{icon-title-format}. | |
944 @end defvar | |
945 | |
946 @node Deleting Frames | |
947 @section Deleting Frames | |
948 @cindex deleting frames | |
949 | |
950 Frames remain potentially visible until you explicitly @dfn{delete} | |
951 them. A deleted frame cannot appear on the screen, but continues to | |
952 exist as a Lisp object until there are no references to it. | |
953 | |
954 @deffn Command delete-frame &optional frame force | |
955 @vindex delete-frame-functions | |
956 This function deletes the frame @var{frame}. Unless @var{frame} is a | |
957 tooltip, it first runs the hook @code{delete-frame-functions} (each | |
958 function gets one argument, @var{frame}). By default, @var{frame} is | |
959 the selected frame. | |
960 | |
961 A frame cannot be deleted if its minibuffer is used by other frames. | |
962 Normally, you cannot delete a frame if all other frames are invisible, | |
963 but if the @var{force} is non-@code{nil}, then you are allowed to do so. | |
964 @end deffn | |
965 | |
966 @defun frame-live-p frame | |
967 The function @code{frame-live-p} returns non-@code{nil} if the frame | |
968 @var{frame} has not been deleted. The possible non-@code{nil} return | |
969 values are like those of @code{framep}. @xref{Frames}. | |
970 @end defun | |
971 | |
972 Some window managers provide a command to delete a window. These work | |
973 by sending a special message to the program that operates the window. | |
974 When Emacs gets one of these commands, it generates a | |
975 @code{delete-frame} event, whose normal definition is a command that | |
976 calls the function @code{delete-frame}. @xref{Misc Events}. | |
977 | |
978 @node Finding All Frames | |
979 @section Finding All Frames | |
980 @cindex frames, scanning all | |
981 | |
982 @defun frame-list | |
983 The function @code{frame-list} returns a list of all the frames that | |
984 have not been deleted. It is analogous to @code{buffer-list} for | |
985 buffers, and includes frames on all terminals. The list that you get is | |
986 newly created, so modifying the list doesn't have any effect on the | |
987 internals of Emacs. | |
988 @end defun | |
989 | |
990 @defun visible-frame-list | |
991 This function returns a list of just the currently visible frames. | |
992 @xref{Visibility of Frames}. (Terminal frames always count as | |
993 ``visible,'' even though only the selected one is actually displayed.) | |
994 @end defun | |
995 | |
996 @defun next-frame &optional frame minibuf | |
997 The function @code{next-frame} lets you cycle conveniently through all | |
998 the frames on the current display from an arbitrary starting point. It | |
999 returns the ``next'' frame after @var{frame} in the cycle. If | |
1000 @var{frame} is omitted or @code{nil}, it defaults to the selected frame | |
1001 (@pxref{Input Focus}). | |
1002 | |
1003 The second argument, @var{minibuf}, says which frames to consider: | |
1004 | |
1005 @table @asis | |
1006 @item @code{nil} | |
1007 Exclude minibuffer-only frames. | |
1008 @item @code{visible} | |
1009 Consider all visible frames. | |
1010 @item 0 | |
1011 Consider all visible or iconified frames. | |
1012 @item a window | |
1013 Consider only the frames using that particular window as their | |
1014 minibuffer. | |
1015 @item anything else | |
1016 Consider all frames. | |
1017 @end table | |
1018 @end defun | |
1019 | |
1020 @defun previous-frame &optional frame minibuf | |
1021 Like @code{next-frame}, but cycles through all frames in the opposite | |
1022 direction. | |
1023 @end defun | |
1024 | |
1025 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic | |
1026 Window Ordering}. | |
1027 | |
1028 @node Frames and Windows | |
1029 @section Frames and Windows | |
1030 | |
1031 Each window is part of one and only one frame; you can get the frame | |
1032 with @code{window-frame}. | |
1033 | |
1034 @defun window-frame window | |
1035 This function returns the frame that @var{window} is on. | |
1036 @end defun | |
1037 | |
1038 All the non-minibuffer windows in a frame are arranged in a cyclic | |
1039 order. The order runs from the frame's top window, which is at the | |
1040 upper left corner, down and to the right, until it reaches the window at | |
1041 the lower right corner (always the minibuffer window, if the frame has | |
1042 one), and then it moves back to the top. @xref{Cyclic Window Ordering}. | |
1043 | |
1044 @defun frame-first-window &optional frame | |
1045 This returns the topmost, leftmost window of frame @var{frame}. | |
1046 If omitted or @code{nil}, @var{frame} defaults to the selected frame. | |
1047 @end defun | |
1048 | |
1049 At any time, exactly one window on any frame is @dfn{selected within the | |
1050 frame}. The significance of this designation is that selecting the | |
1051 frame also selects this window. You can get the frame's current | |
1052 selected window with @code{frame-selected-window}. | |
1053 | |
1054 @defun frame-selected-window &optional frame | |
1055 This function returns the window on @var{frame} that is selected | |
1056 within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to | |
1057 the selected frame. | |
1058 @end defun | |
1059 | |
1060 @defun set-frame-selected-window frame window | |
1061 This sets the selected window of frame @var{frame} to @var{window}. | |
1062 If @var{frame} is @code{nil}, it operates on the selected frame. If | |
1063 @var{frame} is the selected frame, this makes @var{window} the | |
1064 selected window. This function returns @var{window}. | |
1065 @end defun | |
1066 | |
1067 Conversely, selecting a window for Emacs with @code{select-window} also | |
1068 makes that window selected within its frame. @xref{Selecting Windows}. | |
1069 | |
1070 Another function that (usually) returns one of the windows in a given | |
1071 frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}. | |
1072 | |
1073 @node Minibuffers and Frames | |
1074 @section Minibuffers and Frames | |
1075 | |
1076 Normally, each frame has its own minibuffer window at the bottom, which | |
1077 is used whenever that frame is selected. If the frame has a minibuffer, | |
1078 you can get it with @code{minibuffer-window} (@pxref{Definition of | |
1079 minibuffer-window}). | |
1080 | |
1081 However, you can also create a frame with no minibuffer. Such a frame | |
1082 must use the minibuffer window of some other frame. When you create the | |
1083 frame, you can specify explicitly the minibuffer window to use (in some | |
1084 other frame). If you don't, then the minibuffer is found in the frame | |
1085 which is the value of the variable @code{default-minibuffer-frame}. Its | |
1086 value should be a frame that does have a minibuffer. | |
1087 | |
1088 If you use a minibuffer-only frame, you might want that frame to raise | |
1089 when you enter the minibuffer. If so, set the variable | |
1090 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}. | |
1091 | |
1092 @defvar default-minibuffer-frame | |
1093 This variable specifies the frame to use for the minibuffer window, by | |
1094 default. It does not affect existing frames. It is always local to | |
1095 the current terminal and cannot be buffer-local. @xref{Multiple | |
1096 Displays}. | |
1097 @end defvar | |
1098 | |
1099 @node Input Focus | |
1100 @section Input Focus | |
1101 @cindex input focus | |
1102 @c @cindex selected frame Duplicates selected-frame | |
1103 | |
1104 At any time, one frame in Emacs is the @dfn{selected frame}. The selected | |
1105 window always resides on the selected frame. | |
1106 | |
1107 When Emacs displays its frames on several terminals (@pxref{Multiple | |
1108 Displays}), each terminal has its own selected frame. But only one of | |
1109 these is ``@emph{the} selected frame'': it's the frame that belongs to | |
1110 the terminal from which the most recent input came. That is, when Emacs | |
1111 runs a command that came from a certain terminal, the selected frame is | |
1112 the one of that terminal. Since Emacs runs only a single command at any | |
1113 given time, it needs to consider only one selected frame at a time; this | |
1114 frame is what we call @dfn{the selected frame} in this manual. The | |
1115 display on which the selected frame is displayed is the @dfn{selected | |
1116 frame's display}. | |
1117 | |
1118 @defun selected-frame | |
1119 This function returns the selected frame. | |
1120 @end defun | |
1121 | |
1122 Some window systems and window managers direct keyboard input to the | |
1123 window object that the mouse is in; others require explicit clicks or | |
1124 commands to @dfn{shift the focus} to various window objects. Either | |
1125 way, Emacs automatically keeps track of which frame has the focus. To | |
1126 switch to a different frame from a Lisp function, call | |
1127 @code{select-frame-set-input-focus}. | |
1128 | |
1129 Lisp programs can also switch frames ``temporarily'' by calling the | |
1130 function @code{select-frame}. This does not alter the window system's | |
1131 concept of focus; rather, it escapes from the window manager's control | |
1132 until that control is somehow reasserted. | |
1133 | |
1134 When using a text-only terminal, only one frame can be displayed at a | |
1135 time on the terminal, so after a call to @code{select-frame}, the next | |
1136 redisplay actually displays the newly selected frame. This frame | |
1137 remains selected until a subsequent call to @code{select-frame} or | |
1138 @code{select-frame-set-input-focus}. Each terminal frame has a number | |
1139 which appears in the mode line before the buffer name (@pxref{Mode | |
1140 Line Variables}). | |
1141 | |
1142 @defun select-frame-set-input-focus frame | |
1143 This function makes @var{frame} the selected frame, raises it (should | |
1144 it happen to be obscured by other frames) and tries to give it the X | |
1145 server's focus. On a text-only terminal, the next redisplay displays | |
1146 the new frame on the entire terminal screen. The return value of this | |
1147 function is not significant. | |
1148 @end defun | |
1149 | |
1150 @c ??? This is not yet implemented properly. | |
1151 @defun select-frame frame | |
1152 This function selects frame @var{frame}, temporarily disregarding the | |
1153 focus of the X server if any. The selection of @var{frame} lasts until | |
1154 the next time the user does something to select a different frame, or | |
1155 until the next time this function is called. (If you are using a | |
1156 window system, the previously selected frame may be restored as the | |
1157 selected frame after return to the command loop, because it still may | |
1158 have the window system's input focus.) The specified @var{frame} | |
1159 becomes the selected frame, as explained above, and the terminal that | |
1160 @var{frame} is on becomes the selected terminal. This function | |
1161 returns @var{frame}, or @code{nil} if @var{frame} has been deleted. | |
1162 | |
1163 In general, you should never use @code{select-frame} in a way that could | |
1164 switch to a different terminal without switching back when you're done. | |
1165 @end defun | |
1166 | |
1167 Emacs cooperates with the window system by arranging to select frames as | |
1168 the server and window manager request. It does so by generating a | |
1169 special kind of input event, called a @dfn{focus} event, when | |
1170 appropriate. The command loop handles a focus event by calling | |
1171 @code{handle-switch-frame}. @xref{Focus Events}. | |
1172 | |
1173 @deffn Command handle-switch-frame frame | |
1174 This function handles a focus event by selecting frame @var{frame}. | |
1175 | |
1176 Focus events normally do their job by invoking this command. | |
1177 Don't call it for any other reason. | |
1178 @end deffn | |
1179 | |
1180 @defun redirect-frame-focus frame &optional focus-frame | |
1181 This function redirects focus from @var{frame} to @var{focus-frame}. | |
1182 This means that @var{focus-frame} will receive subsequent keystrokes and | |
1183 events intended for @var{frame}. After such an event, the value of | |
1184 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame | |
1185 events specifying @var{frame} will instead select @var{focus-frame}. | |
1186 | |
1187 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing | |
1188 redirection for @var{frame}, which therefore once again receives its own | |
1189 events. | |
1190 | |
1191 One use of focus redirection is for frames that don't have minibuffers. | |
1192 These frames use minibuffers on other frames. Activating a minibuffer | |
1193 on another frame redirects focus to that frame. This puts the focus on | |
1194 the minibuffer's frame, where it belongs, even though the mouse remains | |
1195 in the frame that activated the minibuffer. | |
1196 | |
1197 Selecting a frame can also change focus redirections. Selecting frame | |
1198 @code{bar}, when @code{foo} had been selected, changes any redirections | |
1199 pointing to @code{foo} so that they point to @code{bar} instead. This | |
1200 allows focus redirection to work properly when the user switches from | |
1201 one frame to another using @code{select-window}. | |
1202 | |
1203 This means that a frame whose focus is redirected to itself is treated | |
1204 differently from a frame whose focus is not redirected. | |
1205 @code{select-frame} affects the former but not the latter. | |
1206 | |
1207 The redirection lasts until @code{redirect-frame-focus} is called to | |
1208 change it. | |
1209 @end defun | |
1210 | |
1211 @defopt focus-follows-mouse | |
1212 This option is how you inform Emacs whether the window manager transfers | |
1213 focus when the user moves the mouse. Non-@code{nil} says that it does. | |
1214 When this is so, the command @code{other-frame} moves the mouse to a | |
1215 position consistent with the new selected frame. (This option has no | |
1216 effect on MS-Windows, where the mouse pointer is always automatically | |
1217 moved by the OS to the selected frame.) | |
1218 @end defopt | |
1219 | |
1220 @node Visibility of Frames | |
1221 @section Visibility of Frames | |
1222 @cindex visible frame | |
1223 @cindex invisible frame | |
1224 @cindex iconified frame | |
1225 @cindex frame visibility | |
1226 | |
1227 A window frame may be @dfn{visible}, @dfn{invisible}, or | |
1228 @dfn{iconified}. If it is visible, you can see its contents, unless | |
1229 other windows cover it. If it is iconified, the frame's contents do | |
1230 not appear on the screen, but an icon does. If the frame is | |
1231 invisible, it doesn't show on the screen, not even as an icon. | |
1232 | |
1233 Visibility is meaningless for terminal frames, since only the selected | |
1234 one is actually displayed in any case. | |
1235 | |
1236 @deffn Command make-frame-visible &optional frame | |
1237 This function makes frame @var{frame} visible. If you omit | |
1238 @var{frame}, it makes the selected frame visible. This does not raise | |
1239 the frame, but you can do that with @code{raise-frame} if you wish | |
1240 (@pxref{Raising and Lowering}). | |
1241 @end deffn | |
1242 | |
1243 @deffn Command make-frame-invisible &optional frame force | |
1244 This function makes frame @var{frame} invisible. If you omit | |
1245 @var{frame}, it makes the selected frame invisible. | |
1246 | |
1247 Unless @var{force} is non-@code{nil}, this function refuses to make | |
1248 @var{frame} invisible if all other frames are invisible.. | |
1249 @end deffn | |
1250 | |
1251 @deffn Command iconify-frame &optional frame | |
1252 This function iconifies frame @var{frame}. If you omit @var{frame}, it | |
1253 iconifies the selected frame. | |
1254 @end deffn | |
1255 | |
1256 @defun frame-visible-p frame | |
1257 This returns the visibility status of frame @var{frame}. The value is | |
1258 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and | |
1259 @code{icon} if it is iconified. | |
1260 | |
1261 On a text-only terminal, all frames are considered visible, whether | |
1262 they are currently being displayed or not, and this function returns | |
1263 @code{t} for all frames. | |
1264 @end defun | |
1265 | |
1266 The visibility status of a frame is also available as a frame | |
1267 parameter. You can read or change it as such. @xref{Management | |
1268 Parameters}. | |
1269 | |
1270 The user can iconify and deiconify frames with the window manager. | |
1271 This happens below the level at which Emacs can exert any control, but | |
1272 Emacs does provide events that you can use to keep track of such | |
1273 changes. @xref{Misc Events}. | |
1274 | |
1275 @node Raising and Lowering | |
1276 @section Raising and Lowering Frames | |
1277 | |
1278 Most window systems use a desktop metaphor. Part of this metaphor is | |
1279 the idea that windows are stacked in a notional third dimension | |
1280 perpendicular to the screen surface, and thus ordered from ``highest'' | |
1281 to ``lowest.'' Where two windows overlap, the one higher up covers | |
1282 the one underneath. Even a window at the bottom of the stack can be | |
1283 seen if no other window overlaps it. | |
1284 | |
1285 @c @cindex raising a frame redundant with raise-frame | |
1286 @cindex lowering a frame | |
1287 A window's place in this ordering is not fixed; in fact, users tend | |
1288 to change the order frequently. @dfn{Raising} a window means moving | |
1289 it ``up,'' to the top of the stack. @dfn{Lowering} a window means | |
1290 moving it to the bottom of the stack. This motion is in the notional | |
1291 third dimension only, and does not change the position of the window | |
1292 on the screen. | |
1293 | |
1294 You can raise and lower Emacs frame Windows with these functions: | |
1295 | |
1296 @deffn Command raise-frame &optional frame | |
1297 This function raises frame @var{frame} (default, the selected frame). | |
1298 If @var{frame} is invisible or iconified, this makes it visible. | |
1299 @end deffn | |
1300 | |
1301 @deffn Command lower-frame &optional frame | |
1302 This function lowers frame @var{frame} (default, the selected frame). | |
1303 @end deffn | |
1304 | |
1305 @defopt minibuffer-auto-raise | |
1306 If this is non-@code{nil}, activation of the minibuffer raises the frame | |
1307 that the minibuffer window is in. | |
1308 @end defopt | |
1309 | |
1310 You can also enable auto-raise (raising automatically when a frame is | |
1311 selected) or auto-lower (lowering automatically when it is deselected) | |
1312 for any frame using frame parameters. @xref{Management Parameters}. | |
1313 | |
1314 @node Frame Configurations | |
1315 @section Frame Configurations | |
1316 @cindex frame configuration | |
1317 | |
1318 A @dfn{frame configuration} records the current arrangement of frames, | |
1319 all their properties, and the window configuration of each one. | |
1320 (@xref{Window Configurations}.) | |
1321 | |
1322 @defun current-frame-configuration | |
1323 This function returns a frame configuration list that describes | |
1324 the current arrangement of frames and their contents. | |
1325 @end defun | |
1326 | |
1327 @defun set-frame-configuration configuration &optional nodelete | |
1328 This function restores the state of frames described in | |
1329 @var{configuration}. However, this function does not restore deleted | |
1330 frames. | |
1331 | |
1332 Ordinarily, this function deletes all existing frames not listed in | |
1333 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the | |
1334 unwanted frames are iconified instead. | |
1335 @end defun | |
1336 | |
1337 @node Mouse Tracking | |
1338 @section Mouse Tracking | |
1339 @cindex mouse tracking | |
1340 @c @cindex tracking the mouse Duplicates track-mouse | |
1341 | |
1342 Sometimes it is useful to @dfn{track} the mouse, which means to display | |
1343 something to indicate where the mouse is and move the indicator as the | |
1344 mouse moves. For efficient mouse tracking, you need a way to wait until | |
1345 the mouse actually moves. | |
1346 | |
1347 The convenient way to track the mouse is to ask for events to represent | |
1348 mouse motion. Then you can wait for motion by waiting for an event. In | |
1349 addition, you can easily handle any other sorts of events that may | |
1350 occur. That is useful, because normally you don't want to track the | |
1351 mouse forever---only until some other event, such as the release of a | |
1352 button. | |
1353 | |
1354 @defspec track-mouse body@dots{} | |
1355 This special form executes @var{body}, with generation of mouse motion | |
1356 events enabled. Typically @var{body} would use @code{read-event} to | |
1357 read the motion events and modify the display accordingly. @xref{Motion | |
1358 Events}, for the format of mouse motion events. | |
1359 | |
1360 The value of @code{track-mouse} is that of the last form in @var{body}. | |
1361 You should design @var{body} to return when it sees the up-event that | |
1362 indicates the release of the button, or whatever kind of event means | |
1363 it is time to stop tracking. | |
1364 @end defspec | |
1365 | |
1366 The usual purpose of tracking mouse motion is to indicate on the screen | |
1367 the consequences of pushing or releasing a button at the current | |
1368 position. | |
1369 | |
1370 In many cases, you can avoid the need to track the mouse by using | |
1371 the @code{mouse-face} text property (@pxref{Special Properties}). | |
1372 That works at a much lower level and runs more smoothly than | |
1373 Lisp-level mouse tracking. | |
1374 | |
1375 @ignore | |
1376 @c These are not implemented yet. | |
1377 | |
1378 These functions change the screen appearance instantaneously. The | |
1379 effect is transient, only until the next ordinary Emacs redisplay. That | |
1380 is OK for mouse tracking, since it doesn't make sense for mouse tracking | |
1381 to change the text, and the body of @code{track-mouse} normally reads | |
1382 the events itself and does not do redisplay. | |
1383 | |
1384 @defun x-contour-region window beg end | |
1385 This function draws lines to make a box around the text from @var{beg} | |
1386 to @var{end}, in window @var{window}. | |
1387 @end defun | |
1388 | |
1389 @defun x-uncontour-region window beg end | |
1390 This function erases the lines that would make a box around the text | |
1391 from @var{beg} to @var{end}, in window @var{window}. Use it to remove | |
1392 a contour that you previously made by calling @code{x-contour-region}. | |
1393 @end defun | |
1394 | |
1395 @defun x-draw-rectangle frame left top right bottom | |
1396 This function draws a hollow rectangle on frame @var{frame} with the | |
1397 specified edge coordinates, all measured in pixels from the inside top | |
1398 left corner. It uses the cursor color, the one used for indicating the | |
1399 location of point. | |
1400 @end defun | |
1401 | |
1402 @defun x-erase-rectangle frame left top right bottom | |
1403 This function erases a hollow rectangle on frame @var{frame} with the | |
1404 specified edge coordinates, all measured in pixels from the inside top | |
1405 left corner. Erasure means redrawing the text and background that | |
1406 normally belong in the specified rectangle. | |
1407 @end defun | |
1408 @end ignore | |
1409 | |
1410 @node Mouse Position | |
1411 @section Mouse Position | |
1412 @cindex mouse position | |
1413 @cindex position of mouse | |
1414 | |
1415 The functions @code{mouse-position} and @code{set-mouse-position} | |
1416 give access to the current position of the mouse. | |
1417 | |
1418 @defun mouse-position | |
1419 This function returns a description of the position of the mouse. The | |
1420 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} | |
1421 and @var{y} are integers giving the position in characters relative to | |
1422 the top left corner of the inside of @var{frame}. | |
1423 @end defun | |
1424 | |
1425 @defvar mouse-position-function | |
1426 If non-@code{nil}, the value of this variable is a function for | |
1427 @code{mouse-position} to call. @code{mouse-position} calls this | |
1428 function just before returning, with its normal return value as the | |
1429 sole argument, and it returns whatever this function returns to it. | |
1430 | |
1431 This abnormal hook exists for the benefit of packages like | |
1432 @file{xt-mouse.el} that need to do mouse handling at the Lisp level. | |
1433 @end defvar | |
1434 | |
1435 @defun set-mouse-position frame x y | |
1436 This function @dfn{warps the mouse} to position @var{x}, @var{y} in | |
1437 frame @var{frame}. The arguments @var{x} and @var{y} are integers, | |
1438 giving the position in characters relative to the top left corner of the | |
1439 inside of @var{frame}. If @var{frame} is not visible, this function | |
1440 does nothing. The return value is not significant. | |
1441 @end defun | |
1442 | |
1443 @defun mouse-pixel-position | |
1444 This function is like @code{mouse-position} except that it returns | |
1445 coordinates in units of pixels rather than units of characters. | |
1446 @end defun | |
1447 | |
1448 @defun set-mouse-pixel-position frame x y | |
1449 This function warps the mouse like @code{set-mouse-position} except that | |
1450 @var{x} and @var{y} are in units of pixels rather than units of | |
1451 characters. These coordinates are not required to be within the frame. | |
1452 | |
1453 If @var{frame} is not visible, this function does nothing. The return | |
1454 value is not significant. | |
1455 @end defun | |
1456 | |
1457 @need 3000 | |
1458 | |
1459 @node Pop-Up Menus | |
1460 @section Pop-Up Menus | |
1461 | |
1462 When using a window system, a Lisp program can pop up a menu so that | |
1463 the user can choose an alternative with the mouse. | |
1464 | |
1465 @defun x-popup-menu position menu | |
1466 This function displays a pop-up menu and returns an indication of | |
1467 what selection the user makes. | |
1468 | |
1469 The argument @var{position} specifies where on the screen to put the | |
1470 top left corner of the menu. It can be either a mouse button event | |
1471 (which says to put the menu where the user actuated the button) or a | |
1472 list of this form: | |
1473 | |
1474 @example | |
1475 ((@var{xoffset} @var{yoffset}) @var{window}) | |
1476 @end example | |
1477 | |
1478 @noindent | |
1479 where @var{xoffset} and @var{yoffset} are coordinates, measured in | |
1480 pixels, counting from the top left corner of @var{window}. @var{window} | |
1481 may be a window or a frame. | |
1482 | |
1483 If @var{position} is @code{t}, it means to use the current mouse | |
1484 position. If @var{position} is @code{nil}, it means to precompute the | |
1485 key binding equivalents for the keymaps specified in @var{menu}, | |
1486 without actually displaying or popping up the menu. | |
1487 | |
1488 The argument @var{menu} says what to display in the menu. It can be a | |
1489 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the | |
1490 return value is the list of events corresponding to the user's choice. | |
1491 (This list has more than one element if the choice occurred in a | |
1492 submenu.) Note that @code{x-popup-menu} does not actually execute the | |
1493 command bound to that sequence of events. | |
1494 | |
1495 Alternatively, @var{menu} can have the following form: | |
1496 | |
1497 @example | |
1498 (@var{title} @var{pane1} @var{pane2}...) | |
1499 @end example | |
1500 | |
1501 @noindent | |
1502 where each pane is a list of form | |
1503 | |
1504 @example | |
1505 (@var{title} @var{item1} @var{item2}...) | |
1506 @end example | |
1507 | |
1508 Each item should normally be a cons cell @code{(@var{line} . @var{value})}, | |
1509 where @var{line} is a string, and @var{value} is the value to return if | |
1510 that @var{line} is chosen. An item can also be a string; this makes a | |
1511 non-selectable line in the menu. | |
1512 | |
1513 If the user gets rid of the menu without making a valid choice, for | |
1514 instance by clicking the mouse away from a valid choice or by typing | |
1515 keyboard input, then this normally results in a quit and | |
1516 @code{x-popup-menu} does not return. But if @var{position} is a mouse | |
1517 button event (indicating that the user invoked the menu with the | |
1518 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. | |
1519 @end defun | |
1520 | |
1521 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu | |
1522 if you could do the job with a prefix key defined with a menu keymap. | |
1523 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h | |
1524 a} can see the individual items in that menu and provide help for them. | |
1525 If instead you implement the menu by defining a command that calls | |
1526 @code{x-popup-menu}, the help facilities cannot know what happens inside | |
1527 that command, so they cannot give any help for the menu's items. | |
1528 | |
1529 The menu bar mechanism, which lets you switch between submenus by | |
1530 moving the mouse, cannot look within the definition of a command to see | |
1531 that it calls @code{x-popup-menu}. Therefore, if you try to implement a | |
1532 submenu using @code{x-popup-menu}, it cannot work with the menu bar in | |
1533 an integrated fashion. This is why all menu bar submenus are | |
1534 implemented with menu keymaps within the parent menu, and never with | |
1535 @code{x-popup-menu}. @xref{Menu Bar}. | |
1536 | |
1537 If you want a menu bar submenu to have contents that vary, you should | |
1538 still use a menu keymap to implement it. To make the contents vary, add | |
1539 a hook function to @code{menu-bar-update-hook} to update the contents of | |
1540 the menu keymap as necessary. | |
1541 | |
1542 @node Dialog Boxes | |
1543 @section Dialog Boxes | |
1544 @cindex dialog boxes | |
1545 | |
1546 A dialog box is a variant of a pop-up menu---it looks a little | |
1547 different, it always appears in the center of a frame, and it has just | |
1548 one level and one or more buttons. The main use of dialog boxes is | |
1549 for asking questions that the user can answer with ``yes,'' ``no,'' | |
1550 and a few other alternatives. With a single button, they can also | |
1551 force the user to acknowledge important information. The functions | |
1552 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the | |
1553 keyboard, when called from commands invoked by mouse clicks. | |
1554 | |
1555 @defun x-popup-dialog position contents &optional header | |
1556 This function displays a pop-up dialog box and returns an indication of | |
1557 what selection the user makes. The argument @var{contents} specifies | |
1558 the alternatives to offer; it has this format: | |
1559 | |
1560 @example | |
1561 (@var{title} (@var{string} . @var{value})@dots{}) | |
1562 @end example | |
1563 | |
1564 @noindent | |
1565 which looks like the list that specifies a single pane for | |
1566 @code{x-popup-menu}. | |
1567 | |
1568 The return value is @var{value} from the chosen alternative. | |
1569 | |
1570 As for @code{x-popup-menu}, an element of the list may be just a | |
1571 string instead of a cons cell @code{(@var{string} . @var{value})}. | |
1572 That makes a box that cannot be selected. | |
1573 | |
1574 If @code{nil} appears in the list, it separates the left-hand items from | |
1575 the right-hand items; items that precede the @code{nil} appear on the | |
1576 left, and items that follow the @code{nil} appear on the right. If you | |
1577 don't include a @code{nil} in the list, then approximately half the | |
1578 items appear on each side. | |
1579 | |
1580 Dialog boxes always appear in the center of a frame; the argument | |
1581 @var{position} specifies which frame. The possible values are as in | |
1582 @code{x-popup-menu}, but the precise coordinates or the individual | |
1583 window don't matter; only the frame matters. | |
1584 | |
1585 If @var{header} is non-@code{nil}, the frame title for the box is | |
1586 @samp{Information}, otherwise it is @samp{Question}. The former is used | |
1587 for @code{message-box} (@pxref{message-box}). | |
1588 | |
1589 In some configurations, Emacs cannot display a real dialog box; so | |
1590 instead it displays the same items in a pop-up menu in the center of the | |
1591 frame. | |
1592 | |
1593 If the user gets rid of the dialog box without making a valid choice, | |
1594 for instance using the window manager, then this produces a quit and | |
1595 @code{x-popup-dialog} does not return. | |
1596 @end defun | |
1597 | |
1598 @node Pointer Shape | |
1599 @section Pointer Shape | |
1600 @cindex pointer shape | |
1601 @cindex mouse pointer shape | |
1602 | |
1603 You can specify the mouse pointer style for particular text or | |
1604 images using the @code{pointer} text property, and for images with the | |
1605 @code{:pointer} and @code{:map} image properties. The values you can | |
1606 use in these properties are @code{text} (or @code{nil}), @code{arrow}, | |
1607 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and | |
1608 @code{hourglass}. @code{text} stands for the usual mouse pointer | |
1609 style used over text. | |
1610 | |
1611 Over void parts of the window (parts that do not correspond to any | |
1612 of the buffer contents), the mouse pointer usually uses the | |
1613 @code{arrow} style, but you can specify a different style (one of | |
1614 those above) by setting @code{void-text-area-pointer}. | |
1615 | |
1616 @defvar void-text-area-pointer | |
1617 This variable specifies the mouse pointer style for void text areas. | |
1618 These include the areas after the end of a line or below the last line | |
1619 in the buffer. The default is to use the @code{arrow} (non-text) | |
1620 pointer style. | |
1621 @end defvar | |
1622 | |
1623 You can specify what the @code{text} pointer style really looks like | |
1624 by setting the variable @code{x-pointer-shape}. | |
1625 | |
1626 @defvar x-pointer-shape | |
1627 This variable specifies the pointer shape to use ordinarily in the | |
1628 Emacs frame, for the @code{text} pointer style. | |
1629 @end defvar | |
1630 | |
1631 @defvar x-sensitive-text-pointer-shape | |
1632 This variable specifies the pointer shape to use when the mouse | |
1633 is over mouse-sensitive text. | |
1634 @end defvar | |
1635 | |
1636 These variables affect newly created frames. They do not normally | |
1637 affect existing frames; however, if you set the mouse color of a | |
1638 frame, that also installs the current value of those two variables. | |
1639 @xref{Color Parameters}. | |
1640 | |
1641 The values you can use, to specify either of these pointer shapes, are | |
1642 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos | |
1643 @key{RET} x-pointer @key{RET}} to see a list of them. | |
1644 | |
1645 @node Window System Selections | |
1646 @section Window System Selections | |
1647 @cindex selection (for window systems) | |
1648 | |
1649 The X server records a set of @dfn{selections} which permit transfer of | |
1650 data between application programs. The various selections are | |
1651 distinguished by @dfn{selection types}, represented in Emacs by | |
1652 symbols. X clients including Emacs can read or set the selection for | |
1653 any given type. | |
1654 | |
1655 @deffn Command x-set-selection type data | |
1656 This function sets a ``selection'' in the X server. It takes two | |
1657 arguments: a selection type @var{type}, and the value to assign to it, | |
1658 @var{data}. If @var{data} is @code{nil}, it means to clear out the | |
1659 selection. Otherwise, @var{data} may be a string, a symbol, an integer | |
1660 (or a cons of two integers or list of two integers), an overlay, or a | |
1661 cons of two markers pointing to the same buffer. An overlay or a pair | |
1662 of markers stands for text in the overlay or between the markers. | |
1663 | |
1664 The argument @var{data} may also be a vector of valid non-vector | |
1665 selection values. | |
1666 | |
1667 Each possible @var{type} has its own selection value, which changes | |
1668 independently. The usual values of @var{type} are @code{PRIMARY}, | |
1669 @code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case | |
1670 names, in accord with X Window System conventions. If @var{type} is | |
1671 @code{nil}, that stands for @code{PRIMARY}. | |
1672 | |
1673 This function returns @var{data}. | |
1674 @end deffn | |
1675 | |
1676 @defun x-get-selection &optional type data-type | |
1677 This function accesses selections set up by Emacs or by other X | |
1678 clients. It takes two optional arguments, @var{type} and | |
1679 @var{data-type}. The default for @var{type}, the selection type, is | |
1680 @code{PRIMARY}. | |
1681 | |
1682 The @var{data-type} argument specifies the form of data conversion to | |
1683 use, to convert the raw data obtained from another X client into Lisp | |
1684 data. Meaningful values include @code{TEXT}, @code{STRING}, | |
1685 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE}, | |
1686 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME}, | |
1687 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS}, | |
1688 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and | |
1689 @code{INTEGER}. (These are symbols with upper-case names in accord | |
1690 with X conventions.) The default for @var{data-type} is | |
1691 @code{STRING}. | |
1692 @end defun | |
1693 | |
1694 @cindex cut buffer | |
1695 The X server also has a set of eight numbered @dfn{cut buffers} which can | |
1696 store text or other data being moved between applications. Cut buffers | |
1697 are considered obsolete, but Emacs supports them for the sake of X | |
1698 clients that still use them. Cut buffers are numbered from 0 to 7. | |
1699 | |
1700 @defun x-get-cut-buffer &optional n | |
1701 This function returns the contents of cut buffer number @var{n}. | |
1702 If omitted @var{n} defaults to 0. | |
1703 @end defun | |
1704 | |
1705 @defun x-set-cut-buffer string &optional push | |
1706 @anchor{Definition of x-set-cut-buffer} | |
1707 This function stores @var{string} into the first cut buffer (cut buffer | |
1708 0). If @var{push} is @code{nil}, only the first cut buffer is changed. | |
1709 If @var{push} is non-@code{nil}, that says to move the values down | |
1710 through the series of cut buffers, much like the way successive kills in | |
1711 Emacs move down the kill ring. In other words, the previous value of | |
1712 the first cut buffer moves into the second cut buffer, and the second to | |
1713 the third, and so on through all eight cut buffers. | |
1714 @end defun | |
1715 | |
1716 @defvar selection-coding-system | |
1717 This variable specifies the coding system to use when reading and | |
1718 writing selections or the clipboard. @xref{Coding | |
1719 Systems}. The default is @code{compound-text-with-extensions}, which | |
1720 converts to the text representation that X11 normally uses. | |
1721 @end defvar | |
1722 | |
1723 @cindex clipboard support (for MS-Windows) | |
1724 When Emacs runs on MS-Windows, it does not implement X selections in | |
1725 general, but it does support the clipboard. @code{x-get-selection} | |
1726 and @code{x-set-selection} on MS-Windows support the text data type | |
1727 only; if the clipboard holds other types of data, Emacs treats the | |
1728 clipboard as empty. | |
1729 | |
1730 @defopt x-select-enable-clipboard | |
1731 If this is non-@code{nil}, the Emacs yank functions consult the | |
1732 clipboard before the primary selection, and the kill functions store in | |
1733 the clipboard as well as the primary selection. Otherwise they do not | |
1734 access the clipboard at all. The default is @code{nil} on most systems, | |
97043
9592c50233ab
Remove support for Mac Carbon.
Dan Nicolaescu <dann@ics.uci.edu>
parents:
92098
diff
changeset
|
1735 but @code{t} on MS-Windows. |
84068 | 1736 @end defopt |
1737 | |
1738 @node Drag and Drop | |
1739 @section Drag and Drop | |
1740 | |
1741 @vindex x-dnd-test-function | |
1742 @vindex x-dnd-known-types | |
1743 When a user drags something from another application over Emacs, that other | |
1744 application expects Emacs to tell it if Emacs can handle the data that is | |
1745 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine | |
1746 what to reply. The default value is @code{x-dnd-default-test-function} | |
1747 which accepts drops if the type of the data to be dropped is present in | |
1748 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or | |
1749 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based | |
1750 on some other criteria. | |
1751 | |
1752 @vindex x-dnd-types-alist | |
1753 If you want to change the way Emacs handles drop of different types | |
1754 or add a new type, customize @code{x-dnd-types-alist}. This requires | |
1755 detailed knowledge of what types other applications use for drag and | |
1756 drop. | |
1757 | |
1758 @vindex dnd-protocol-alist | |
1759 When an URL is dropped on Emacs it may be a file, but it may also be | |
1760 another URL type (ftp, http, etc.). Emacs first checks | |
1761 @code{dnd-protocol-alist} to determine what to do with the URL. If | |
1762 there is no match there and if @code{browse-url-browser-function} is | |
1763 an alist, Emacs looks for a match there. If no match is found the | |
1764 text for the URL is inserted. If you want to alter Emacs behavior, | |
1765 you can customize these variables. | |
1766 | |
1767 @node Color Names | |
1768 @section Color Names | |
1769 | |
1770 @cindex color names | |
1771 @cindex specify color | |
1772 @cindex numerical RGB color specification | |
1773 A color name is text (usually in a string) that specifies a color. | |
1774 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc., | |
1775 are allowed; use @kbd{M-x list-colors-display} to see a list of | |
1776 defined names. You can also specify colors numerically in forms such | |
1777 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where | |
1778 @var{r} specifies the red level, @var{g} specifies the green level, | |
1779 and @var{b} specifies the blue level. You can use either one, two, | |
1780 three, or four hex digits for @var{r}; then you must use the same | |
1781 number of hex digits for all @var{g} and @var{b} as well, making | |
1782 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the | |
1783 X Window System for more details about numerical RGB specification of | |
1784 colors.) | |
1785 | |
1786 These functions provide a way to determine which color names are | |
1787 valid, and what they look like. In some cases, the value depends on the | |
1788 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the | |
1789 meaning of the term ``selected frame.'' | |
1790 | |
1791 @defun color-defined-p color &optional frame | |
1792 This function reports whether a color name is meaningful. It returns | |
1793 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says | |
1794 which frame's display to ask about; if @var{frame} is omitted or | |
1795 @code{nil}, the selected frame is used. | |
1796 | |
1797 Note that this does not tell you whether the display you are using | |
1798 really supports that color. When using X, you can ask for any defined | |
1799 color on any kind of display, and you will get some result---typically, | |
1800 the closest it can do. To determine whether a frame can really display | |
1801 a certain color, use @code{color-supported-p} (see below). | |
1802 | |
1803 @findex x-color-defined-p | |
1804 This function used to be called @code{x-color-defined-p}, | |
1805 and that name is still supported as an alias. | |
1806 @end defun | |
1807 | |
1808 @defun defined-colors &optional frame | |
1809 This function returns a list of the color names that are defined | |
1810 and supported on frame @var{frame} (default, the selected frame). | |
1811 If @var{frame} does not support colors, the value is @code{nil}. | |
1812 | |
1813 @findex x-defined-colors | |
1814 This function used to be called @code{x-defined-colors}, | |
1815 and that name is still supported as an alias. | |
1816 @end defun | |
1817 | |
1818 @defun color-supported-p color &optional frame background-p | |
1819 This returns @code{t} if @var{frame} can really display the color | |
1820 @var{color} (or at least something close to it). If @var{frame} is | |
1821 omitted or @code{nil}, the question applies to the selected frame. | |
1822 | |
1823 Some terminals support a different set of colors for foreground and | |
1824 background. If @var{background-p} is non-@code{nil}, that means you are | |
1825 asking whether @var{color} can be used as a background; otherwise you | |
1826 are asking whether it can be used as a foreground. | |
1827 | |
1828 The argument @var{color} must be a valid color name. | |
1829 @end defun | |
1830 | |
1831 @defun color-gray-p color &optional frame | |
1832 This returns @code{t} if @var{color} is a shade of gray, as defined on | |
1833 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the | |
1834 question applies to the selected frame. If @var{color} is not a valid | |
1835 color name, this function returns @code{nil}. | |
1836 @end defun | |
1837 | |
1838 @defun color-values color &optional frame | |
1839 @cindex rgb value | |
1840 This function returns a value that describes what @var{color} should | |
1841 ideally look like on @var{frame}. If @var{color} is defined, the | |
1842 value is a list of three integers, which give the amount of red, the | |
1843 amount of green, and the amount of blue. Each integer ranges in | |
1844 principle from 0 to 65535, but some displays may not use the full | |
1845 range. This three-element list is called the @dfn{rgb values} of the | |
1846 color. | |
1847 | |
1848 If @var{color} is not defined, the value is @code{nil}. | |
1849 | |
1850 @example | |
1851 (color-values "black") | |
1852 @result{} (0 0 0) | |
1853 (color-values "white") | |
1854 @result{} (65280 65280 65280) | |
1855 (color-values "red") | |
1856 @result{} (65280 0 0) | |
1857 (color-values "pink") | |
1858 @result{} (65280 49152 51968) | |
1859 (color-values "hungry") | |
1860 @result{} nil | |
1861 @end example | |
1862 | |
1863 The color values are returned for @var{frame}'s display. If | |
1864 @var{frame} is omitted or @code{nil}, the information is returned for | |
1865 the selected frame's display. If the frame cannot display colors, the | |
1866 value is @code{nil}. | |
1867 | |
1868 @findex x-color-values | |
1869 This function used to be called @code{x-color-values}, | |
1870 and that name is still supported as an alias. | |
1871 @end defun | |
1872 | |
1873 @node Text Terminal Colors | |
1874 @section Text Terminal Colors | |
1875 @cindex colors on text-only terminals | |
1876 | |
1877 Text-only terminals usually support only a small number of colors, | |
1878 and the computer uses small integers to select colors on the terminal. | |
1879 This means that the computer cannot reliably tell what the selected | |
1880 color looks like; instead, you have to inform your application which | |
1881 small integers correspond to which colors. However, Emacs does know | |
1882 the standard set of colors and will try to use them automatically. | |
1883 | |
1884 The functions described in this section control how terminal colors | |
1885 are used by Emacs. | |
1886 | |
1887 Several of these functions use or return @dfn{rgb values}, described | |
1888 in @ref{Color Names}. | |
1889 | |
1890 These functions accept a display (either a frame or the name of a | |
1891 terminal) as an optional argument. We hope in the future to make Emacs | |
1892 support more than one text-only terminal at one time; then this argument | |
1893 will specify which terminal to operate on (the default being the | |
1894 selected frame's terminal; @pxref{Input Focus}). At present, though, | |
1895 the @var{frame} argument has no effect. | |
1896 | |
1897 @defun tty-color-define name number &optional rgb frame | |
1898 This function associates the color name @var{name} with | |
1899 color number @var{number} on the terminal. | |
1900 | |
1901 The optional argument @var{rgb}, if specified, is an rgb value, a list | |
1902 of three numbers that specify what the color actually looks like. | |
1903 If you do not specify @var{rgb}, then this color cannot be used by | |
1904 @code{tty-color-approximate} to approximate other colors, because | |
1905 Emacs will not know what it looks like. | |
1906 @end defun | |
1907 | |
1908 @defun tty-color-clear &optional frame | |
1909 This function clears the table of defined colors for a text-only terminal. | |
1910 @end defun | |
1911 | |
1912 @defun tty-color-alist &optional frame | |
1913 This function returns an alist recording the known colors supported by a | |
1914 text-only terminal. | |
1915 | |
1916 Each element has the form @code{(@var{name} @var{number} . @var{rgb})} | |
1917 or @code{(@var{name} @var{number})}. Here, @var{name} is the color | |
1918 name, @var{number} is the number used to specify it to the terminal. | |
1919 If present, @var{rgb} is a list of three color values (for red, green, | |
1920 and blue) that says what the color actually looks like. | |
1921 @end defun | |
1922 | |
1923 @defun tty-color-approximate rgb &optional frame | |
1924 This function finds the closest color, among the known colors | |
1925 supported for @var{display}, to that described by the rgb value | |
1926 @var{rgb} (a list of color values). The return value is an element of | |
1927 @code{tty-color-alist}. | |
1928 @end defun | |
1929 | |
1930 @defun tty-color-translate color &optional frame | |
1931 This function finds the closest color to @var{color} among the known | |
1932 colors supported for @var{display} and returns its index (an integer). | |
1933 If the name @var{color} is not defined, the value is @code{nil}. | |
1934 @end defun | |
1935 | |
1936 @node Resources | |
1937 @section X Resources | |
1938 | |
1939 @defun x-get-resource attribute class &optional component subclass | |
1940 The function @code{x-get-resource} retrieves a resource value from the X | |
1941 Window defaults database. | |
1942 | |
1943 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. | |
1944 This function searches using a key of the form | |
1945 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name | |
1946 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as | |
1947 the class. | |
1948 | |
1949 The optional arguments @var{component} and @var{subclass} add to the key | |
1950 and the class, respectively. You must specify both of them or neither. | |
1951 If you specify them, the key is | |
1952 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is | |
1953 @samp{Emacs.@var{class}.@var{subclass}}. | |
1954 @end defun | |
1955 | |
1956 @defvar x-resource-class | |
1957 This variable specifies the application name that @code{x-get-resource} | |
1958 should look up. The default value is @code{"Emacs"}. You can examine X | |
1959 resources for application names other than ``Emacs'' by binding this | |
1960 variable to some other string, around a call to @code{x-get-resource}. | |
1961 @end defvar | |
1962 | |
1963 @defvar x-resource-name | |
1964 This variable specifies the instance name that @code{x-get-resource} | |
1965 should look up. The default value is the name Emacs was invoked with, | |
1966 or the value specified with the @samp{-name} or @samp{-rn} switches. | |
1967 @end defvar | |
1968 | |
1969 To illustrate some of the above, suppose that you have the line: | |
1970 | |
1971 @example | |
1972 xterm.vt100.background: yellow | |
1973 @end example | |
1974 | |
1975 @noindent | |
1976 in your X resources file (whose name is usually @file{~/.Xdefaults} | |
1977 or @file{~/.Xresources}). Then: | |
1978 | |
1979 @example | |
1980 @group | |
1981 (let ((x-resource-class "XTerm") (x-resource-name "xterm")) | |
1982 (x-get-resource "vt100.background" "VT100.Background")) | |
1983 @result{} "yellow" | |
1984 @end group | |
1985 @group | |
1986 (let ((x-resource-class "XTerm") (x-resource-name "xterm")) | |
1987 (x-get-resource "background" "VT100" "vt100" "Background")) | |
1988 @result{} "yellow" | |
1989 @end group | |
1990 @end example | |
1991 | |
1992 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. | |
1993 | |
1994 @node Display Feature Testing | |
1995 @section Display Feature Testing | |
1996 @cindex display feature testing | |
1997 | |
1998 The functions in this section describe the basic capabilities of a | |
1999 particular display. Lisp programs can use them to adapt their behavior | |
2000 to what the display can do. For example, a program that ordinarily uses | |
2001 a popup menu could use the minibuffer if popup menus are not supported. | |
2002 | |
2003 The optional argument @var{display} in these functions specifies which | |
2004 display to ask the question about. It can be a display name, a frame | |
2005 (which designates the display that frame is on), or @code{nil} (which | |
2006 refers to the selected frame's display, @pxref{Input Focus}). | |
2007 | |
2008 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to | |
2009 obtain information about displays. | |
2010 | |
2011 @defun display-popup-menus-p &optional display | |
2012 This function returns @code{t} if popup menus are supported on | |
2013 @var{display}, @code{nil} if not. Support for popup menus requires that | |
2014 the mouse be available, since the user cannot choose menu items without | |
2015 a mouse. | |
2016 @end defun | |
2017 | |
2018 @defun display-graphic-p &optional display | |
2019 This function returns @code{t} if @var{display} is a graphic display | |
2020 capable of displaying several frames and several different fonts at | |
2021 once. This is true for displays that use a window system such as X, and | |
2022 false for text-only terminals. | |
2023 @end defun | |
2024 | |
2025 @defun display-mouse-p &optional display | |
2026 @cindex mouse, availability | |
2027 This function returns @code{t} if @var{display} has a mouse available, | |
2028 @code{nil} if not. | |
2029 @end defun | |
2030 | |
2031 @defun display-color-p &optional display | |
2032 @findex x-display-color-p | |
2033 This function returns @code{t} if the screen is a color screen. | |
2034 It used to be called @code{x-display-color-p}, and that name | |
2035 is still supported as an alias. | |
2036 @end defun | |
2037 | |
2038 @defun display-grayscale-p &optional display | |
2039 This function returns @code{t} if the screen can display shades of gray. | |
2040 (All color displays can do this.) | |
2041 @end defun | |
2042 | |
2043 @defun display-supports-face-attributes-p attributes &optional display | |
2044 @anchor{Display Face Attribute Testing} | |
2045 This function returns non-@code{nil} if all the face attributes in | |
2046 @var{attributes} are supported (@pxref{Face Attributes}). | |
2047 | |
2048 The definition of `supported' is somewhat heuristic, but basically | |
2049 means that a face containing all the attributes in @var{attributes}, | |
2050 when merged with the default face for display, can be represented in a | |
2051 way that's | |
2052 | |
2053 @enumerate | |
2054 @item | |
2055 different in appearance than the default face, and | |
2056 | |
2057 @item | |
2058 `close in spirit' to what the attributes specify, if not exact. | |
2059 @end enumerate | |
2060 | |
2061 Point (2) implies that a @code{:weight black} attribute will be | |
2062 satisfied by any display that can display bold, as will | |
2063 @code{:foreground "yellow"} as long as some yellowish color can be | |
2064 displayed, but @code{:slant italic} will @emph{not} be satisfied by | |
2065 the tty display code's automatic substitution of a `dim' face for | |
2066 italic. | |
2067 @end defun | |
2068 | |
2069 @defun display-selections-p &optional display | |
2070 This function returns @code{t} if @var{display} supports selections. | |
2071 Windowed displays normally support selections, but they may also be | |
2072 supported in some other cases. | |
2073 @end defun | |
2074 | |
2075 @defun display-images-p &optional display | |
2076 This function returns @code{t} if @var{display} can display images. | |
2077 Windowed displays ought in principle to handle images, but some | |
2078 systems lack the support for that. On a display that does not support | |
2079 images, Emacs cannot display a tool bar. | |
2080 @end defun | |
2081 | |
2082 @defun display-screens &optional display | |
2083 This function returns the number of screens associated with the display. | |
2084 @end defun | |
2085 | |
2086 @defun display-pixel-height &optional display | |
2087 This function returns the height of the screen in pixels. | |
2088 On a character terminal, it gives the height in characters. | |
2089 | |
2090 For graphical terminals, note that on ``multi-monitor'' setups this | |
2091 refers to the pixel width for all physical monitors associated with | |
2092 @var{display}. @xref{Multiple Displays}. | |
2093 @end defun | |
2094 | |
2095 @defun display-pixel-width &optional display | |
2096 This function returns the width of the screen in pixels. | |
2097 On a character terminal, it gives the width in characters. | |
2098 | |
2099 For graphical terminals, note that on ``multi-monitor'' setups this | |
2100 refers to the pixel width for all physical monitors associated with | |
2101 @var{display}. @xref{Multiple Displays}. | |
2102 @end defun | |
2103 | |
2104 @defun display-mm-height &optional display | |
2105 This function returns the height of the screen in millimeters, | |
2106 or @code{nil} if Emacs cannot get that information. | |
2107 @end defun | |
2108 | |
2109 @defun display-mm-width &optional display | |
2110 This function returns the width of the screen in millimeters, | |
2111 or @code{nil} if Emacs cannot get that information. | |
2112 @end defun | |
2113 | |
2114 @defvar display-mm-dimensions-alist | |
2115 This variable allows the user to specify the dimensions of graphical | |
2116 displays returned by @code{display-mm-height} and | |
2117 @code{display-mm-width} in case the system provides incorrect values. | |
2118 @end defvar | |
2119 | |
2120 @defun display-backing-store &optional display | |
2121 This function returns the backing store capability of the display. | |
2122 Backing store means recording the pixels of windows (and parts of | |
2123 windows) that are not exposed, so that when exposed they can be | |
2124 displayed very quickly. | |
2125 | |
2126 Values can be the symbols @code{always}, @code{when-mapped}, or | |
2127 @code{not-useful}. The function can also return @code{nil} | |
2128 when the question is inapplicable to a certain kind of display. | |
2129 @end defun | |
2130 | |
2131 @defun display-save-under &optional display | |
2132 This function returns non-@code{nil} if the display supports the | |
2133 SaveUnder feature. That feature is used by pop-up windows | |
2134 to save the pixels they obscure, so that they can pop down | |
2135 quickly. | |
2136 @end defun | |
2137 | |
2138 @defun display-planes &optional display | |
2139 This function returns the number of planes the display supports. | |
2140 This is typically the number of bits per pixel. | |
2141 For a tty display, it is log to base two of the number of colors supported. | |
2142 @end defun | |
2143 | |
2144 @defun display-visual-class &optional display | |
2145 This function returns the visual class for the screen. The value is one | |
2146 of the symbols @code{static-gray}, @code{gray-scale}, | |
2147 @code{static-color}, @code{pseudo-color}, @code{true-color}, and | |
2148 @code{direct-color}. | |
2149 @end defun | |
2150 | |
2151 @defun display-color-cells &optional display | |
2152 This function returns the number of color cells the screen supports. | |
2153 @end defun | |
2154 | |
2155 These functions obtain additional information specifically | |
2156 about X displays. | |
2157 | |
2158 @defun x-server-version &optional display | |
2159 This function returns the list of version numbers of the X server | |
2160 running the display. The value is a list of three integers: the major | |
2161 and minor version numbers of the X protocol, and the | |
2162 distributor-specific release number of the X server software itself. | |
2163 @end defun | |
2164 | |
2165 @defun x-server-vendor &optional display | |
2166 This function returns the ``vendor'' that provided the X server | |
2167 software (as a string). Really this means whoever distributes the X | |
2168 server. | |
2169 | |
2170 When the developers of X labelled software distributors as | |
2171 ``vendors,'' they showed their false assumption that no system could | |
2172 ever be developed and distributed noncommercially. | |
2173 @end defun | |
2174 | |
2175 @ignore | |
2176 @defvar x-no-window-manager | |
2177 This variable's value is @code{t} if no X window manager is in use. | |
2178 @end defvar | |
2179 @end ignore | |
2180 | |
2181 @ignore | |
2182 @item | |
2183 The functions @code{x-pixel-width} and @code{x-pixel-height} return the | |
2184 width and height of an X Window frame, measured in pixels. | |
2185 @end ignore | |
2186 | |
2187 @ignore | |
2188 arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba | |
2189 @end ignore |