|
0
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
|
4 @c Copyright (C) 1995, 1996 Ben Wing.
|
|
|
5 @c See the file lispref.texi for copying conditions.
|
|
|
6 @setfilename ../../info/frames.info
|
|
|
7 @node Frames, Consoles and Devices, Windows, Top
|
|
|
8 @chapter Frames
|
|
|
9 @cindex frame
|
|
|
10
|
|
|
11 A @var{frame} is a rectangle on the screen that contains one or more
|
|
|
12 Emacs windows. A frame initially contains a single main window (plus
|
|
|
13 perhaps a minibuffer window), which you can subdivide vertically or
|
|
|
14 horizontally into smaller windows.
|
|
|
15
|
|
|
16 @cindex terminal frame
|
|
|
17 @cindex X window frame
|
|
|
18 When XEmacs runs on a text-only terminal, it starts with one
|
|
|
19 @dfn{TTY frame}. If you create additional ones, XEmacs displays
|
|
|
20 one and only one at any given time---on the terminal screen, of course.
|
|
|
21
|
|
|
22 When XEmacs communicates directly with an X server, it does not have a
|
|
|
23 TTY frame; instead, it starts with a single @dfn{X window frame}.
|
|
|
24 It can display multiple X window frames at the same time, each in its
|
|
|
25 own X window.
|
|
|
26
|
|
|
27 @defun framep object
|
|
|
28 This predicate returns @code{t} if @var{object} is a frame, and
|
|
|
29 @code{nil} otherwise.
|
|
|
30 @end defun
|
|
|
31
|
|
|
32 @menu
|
|
|
33 * Creating Frames:: Creating additional frames.
|
|
|
34 * Frame Parameters:: Controlling frame size, position, font, etc.
|
|
|
35 * Frame Titles:: Automatic updating of frame titles.
|
|
|
36 * Deleting Frames:: Frames last until explicitly deleted.
|
|
|
37 * Finding All Frames:: How to examine all existing frames.
|
|
|
38 * Frames and Windows:: A frame contains windows;
|
|
|
39 display of text always works through windows.
|
|
|
40 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
|
|
|
41 * Input Focus:: Specifying the selected frame.
|
|
|
42 * Visibility of Frames:: Frames may be visible or invisible, or icons.
|
|
|
43 * Raising and Lowering:: Raising a frame makes it hide other X windows;
|
|
|
44 lowering it makes the others hide them.
|
|
|
45 * Frame Configurations:: Saving the state of all frames.
|
|
|
46 * Frame Hooks:: Hooks for customizing frame behavior.
|
|
|
47 @end menu
|
|
|
48
|
|
|
49 @xref{Display}, for related information.
|
|
|
50
|
|
|
51 @node Creating Frames
|
|
|
52 @section Creating Frames
|
|
|
53
|
|
|
54 To create a new frame, call the function @code{make-frame}.
|
|
|
55
|
|
|
56 @defun make-frame &optional alist device
|
|
|
57 This function creates a new frame on @var{device}, if @var{device}
|
|
|
58 permits creation of frames. (An X server does; an ordinary terminal
|
|
|
59 does not.) @var{device} defaults to the selected device if omitted.
|
|
|
60 @xref{Consoles and Devices}.
|
|
|
61
|
|
|
62 The argument is an alist specifying frame parameters. Any parameters
|
|
|
63 not mentioned in @var{alist} default according to the value of the
|
|
|
64 variable @code{default-frame-alist}. For X devices, parameters not
|
|
|
65 specified in @code{default-frame-alist} default in turn from
|
|
|
66 @code{default-x-frame-alist} and, if not specified there, from the X
|
|
|
67 resources. For TTY devices, @code{default-tty-frame-alist} is
|
|
|
68 consulted as well as @code{default-frame-alist}.
|
|
|
69
|
|
|
70 The set of possible parameters depends in principle on what kind of
|
|
|
71 window system XEmacs uses to display its frames. @xref{X Frame
|
|
|
72 Parameters}, for documentation of individual parameters you can specify
|
|
|
73 when creating an X window frame.
|
|
|
74 @end defun
|
|
|
75
|
|
|
76 @node Frame Parameters
|
|
|
77 @section Frame Parameters
|
|
|
78
|
|
|
79 A frame has many parameters that control its appearance and behavior.
|
|
|
80 Just what parameters a frame has depends on what display mechanism it
|
|
|
81 uses.
|
|
|
82
|
|
|
83 Frame parameters exist for the sake of window systems. A terminal frame
|
|
|
84 has a few parameters, mostly for compatibility's sake; only the height,
|
|
|
85 width and @code{buffer-predicate} parameters really do something.
|
|
|
86
|
|
|
87 @menu
|
|
|
88 * Parameter Access:: How to change a frame's parameters.
|
|
|
89 * Initial Parameters:: Specifying frame parameters when you make a frame.
|
|
|
90 * X Frame Parameters:: List of frame parameters.
|
|
|
91 * Size and Position:: Changing the size and position of a frame.
|
|
|
92 * Frame Name:: The name of a frame (as opposed to its title).
|
|
|
93 @end menu
|
|
|
94
|
|
|
95 @node Parameter Access
|
|
|
96 @subsection Access to Frame Parameters
|
|
|
97
|
|
|
98 These functions let you read and change the parameter values of a
|
|
|
99 frame.
|
|
|
100
|
|
|
101 @defun frame-parameters frame
|
|
|
102 The function @code{frame-parameters} returns an alist listing all the
|
|
|
103 parameters of @var{frame} and their values.
|
|
|
104 @end defun
|
|
|
105
|
|
|
106 @defun modify-frame-parameters frame alist
|
|
|
107 This function alters the parameters of frame @var{frame} based on the
|
|
|
108 elements of @var{alist}. Each element of @var{alist} has the form
|
|
|
109 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
|
|
|
110 parameter. If you don't mention a parameter in @var{alist}, its value
|
|
|
111 doesn't change.
|
|
|
112 @end defun
|
|
|
113
|
|
|
114 @node Initial Parameters
|
|
|
115 @subsection Initial Frame Parameters
|
|
|
116
|
|
|
117 You can specify the parameters for the initial startup frame
|
|
|
118 by setting @code{initial-frame-alist} in your @file{.emacs} file.
|
|
|
119
|
|
|
120 @defvar initial-frame-alist
|
|
|
121 This variable's value is an alist of parameter values used when creating
|
|
|
122 the initial X window frame. Each element has the form:
|
|
|
123
|
|
|
124 @example
|
|
|
125 (@var{parameter} . @var{value})
|
|
|
126 @end example
|
|
|
127
|
|
|
128 Emacs creates the initial frame before it reads your @file{~/.emacs}
|
|
|
129 file. After reading that file, Emacs checks @code{initial-frame-alist},
|
|
|
130 and applies the parameter settings in the altered value to the already
|
|
|
131 created initial frame.
|
|
|
132
|
|
|
133 If these settings affect the frame geometry and appearance, you'll see
|
|
|
134 the frame appear with the wrong ones and then change to the specified
|
|
|
135 ones. If that bothers you, you can specify the same geometry and
|
|
|
136 appearance with X resources; those do take affect before the frame is
|
|
|
137 created. @xref{Resources X,, X Resources, emacs, The XEmacs User's Manual}.
|
|
|
138
|
|
|
139 X resource settings typically apply to all frames. If you want to
|
|
|
140 specify some X resources solely for the sake of the initial frame, and
|
|
|
141 you don't want them to apply to subsequent frames, here's how to achieve
|
|
|
142 this. Specify parameters in @code{default-frame-alist} to override the
|
|
|
143 X resources for subsequent frames; then, to prevent these from affecting
|
|
|
144 the initial frame, specify the same parameters in
|
|
|
145 @code{initial-frame-alist} with values that match the X resources.
|
|
|
146 @end defvar
|
|
|
147
|
|
|
148 If these parameters specify a separate minibuffer-only frame with
|
|
|
149 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
|
|
|
150 one for you.
|
|
|
151
|
|
|
152 @defvar minibuffer-frame-alist
|
|
|
153 This variable's value is an alist of parameter values used when creating
|
|
|
154 an initial minibuffer-only frame---if such a frame is needed, according
|
|
|
155 to the parameters for the main initial frame.
|
|
|
156 @end defvar
|
|
|
157
|
|
|
158 @defvar default-frame-alist
|
|
|
159 This is an alist specifying default values of frame parameters for
|
|
|
160 subsequent Emacs frames (not the initial ones).
|
|
|
161 @end defvar
|
|
|
162
|
|
|
163 See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
|
|
|
164
|
|
|
165 If you use options that specify window appearance when you invoke Emacs,
|
|
|
166 they take effect by adding elements to @code{default-frame-alist}. One
|
|
|
167 exception is @samp{-geometry}, which adds the specified position to
|
|
|
168 @code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
|
|
|
169 The XEmacs User's Manual}.
|
|
|
170
|
|
|
171 @node X Frame Parameters
|
|
|
172 @subsection X Window Frame Parameters
|
|
|
173
|
|
|
174 Just what parameters a frame has depends on what display mechanism it
|
|
|
175 uses. Here is a table of the parameters of an X window frame; of these,
|
|
|
176 @code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
|
|
|
177 provide meaningful information in non-X frames.
|
|
|
178
|
|
|
179 @table @code
|
|
|
180 @item name
|
|
|
181 The name of the frame. Most window managers display the frame's name in
|
|
|
182 the frame's border, at the top of the frame. If you don't specify a
|
|
|
183 name, and you have more than one frame, Emacs sets the frame name based
|
|
|
184 on the buffer displayed in the frame's selected window.
|
|
|
185
|
|
|
186 If you specify the frame name explicitly when you create the frame, the
|
|
|
187 name is also used (instead of the name of the Emacs executable) when
|
|
|
188 looking up X resources for the frame.
|
|
|
189
|
|
|
190 @item display
|
|
|
191 The display on which to open this frame. It should be a string of the
|
|
|
192 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
|
|
|
193 @code{DISPLAY} environment variable.
|
|
|
194
|
|
|
195 @item left
|
|
|
196 The screen position of the left edge, in pixels, with respect to the
|
|
|
197 left edge of the screen. The value may be a positive number @var{pos},
|
|
|
198 or a list of the form @code{(+ @var{pos})} which permits specifying a
|
|
|
199 negative @var{pos} value.
|
|
|
200
|
|
|
201 A negative number @minus{}@var{pos}, or a list of the form @code{(-
|
|
|
202 @var{pos})}, actually specifies the position of the right edge of the
|
|
|
203 window with respect to the right edge of the screen. A positive value
|
|
|
204 of @var{pos} counts toward the left. If the parameter is a negative
|
|
|
205 integer @minus{}@var{pos} then @var{pos} is positive!
|
|
|
206
|
|
|
207 @item top
|
|
|
208 The screen position of the top edge, in pixels, with respect to the
|
|
|
209 top edge of the screen. The value may be a positive number @var{pos},
|
|
|
210 or a list of the form @code{(+ @var{pos})} which permits specifying a
|
|
|
211 negative @var{pos} value.
|
|
|
212
|
|
|
213 A negative number @minus{}@var{pos}, or a list of the form @code{(-
|
|
|
214 @var{pos})}, actually specifies the position of the bottom edge of the
|
|
|
215 window with respect to the bottom edge of the screen. A positive value
|
|
|
216 of @var{pos} counts toward the top. If the parameter is a negative
|
|
|
217 integer @minus{}@var{pos} then @var{pos} is positive!
|
|
|
218
|
|
|
219 @item icon-left
|
|
|
220 The screen position of the left edge @emph{of the frame's icon}, in
|
|
|
221 pixels, counting from the left edge of the screen. This takes effect if
|
|
|
222 and when the frame is iconified.
|
|
|
223
|
|
|
224 @item icon-top
|
|
|
225 The screen position of the top edge @emph{of the frame's icon}, in
|
|
|
226 pixels, counting from the top edge of the screen. This takes effect if
|
|
|
227 and when the frame is iconified.
|
|
|
228
|
|
|
229 @item user-position
|
|
|
230 Non-@code{nil} if the screen position of the frame was explicitly
|
|
|
231 requested by the user (for example, with the @samp{-geometry} option).
|
|
|
232 Nothing automatically makes this parameter non-@code{nil}; it is up to
|
|
|
233 Lisp programs that call @code{make-frame} to specify this parameter as
|
|
|
234 well as specifying the @code{left} and @code{top} parameters.
|
|
|
235
|
|
|
236 @item height
|
|
|
237 The height of the frame contents, in characters. (To get the height in
|
|
|
238 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
|
|
|
239
|
|
|
240 @item width
|
|
|
241 The width of the frame contents, in characters. (To get the height in
|
|
|
242 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
|
|
|
243
|
|
|
244 @item window-id
|
|
|
245 The number of the X window for the frame.
|
|
|
246
|
|
|
247 @item minibuffer
|
|
|
248 Whether this frame has its own minibuffer. The value @code{t} means
|
|
|
249 yes, @code{nil} means no, @code{only} means this frame is just a
|
|
|
250 minibuffer. If the value is a minibuffer window (in some other frame),
|
|
|
251 the new frame uses that minibuffer. (Minibuffer-only and minibuffer-less
|
|
|
252 frames are not yet implemented in XEmacs.)
|
|
|
253
|
|
|
254 @item buffer-predicate
|
|
|
255 The buffer-predicate function for this frame. The function
|
|
|
256 @code{other-buffer} uses this predicate (from the selected frame) to
|
|
|
257 decide which buffers it should consider, if the predicate is not
|
|
|
258 @code{nil}. It calls the predicate with one arg, a buffer, once for
|
|
|
259 each buffer; if the predicate returns a non-@code{nil} value, it
|
|
|
260 considers that buffer.
|
|
|
261
|
|
|
262 @item scroll-bar-width
|
|
|
263 The width of the vertical scroll bar, in pixels.
|
|
|
264
|
|
|
265 @ignore Not in XEmacs
|
|
|
266 @item icon-type
|
|
|
267 The type of icon to use for this frame when it is iconified. If the
|
|
|
268 value is a string, that specifies a file containing a bitmap to use.
|
|
|
269 Any other non-@code{nil} value specifies the default bitmap icon (a
|
|
|
270 picture of a gnu); @code{nil} specifies a text icon.
|
|
|
271
|
|
|
272 @item icon-name
|
|
|
273 The name to use in the icon for this frame, when and if the icon
|
|
|
274 appears. If this is @code{nil}, the frame's title is used.
|
|
|
275 @end ignore
|
|
|
276
|
|
|
277 @item cursor-color
|
|
|
278 The color for the cursor that shows point.
|
|
|
279
|
|
|
280 @item border-color
|
|
|
281 The color for the border of the frame.
|
|
|
282
|
|
|
283 @ignore Not in XEmacs
|
|
|
284 @item cursor-type
|
|
|
285 The way to display the cursor. The legitimate values are @code{bar},
|
|
|
286 @code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
|
|
|
287 specifies an ordinary black box overlaying the character after point;
|
|
|
288 that is the default. The symbol @code{bar} specifies a vertical bar
|
|
|
289 between characters as the cursor. @code{(bar . @var{width})} specifies
|
|
|
290 a bar @var{width} pixels wide.
|
|
|
291 @end ignore
|
|
|
292
|
|
|
293 @item border-width
|
|
|
294 The width in pixels of the window border.
|
|
|
295
|
|
|
296 @item internal-border-width
|
|
|
297 The distance in pixels between text and border.
|
|
|
298
|
|
|
299 @item unsplittable
|
|
|
300 If non-@code{nil}, this frame's window is never split automatically.
|
|
|
301
|
|
|
302 @item inter-line-space
|
|
|
303 The space in pixels between adjacent lines of text. (Not currently
|
|
|
304 implemented.)
|
|
|
305
|
|
|
306 @item modeline
|
|
|
307 Whether the frame has a modeline.
|
|
|
308 @end table
|
|
|
309
|
|
|
310 @node Size and Position
|
|
|
311 @subsection Frame Size And Position
|
|
|
312 @cindex size of frame
|
|
|
313 @cindex frame size
|
|
|
314 @cindex display lines
|
|
|
315 @cindex display columns
|
|
|
316 @cindex resize redisplay
|
|
|
317 @cindex frame position
|
|
|
318 @cindex position of frame
|
|
|
319
|
|
|
320 You can read or change the size and position of a frame using the
|
|
|
321 frame parameters @code{left}, @code{top}, @code{height}, and
|
|
|
322 @code{width}. Whatever geometry parameters you don't specify are chosen
|
|
|
323 by the window manager in its usual fashion.
|
|
|
324
|
|
|
325 Here are some special features for working with sizes and positions:
|
|
|
326
|
|
|
327 @defun set-frame-position frame left top
|
|
|
328 This function sets the position of the top left corner of @var{frame} to
|
|
|
329 @var{left} and @var{top}. These arguments are measured in pixels, and
|
|
|
330 count from the top left corner of the screen. Negative parameter values
|
|
|
331 count up or rightward from the top left corner of the screen.
|
|
|
332 @end defun
|
|
|
333
|
|
|
334 @defun frame-height &optional frame
|
|
|
335 @defunx frame-width &optional frame
|
|
|
336 These functions return the height and width of @var{frame}, measured in
|
|
|
337 lines and columns. If you don't supply @var{frame}, they use the selected
|
|
|
338 frame.
|
|
|
339 @end defun
|
|
|
340
|
|
|
341 @defun frame-pixel-height &optional frame
|
|
|
342 @defunx frame-pixel-width &optional frame
|
|
|
343 These functions return the height and width of @var{frame}, measured in
|
|
|
344 pixels. If you don't supply @var{frame}, they use the selected frame.
|
|
|
345 @end defun
|
|
|
346
|
|
|
347 @defun set-frame-size frame cols rows &optional pretend
|
|
|
348 This function sets the size of @var{frame}, measured in characters;
|
|
|
349 @var{cols} and @var{rows} specify the new width and height. (If
|
|
|
350 @var{pretend} is non-nil, it means that redisplay should act as if
|
|
|
351 the frame's size is @var{cols} by @var{rows}, but the actual size
|
|
|
352 of the frame should not be changed. You should not normally use
|
|
|
353 this option.)
|
|
|
354 @end defun
|
|
|
355
|
|
|
356 You can also use the functions @code{set-frame-height} and
|
|
|
357 @code{set-frame-width} to set the height and width individually.
|
|
|
358 The frame is the first argument and the size (in rows or columns)
|
|
|
359 is the second. (There is an optional third argument, @var{pretend},
|
|
|
360 which has the same purpose as the corresponding argument in
|
|
|
361 @code{set-frame-size}.)
|
|
|
362
|
|
|
363 @ignore @c Not in XEmacs
|
|
|
364 @defun x-parse-geometry geom
|
|
|
365 @cindex geometry specification
|
|
|
366 The function @code{x-parse-geometry} converts a standard X windows
|
|
|
367 geometry string to an alist that you can use as part of the argument to
|
|
|
368 @code{make-frame}.
|
|
|
369
|
|
|
370 The alist describes which parameters were specified in @var{geom}, and
|
|
|
371 gives the values specified for them. Each element looks like
|
|
|
372 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
|
|
|
373 values are @code{left}, @code{top}, @code{width}, and @code{height}.
|
|
|
374
|
|
|
375 For the size parameters, the value must be an integer. The position
|
|
|
376 parameter names @code{left} and @code{top} are not totally accurate,
|
|
|
377 because some values indicate the position of the right or bottom edges
|
|
|
378 instead. These are the @var{value} possibilities for the position
|
|
|
379 parameters:
|
|
|
380
|
|
|
381 @table @asis
|
|
|
382 @item an integer
|
|
|
383 A positive integer relates the left edge or top edge of the window to
|
|
|
384 the left or top edge of the screen. A negative integer relates the
|
|
|
385 right or bottom edge of the window to the right or bottom edge of the
|
|
|
386 screen.
|
|
|
387
|
|
|
388 @item @code{(+ @var{position})}
|
|
|
389 This specifies the position of the left or top edge of the window
|
|
|
390 relative to the left or top edge of the screen. The integer
|
|
|
391 @var{position} may be positive or negative; a negative value specifies a
|
|
|
392 position outside the screen.
|
|
|
393
|
|
|
394 @item @code{(- @var{position})}
|
|
|
395 This specifies the position of the right or bottom edge of the window
|
|
|
396 relative to the right or bottom edge of the screen. The integer
|
|
|
397 @var{position} may be positive or negative; a negative value specifies a
|
|
|
398 position outside the screen.
|
|
|
399 @end table
|
|
|
400
|
|
|
401 Here is an example:
|
|
|
402
|
|
|
403 @example
|
|
|
404 (x-parse-geometry "35x70+0-0")
|
|
|
405 @result{} ((width . 35) (height . 70)
|
|
|
406 (left . 0) (top - 0))
|
|
|
407 @end example
|
|
|
408 @end defun
|
|
|
409 @end ignore
|
|
|
410
|
|
|
411 @node Frame Name
|
|
|
412 @subsection The Name of a Frame (As Opposed to Its Title)
|
|
|
413 @cindex frame name
|
|
|
414
|
|
|
415 Under X, every frame has a name, which is not the same as the title of
|
|
|
416 the frame. A frame's name is used to look up its resources and does
|
|
|
417 not normally change over the lifetime of a frame. It is perfectly
|
|
|
418 allowable, and quite common, for multiple frames to have the same
|
|
|
419 name.
|
|
|
420
|
|
|
421 @defun frame-name &optional frame
|
|
|
422 This function returns the name of @var{frame}, which defaults to the
|
|
|
423 selected frame if not specified. The name of a frame can also be
|
|
|
424 obtained from the frame's parameters. @xref{Frame Parameters}.
|
|
|
425 @end defun
|
|
|
426
|
|
|
427 @defvar default-frame-name
|
|
|
428 This variable holds the default name to assign to newly-created frames.
|
|
|
429 This can be overridden by arguments to @code{make-frame}. This
|
|
|
430 must be a string.
|
|
|
431 @end defvar
|
|
|
432
|
|
|
433 @node Frame Titles
|
|
|
434 @section Frame Titles
|
|
|
435
|
|
|
436 Every frame has a title; most window managers display the frame title at
|
|
|
437 the top of the frame. You can specify an explicit title with the
|
|
|
438 @code{name} frame property. But normally you don't specify this
|
|
|
439 explicitly, and Emacs computes the title automatically.
|
|
|
440
|
|
|
441 Emacs computes the frame title based on a template stored in the
|
|
|
442 variable @code{frame-title-format}.
|
|
|
443
|
|
|
444 @defvar frame-title-format
|
|
|
445 This variable specifies how to compute a title for a frame
|
|
|
446 when you have not explicitly specified one.
|
|
|
447
|
|
|
448 The variable's value is actually a modeline construct, just like
|
|
|
449 @code{modeline-format}. @xref{Modeline Data}.
|
|
|
450 @end defvar
|
|
|
451
|
|
|
452 @defvar frame-icon-title-format
|
|
|
453 This variable specifies how to compute the title for an iconified frame,
|
|
|
454 when you have not explicitly specified the frame title. This title
|
|
|
455 appears in the icon itself.
|
|
|
456 @end defvar
|
|
|
457
|
|
|
458 @defun x-set-frame-icon-pixmap frame pixmap &optional mask
|
|
|
459 This function sets the icon of the given frame to the given image
|
|
|
460 instance, which should be an image instance object (as returned by
|
|
|
461 @code{make-image-instance}), a glyph object (as returned by
|
|
|
462 @code{make-glyph}), or @code{nil}. If a glyph object is given, the
|
|
|
463 glyph will be instantiated on the frame to produce an image instance
|
|
|
464 object.
|
|
|
465
|
|
|
466 If the given image instance has a mask, that will be used as the icon mask;
|
|
|
467 however, not all window managers support this.
|
|
|
468
|
|
|
469 The window manager is also not required to support color pixmaps,
|
|
|
470 only bitmaps (one plane deep).
|
|
|
471
|
|
|
472 If the image instance does not have a mask, then the optional
|
|
|
473 third argument may be the image instance to use as the mask (it must be
|
|
|
474 one plane deep).
|
|
|
475 @xref{Glyphs}.
|
|
|
476 @end defun
|
|
|
477
|
|
|
478 @node Deleting Frames
|
|
|
479 @section Deleting Frames
|
|
|
480 @cindex deletion of frames
|
|
|
481
|
|
|
482 Frames remain potentially visible until you explicitly @dfn{delete}
|
|
|
483 them. A deleted frame cannot appear on the screen, but continues to
|
|
|
484 exist as a Lisp object until there are no references to it.
|
|
|
485
|
|
|
486 @deffn Command delete-frame &optional frame
|
|
|
487 This function deletes the frame @var{frame}. By default, @var{frame} is
|
|
|
488 the selected frame.
|
|
|
489 @end deffn
|
|
|
490
|
|
|
491 @defun frame-live-p frame
|
|
|
492 The function @code{frame-live-p} returns non-@code{nil} if the frame
|
|
|
493 @var{frame} has not been deleted.
|
|
|
494 @end defun
|
|
|
495
|
|
|
496 @ignore Not in XEmacs currently
|
|
|
497 Some window managers provide a command to delete a window. These work
|
|
|
498 by sending a special message to the program that operates the window.
|
|
|
499 When Emacs gets one of these commands, it generates a
|
|
|
500 @code{delete-frame} event, whose normal definition is a command that
|
|
|
501 calls the function @code{delete-frame}. @xref{Misc Events}.
|
|
|
502 @end ignore
|
|
|
503
|
|
|
504 @node Finding All Frames
|
|
|
505 @section Finding All Frames
|
|
|
506
|
|
|
507 @defun frame-list
|
|
|
508 The function @code{frame-list} returns a list of all the frames that
|
|
|
509 have not been deleted. It is analogous to @code{buffer-list} for
|
|
|
510 buffers. The list that you get is newly created, so modifying the list
|
|
|
511 doesn't have any effect on the internals of XEmacs.
|
|
|
512 @end defun
|
|
|
513
|
|
|
514 @defun device-frame-list &optional device
|
|
|
515 This function returns a list of all frames on @var{device}. If
|
|
|
516 @var{device} is @code{nil}, the selected device will be used.
|
|
|
517 @end defun
|
|
|
518
|
|
|
519 @defun visible-frame-list &optional device
|
|
|
520 This function returns a list of just the currently visible frames.
|
|
|
521 If @var{device} is specified only frames on that device will be returned.
|
|
|
522 @xref{Visibility of Frames}. (TTY frames always count as
|
|
|
523 ``visible'', even though only the selected one is actually displayed.)
|
|
|
524 @end defun
|
|
|
525
|
|
|
526 @defun next-frame &optional frame minibuf
|
|
|
527 The function @code{next-frame} lets you cycle conveniently through all
|
|
|
528 the frames from an arbitrary starting point. It returns the ``next''
|
|
|
529 frame after @var{frame} in the cycle. If @var{frame} is omitted or
|
|
|
530 @code{nil}, it defaults to the selected frame.
|
|
|
531
|
|
|
532 The second argument, @var{minibuf}, says which frames to consider:
|
|
|
533
|
|
|
534 @table @asis
|
|
|
535 @item @code{nil}
|
|
|
536 Exclude minibuffer-only frames.
|
|
|
537 @item @code{visible}
|
|
|
538 Consider all visible frames.
|
|
|
539 @item 0
|
|
|
540 Consider all visible or iconified frames.
|
|
|
541 @item a window
|
|
|
542 Consider only the frames using that particular window as their
|
|
|
543 minibuffer.
|
|
|
544 @item the symbol @code{visible}
|
|
|
545 Include all visible frames.
|
|
|
546 @item @code{0}
|
|
|
547 Include all visible and iconified frames.
|
|
|
548 @item anything else
|
|
|
549 Consider all frames.
|
|
|
550 @end table
|
|
|
551 @end defun
|
|
|
552
|
|
|
553 @defun previous-frame &optional frame minibuf
|
|
|
554 Like @code{next-frame}, but cycles through all frames in the opposite
|
|
|
555 direction.
|
|
|
556 @end defun
|
|
|
557
|
|
|
558 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
|
|
|
559 Window Ordering}.
|
|
|
560
|
|
|
561 @node Frames and Windows
|
|
|
562 @section Frames and Windows
|
|
|
563
|
|
|
564 Each window is part of one and only one frame; you can get the frame
|
|
|
565 with @code{window-frame}.
|
|
|
566
|
|
|
567 @defun frame-root-window &optional frame
|
|
|
568 This returns the root window of frame @var{frame}. @var{frame}
|
|
|
569 defaults to the selected frame if not specified.
|
|
|
570 @end defun
|
|
|
571
|
|
|
572 @defun window-frame &optional window
|
|
|
573 This function returns the frame that @var{window} is on. @var{window}
|
|
|
574 defaults to the selected window if omitted.
|
|
|
575 @end defun
|
|
|
576
|
|
|
577 All the non-minibuffer windows in a frame are arranged in a cyclic
|
|
|
578 order. The order runs from the frame's top window, which is at the
|
|
|
579 upper left corner, down and to the right, until it reaches the window at
|
|
|
580 the lower right corner (always the minibuffer window, if the frame has
|
|
|
581 one), and then it moves back to the top.
|
|
|
582
|
|
|
583 @defun frame-top-window frame
|
|
|
584 This returns the topmost, leftmost window of frame @var{frame}.
|
|
|
585 @end defun
|
|
|
586
|
|
|
587 At any time, exactly one window on any frame is @dfn{selected within the
|
|
|
588 frame}. The significance of this designation is that selecting the
|
|
|
589 frame also selects this window. You can get the frame's current
|
|
|
590 selected window with @code{frame-selected-window}.
|
|
|
591
|
|
|
592 @defun frame-selected-window &optional frame
|
|
|
593 This function returns the window on @var{frame} that is selected within
|
|
|
594 @var{frame}. @var{frame} defaults to the selected frame if not
|
|
|
595 specified.
|
|
|
596 @end defun
|
|
|
597
|
|
|
598 Conversely, selecting a window for XEmacs with @code{select-window} also
|
|
|
599 makes that window selected within its frame. @xref{Selecting Windows}.
|
|
|
600
|
|
|
601 Another function that (usually) returns one of the windows in a frame is
|
|
|
602 @code{minibuffer-window}. @xref{Minibuffer Misc}.
|
|
|
603
|
|
|
604 @node Minibuffers and Frames
|
|
|
605 @section Minibuffers and Frames
|
|
|
606
|
|
|
607 Normally, each frame has its own minibuffer window at the bottom, which
|
|
|
608 is used whenever that frame is selected. If the frame has a minibuffer,
|
|
|
609 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
|
|
|
610
|
|
|
611 However, you can also create a frame with no minibuffer (this is not
|
|
|
612 implemented as of 19.13, but will be in 19.14). Such a frame must use
|
|
|
613 the minibuffer window of some other frame. When you create the frame,
|
|
|
614 you can specify explicitly the minibuffer window to use (in some other
|
|
|
615 frame). If you don't, then the minibuffer is found in the frame which is
|
|
|
616 the value of the variable @code{default-minibuffer-frame}. Its value
|
|
|
617 should be a frame which does have a minibuffer.
|
|
|
618
|
|
|
619 @ignore Not yet in XEmacs
|
|
|
620 If you use a minibuffer-only frame, you might want that frame to raise
|
|
|
621 when you enter the minibuffer. If so, set the variable
|
|
|
622 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
|
|
|
623 @end ignore
|
|
|
624
|
|
|
625 @defvar default-minibuffer-frame
|
|
|
626 This variable specifies the frame to use for the minibuffer window, by
|
|
|
627 default.
|
|
|
628 @end defvar
|
|
|
629
|
|
|
630 @node Input Focus
|
|
|
631 @section Input Focus
|
|
|
632 @cindex input focus
|
|
|
633 @cindex selected frame
|
|
|
634
|
|
|
635 At any time, one frame in XEmacs is the @dfn{selected frame}. The selected
|
|
|
636 window always resides on the selected frame. As the focus moves from
|
|
|
637 device to device, the selected frame on each device is remembered and
|
|
|
638 restored when the focus moves back to that device.
|
|
|
639
|
|
|
640 @defun selected-frame &optional device
|
|
|
641 This function returns the selected frame on @var{device}. If
|
|
|
642 @var{device} is not specified, the selected device will be used. If no
|
|
|
643 frames exist on the device, @code{nil} is returned.
|
|
|
644 @end defun
|
|
|
645
|
|
|
646 The X server normally directs keyboard input to the X window that the
|
|
|
647 mouse is in. Some window managers use mouse clicks or keyboard events
|
|
|
648 to @dfn{shift the focus} to various X windows, overriding the normal
|
|
|
649 behavior of the server.
|
|
|
650
|
|
|
651 Lisp programs can switch frames ``temporarily'' by calling
|
|
|
652 the function @code{select-frame}. This does not override the window
|
|
|
653 manager; rather, it escapes from the window manager's control until
|
|
|
654 that control is somehow reasserted.
|
|
|
655
|
|
|
656 When using a text-only terminal, there is no window manager; therefore,
|
|
|
657 @code{select-frame} is the only way to switch frames, and the effect
|
|
|
658 lasts until overridden by a subsequent call to @code{select-frame}.
|
|
|
659 Only the selected terminal frame is actually displayed on the terminal.
|
|
|
660 Each terminal screen except for the initial one has a number, and the
|
|
|
661 number of the selected frame appears in the mode line after the word
|
|
|
662 @samp{Emacs} (@pxref{Modeline Variables}).
|
|
|
663
|
|
|
664 @defun select-frame frame
|
|
|
665 This function selects frame @var{frame}, temporarily disregarding the
|
|
|
666 focus of the X server if any. The selection of @var{frame} lasts until
|
|
|
667 the next time the user does something to select a different frame, or
|
|
|
668 until the next time this function is called.
|
|
|
669 @end defun
|
|
|
670
|
|
|
671 Note that this does not actually cause the window-system focus to be set
|
|
|
672 to this frame, or the @code{select-frame-hook} or
|
|
|
673 @code{deselect-frame-hook} to be run, until the next time that XEmacs is
|
|
|
674 waiting for an event.
|
|
|
675
|
|
|
676 @ignore (FSF Emacs)
|
|
|
677 Emacs cooperates with the X server and the window managers by arranging
|
|
|
678 to select frames according to what the server and window manager ask
|
|
|
679 for. It does so by generating a special kind of input event, called a
|
|
|
680 @dfn{focus} event. The command loop handles a focus event by calling
|
|
|
681 @code{handle-select-frame}. @xref{Focus Events}.
|
|
|
682
|
|
|
683 @deffn Command handle-switch-frame frame
|
|
|
684 This function handles a focus event by selecting frame @var{frame}.
|
|
|
685
|
|
|
686 Focus events normally do their job by invoking this command.
|
|
|
687 Don't call it for any other reason.
|
|
|
688 @end deffn
|
|
|
689
|
|
|
690 @defun redirect-frame-focus frame focus-frame
|
|
|
691 This function redirects focus from @var{frame} to @var{focus-frame}.
|
|
|
692 This means that @var{focus-frame} will receive subsequent keystrokes
|
|
|
693 intended for @var{frame}. After such an event, the value of
|
|
|
694 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
|
|
|
695 events specifying @var{frame} will instead select @var{focus-frame}.
|
|
|
696
|
|
|
697 If @var{focus-frame} is @code{nil}, that cancels any existing
|
|
|
698 redirection for @var{frame}, which therefore once again receives its own
|
|
|
699 events.
|
|
|
700
|
|
|
701 One use of focus redirection is for frames that don't have minibuffers.
|
|
|
702 These frames use minibuffers on other frames. Activating a minibuffer
|
|
|
703 on another frame redirects focus to that frame. This puts the focus on
|
|
|
704 the minibuffer's frame, where it belongs, even though the mouse remains
|
|
|
705 in the frame that activated the minibuffer.
|
|
|
706
|
|
|
707 Selecting a frame can also change focus redirections. Selecting frame
|
|
|
708 @code{bar}, when @code{foo} had been selected, changes any redirections
|
|
|
709 pointing to @code{foo} so that they point to @code{bar} instead. This
|
|
|
710 allows focus redirection to work properly when the user switches from
|
|
|
711 one frame to another using @code{select-window}.
|
|
|
712
|
|
|
713 This means that a frame whose focus is redirected to itself is treated
|
|
|
714 differently from a frame whose focus is not redirected.
|
|
|
715 @code{select-frame} affects the former but not the latter.
|
|
|
716
|
|
|
717 The redirection lasts until @code{redirect-frame-focus} is called to
|
|
|
718 change it.
|
|
|
719 @end defun
|
|
|
720 @end ignore
|
|
|
721
|
|
|
722 @node Visibility of Frames
|
|
|
723 @section Visibility of Frames
|
|
|
724 @cindex visible frame
|
|
|
725 @cindex invisible frame
|
|
|
726 @cindex iconified frame
|
|
|
727 @cindex frame visibility
|
|
|
728
|
|
|
729 An X window frame may be @dfn{visible}, @dfn{invisible}, or
|
|
|
730 @dfn{iconified}. If it is visible, you can see its contents. If it is
|
|
|
731 iconified, the frame's contents do not appear on the screen, but an icon
|
|
|
732 does. If the frame is invisible, it doesn't show on the screen, not
|
|
|
733 even as an icon.
|
|
|
734
|
|
|
735 Visibility is meaningless for TTY frames, since only the selected
|
|
|
736 one is actually displayed in any case.
|
|
|
737
|
|
|
738 @deffn Command make-frame-visible &optional frame
|
|
|
739 This function makes frame @var{frame} visible. If you omit @var{frame},
|
|
|
740 it makes the selected frame visible.
|
|
|
741 @end deffn
|
|
|
742
|
|
|
743 @deffn Command make-frame-invisible &optional frame
|
|
|
744 This function makes frame @var{frame} invisible.
|
|
|
745 @end deffn
|
|
|
746
|
|
|
747 @deffn Command iconify-frame &optional frame
|
|
|
748 This function iconifies frame @var{frame}.
|
|
|
749 @end deffn
|
|
|
750
|
|
|
751 @deffn Command deiconify-frame &optional frame
|
|
|
752 This function de-iconifies frame @var{frame}. Under X, this is
|
|
|
753 equivalent to @code{make-frame-visible}.
|
|
|
754 @end deffn
|
|
|
755
|
|
|
756 @defun frame-visible-p frame
|
|
|
757 This returns whether @var{frame} is currently ``visible'' (actually in
|
|
|
758 use for display). A frame that is not visible is not updated, and, if
|
|
|
759 it works through a window system, may not show at all.
|
|
|
760 @end defun
|
|
|
761
|
|
|
762 @defun frame-iconified-p frame
|
|
|
763 This returns whether @var{frame} is iconified. Not all window managers
|
|
|
764 use icons; some merely unmap the window, so this function is not the
|
|
|
765 inverse of @code{frame-visible-p}. It is possible for a frame to not
|
|
|
766 be visible and not be iconified either. However, if the frame is
|
|
|
767 iconified, it will not be visible. (Under FSF Emacs, the functionality
|
|
|
768 of this function is obtained through @code{frame-visible-p}.)
|
|
|
769 @end defun
|
|
|
770
|
|
|
771 @defun frame-totally-visible-p frame
|
|
|
772 This returns whether @var{frame} is not obscured by any other X
|
|
|
773 windows. On TTY frames, this is the same as @code{frame-visible-p}.
|
|
|
774 @end defun
|
|
|
775
|
|
|
776 @ignore @c Not in XEmacs.
|
|
|
777 The visibility status of a frame is also available as a frame
|
|
|
778 parameter. You can read or change it as such. @xref{X Frame
|
|
|
779 Parameters}.
|
|
|
780
|
|
|
781 The user can iconify and deiconify frames with the window manager.
|
|
|
782 This happens below the level at which Emacs can exert any control, but
|
|
|
783 Emacs does provide events that you can use to keep track of such
|
|
|
784 changes. @xref{Misc Events}.
|
|
|
785 @end ignore
|
|
|
786
|
|
|
787 @node Raising and Lowering
|
|
|
788 @section Raising and Lowering Frames
|
|
|
789
|
|
|
790 The X Window System uses a desktop metaphor. Part of this metaphor is
|
|
|
791 the idea that windows are stacked in a notional third dimension
|
|
|
792 perpendicular to the screen surface, and thus ordered from ``highest''
|
|
|
793 to ``lowest''. Where two windows overlap, the one higher up covers the
|
|
|
794 one underneath. Even a window at the bottom of the stack can be seen if
|
|
|
795 no other window overlaps it.
|
|
|
796
|
|
|
797 @cindex raising a frame
|
|
|
798 @cindex lowering a frame
|
|
|
799 A window's place in this ordering is not fixed; in fact, users tend to
|
|
|
800 change the order frequently. @dfn{Raising} a window means moving it
|
|
|
801 ``up'', to the top of the stack. @dfn{Lowering} a window means moving
|
|
|
802 it to the bottom of the stack. This motion is in the notional third
|
|
|
803 dimension only, and does not change the position of the window on the
|
|
|
804 screen.
|
|
|
805
|
|
|
806 You can raise and lower XEmacs's X windows with these functions:
|
|
|
807
|
|
|
808 @deffn Command raise-frame &optional frame
|
|
|
809 This function raises frame @var{frame}.
|
|
|
810 @end deffn
|
|
|
811
|
|
|
812 @deffn Command lower-frame &optional frame
|
|
|
813 This function lowers frame @var{frame}.
|
|
|
814 @end deffn
|
|
|
815
|
|
|
816 You can also specify auto-raise (raising automatically when a frame is
|
|
|
817 selected) or auto-lower (lowering automatically when it is deselected).
|
|
|
818 Under X, most ICCCM-compliant window managers will have an option to do
|
|
|
819 this for you, but the following variables are provided in case you're
|
|
|
820 using a broken WM. (Under FSF Emacs, the same functionality is
|
|
|
821 provided through the @code{auto-raise} and @code{auto-lower}
|
|
|
822 frame parameters.)
|
|
|
823
|
|
|
824 @defvar auto-raise-frame
|
|
|
825 This variable's value is @code{t} if frames will be raised to the top
|
|
|
826 when selected.
|
|
|
827 @end defvar
|
|
|
828
|
|
|
829 @ignore Not in XEmacs
|
|
|
830 @defopt minibuffer-auto-raise
|
|
|
831 If this is non-@code{nil}, activation of the minibuffer raises the frame
|
|
|
832 that the minibuffer window is in.
|
|
|
833 @end defopt
|
|
|
834 @end ignore
|
|
|
835
|
|
|
836 @defvar auto-lower-frame
|
|
|
837 This variable's value is @code{t} if frames will be lowered to the bottom
|
|
|
838 when no longer selected.
|
|
|
839 @end defvar
|
|
|
840
|
|
|
841 Auto-raising and auto-lowering is implemented through functions attached
|
|
|
842 to @code{select-frame-hook} and @code{deselect-frame-hook}
|
|
|
843 (@pxref{Frame Hooks}). Under normal circumstances, you should not call
|
|
|
844 these functions directly.
|
|
|
845
|
|
|
846 @defun default-select-frame-hook
|
|
|
847 This hook function implements the @code{auto-raise-frame} variable; it is
|
|
|
848 for use as the value of @code{select-frame-hook}.
|
|
|
849 @end defun
|
|
|
850
|
|
|
851 @defun default-deselect-frame-hook
|
|
|
852 This hook function implements the @code{auto-lower-frame} variable; it is
|
|
|
853 for use as the value of @code{deselect-frame-hook}.
|
|
|
854 @end defun
|
|
|
855
|
|
|
856 @node Frame Configurations
|
|
|
857 @section Frame Configurations
|
|
|
858 @cindex frame configuration
|
|
|
859
|
|
|
860 A @dfn{frame configuration} records the current arrangement of frames,
|
|
|
861 all their properties, and the window configuration of each one.
|
|
|
862
|
|
|
863 @defun current-frame-configuration
|
|
|
864 This function returns a frame configuration list that describes
|
|
|
865 the current arrangement of frames and their contents.
|
|
|
866 @end defun
|
|
|
867
|
|
|
868 @defun set-frame-configuration configuration
|
|
|
869 This function restores the state of frames described in
|
|
|
870 @var{configuration}.
|
|
|
871 @end defun
|
|
|
872
|
|
|
873 @node Frame Hooks
|
|
|
874 @section Hooks for Customizing Frame Behavior
|
|
|
875 @cindex frame hooks
|
|
|
876
|
|
|
877 XEmacs provides many hooks that are called at various times during a
|
|
|
878 frame's lifetime. @xref{Hooks}.
|
|
|
879
|
|
|
880 @defvar create-frame-hook
|
|
|
881 This hook is called each time a frame is created. The functions are called
|
|
|
882 with one argument, the newly-created frame.
|
|
|
883 @end defvar
|
|
|
884
|
|
|
885 @defvar delete-frame-hook
|
|
|
886 This hook is called each time a frame is deleted. The functions are called
|
|
|
887 with one argument, the about-to-be-deleted frame.
|
|
|
888 @end defvar
|
|
|
889
|
|
|
890 @defvar select-frame-hook
|
|
|
891 This is a normal hook that is run just after a frame is selected. The
|
|
|
892 function @code{default-select-frame-hook}, which implements auto-raising
|
|
|
893 (@pxref{Raising and Lowering}), is normally attached to this hook.
|
|
|
894
|
|
|
895 Note that calling @code{select-frame} does not necessarily set the
|
|
|
896 focus: The actual window-system focus will not be changed until the next
|
|
|
897 time that XEmacs is waiting for an event, and even then, the window
|
|
|
898 manager may refuse the focus-change request.
|
|
|
899 @end defvar
|
|
|
900
|
|
|
901 @defvar deselect-frame-hook
|
|
|
902 This is a normal hook that is run just before a frame is deselected
|
|
|
903 (and another frame is selected). The function
|
|
|
904 @code{default-deselect-frame-hook}, which implements auto-lowering
|
|
|
905 (@pxref{Raising and Lowering}), is normally attached to this hook.
|
|
|
906 @end defvar
|
|
|
907
|
|
|
908 @defvar map-frame-hook
|
|
|
909 This hook is called each time a frame is mapped (i.e. made visible).
|
|
|
910 The functions are called with one argument, the newly mapped frame.
|
|
|
911 @end defvar
|
|
|
912
|
|
|
913 @defvar unmap-frame-hook
|
|
|
914 This hook is called each time a frame is unmapped (i.e. made invisible
|
|
|
915 or iconified). The functions are called with one argument, the
|
|
|
916 newly unmapped frame.
|
|
|
917 @end defvar
|
