Mercurial > hg > xemacs-beta

comparison man/lispref/frames.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children ac2d302a0011
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
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