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
11 A @var{frame} is a rectangle on the screen that contains one or more
12 XEmacs windows (@pxref{Windows}). A frame initially contains a single
13 main window (plus perhaps an echo area), which you can subdivide
14 vertically or horizontally into smaller windows. Each window is
15 associated with a modeline (@pxref{Modeline Format}), and optionally two
16 scrollbars (@pxref{Scrollbars}). By default the vertical scrollbar is
17 on, the horizontal scrollbar is off.
19 The frame may also contain menubars (@pxref{Menubar}), toolbars
20 (@pxref{Toolbar Intro}), and gutters (@pxref{Gutter Intro}). By default
21 there is one of each at the top of the frame, with menubar topmost,
22 toolbar next, and gutter lowest, immediately above the windows.
23 (Warning: the gutter is a new, experimental, and unstable feature of
26 @cindex terminal frame
27 @cindex X window frame
28 When XEmacs runs on a text-only terminal, it starts with one
29 @dfn{TTY frame}. If you create additional ones, XEmacs displays
30 one and only one at any given time---on the terminal screen, of course.
32 When XEmacs communicates directly with an X server, it does not have a
33 TTY frame; instead, it starts with a single @dfn{X window frame}.
34 It can display multiple X window frames at the same time, each in its
38 This predicate returns @code{t} if @var{object} is a frame, and
43 * Creating Frames:: Creating additional frames.
44 * Frame Properties:: Controlling frame size, position, font, etc.
45 * Frame Titles:: Automatic updating of frame titles.
46 * Deleting Frames:: Frames last until explicitly deleted.
47 * Finding All Frames:: How to examine all existing frames.
48 * Frames and Windows:: A frame contains windows;
49 display of text always works through windows.
50 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
51 * Input Focus:: Specifying the selected frame.
52 * Visibility of Frames:: Frames may be visible or invisible, or icons.
53 * Raising and Lowering:: Raising a frame makes it hide other X windows;
54 lowering it makes the others hide them.
55 * Frame Configurations:: Saving the state of all frames.
56 * Frame Hooks:: Hooks for customizing frame behavior.
59 @xref{Display}, for related information.
62 @section Creating Frames
64 To create a new frame, call the function @code{make-frame}.
66 @defun make-frame &optional props device
67 This function creates a new frame on @var{device}, if @var{device}
68 permits creation of frames. (An X server does; an ordinary terminal
69 does not (yet).) @var{device} defaults to the selected device if omitted.
70 @xref{Consoles and Devices}.
72 The argument @var{props} is a property list (a list of alternating
73 keyword-value specifications) of properties for the new frame. (An alist
74 is accepted for backward compatibility but should not be passed in.) Any
75 properties not mentioned in @var{props} default according to the value
76 of the variable @code{default-frame-plist}. For X devices, properties
77 not specified in @code{default-frame-plist} default in turn from
78 @code{default-x-frame-plist} and, if not specified there, from the X
79 resources. For TTY devices, @code{default-tty-frame-plist} is consulted
80 as well as @code{default-frame-plist}.
82 The set of possible properties depends in principle on what kind of
83 window system XEmacs uses to display its frames. @xref{X Frame
84 Properties}, for documentation of individual properties you can specify
85 when creating an X window frame.
88 @node Frame Properties
89 @section Frame Properties
91 A frame has many properties that control its appearance and behavior.
92 Just what properties a frame has depends on which display mechanism it
95 Frame properties exist for the sake of window systems. A terminal frame
96 has few properties, mostly for compatibility's sake; only the height,
97 width and @code{buffer-predicate} properties really do something.
100 * Property Access:: How to change a frame's properties.
101 * Initial Properties:: Specifying frame properties when you make a frame.
102 * X Frame Properties:: List of frame properties.
103 * Size and Position:: Changing the size and position of a frame.
104 * Frame Name:: The name of a frame (as opposed to its title).
107 @node Property Access
108 @subsection Access to Frame Properties
110 These functions let you read and change the properties of a frame.
112 @defun frame-properties &optional frame
113 This function returns a plist listing all the properties of @var{frame}
117 @defun frame-property frame property &optional default
118 This function returns @var{frame}'s value for the property
122 @defun set-frame-properties frame plist
123 This function alters the properties of frame @var{frame} based on the
124 elements of property list @var{plist}. If you don't mention a property
125 in @var{plist}, its value doesn't change.
128 @defun set-frame-property frame prop val
129 This function sets the property @var{prop} of frame @var{frame} to the
133 @node Initial Properties
134 @subsection Initial Frame Properties
136 You can specify the properties for the initial startup frame by setting
137 @code{initial-frame-plist} in your @file{.emacs} file.
139 @defvar initial-frame-plist
140 This variable's value is a plist of alternating property-value pairs
141 used when creating the initial X window frame.
143 XEmacs creates the initial frame before it reads your @file{~/.emacs}
144 file. After reading that file, XEmacs checks @code{initial-frame-plist},
145 and applies the property settings in the altered value to the already
146 created initial frame.
148 If these settings affect the frame geometry and appearance, you'll see
149 the frame appear with the wrong ones and then change to the specified
150 ones. If that bothers you, you can specify the same geometry and
151 appearance with X resources; those do take affect before the frame is
152 created. @xref{Resources X,, X Resources, xemacs, The XEmacs User's Manual}.
154 X resource settings typically apply to all frames. If you want to
155 specify some X resources solely for the sake of the initial frame, and
156 you don't want them to apply to subsequent frames, here's how to achieve
157 this: specify properties in @code{default-frame-plist} to override the X
158 resources for subsequent frames; then, to prevent these from affecting
159 the initial frame, specify the same properties in
160 @code{initial-frame-plist} with values that match the X resources.
163 If these properties specify a separate minibuffer-only frame via a
164 @code{minibuffer} property of @code{nil}, and you have not yet created
165 one, XEmacs creates one for you.
167 @defvar minibuffer-frame-plist
168 This variable's value is a plist of properties used when creating an
169 initial minibuffer-only frame---if such a frame is needed, according to
170 the properties for the main initial frame.
173 @defvar default-frame-plist
174 This is a plist specifying default values of frame properties for
175 subsequent XEmacs frames (not the initial ones).
178 See also @code{special-display-frame-plist}, in @ref{Choosing Window}.
180 If you use options that specify window appearance when you invoke XEmacs,
181 they take effect by adding elements to @code{default-frame-plist}. One
182 exception is @samp{-geometry}, which adds the specified position to
183 @code{initial-frame-plist} instead. @xref{Command Arguments,,, xemacs,
184 The XEmacs User's Manual}.
186 @node X Frame Properties
187 @subsection X Window Frame Properties
189 Just what properties a frame has depends on what display mechanism it
190 uses. Here is a table of the properties of an X window frame; of these,
191 @code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
192 provide meaningful information in non-X frames.
196 The name of the frame. Most window managers display the frame's name in
197 the frame's border, at the top of the frame. If you don't specify a
198 name, and you have more than one frame, XEmacs sets the frame name based
199 on the buffer displayed in the frame's selected window.
201 If you specify the frame name explicitly when you create the frame, the
202 name is also used (instead of the name of the XEmacs executable) when
203 looking up X resources for the frame.
206 The display on which to open this frame. It should be a string of the
207 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
208 @code{DISPLAY} environment variable.
211 The screen position of the left edge, in pixels, with respect to the
212 left edge of the screen. The value may be a positive number @var{pos},
213 or a list of the form @code{(+ @var{pos})} which permits specifying a
214 negative @var{pos} value.
216 A negative number @minus{}@var{pos}, or a list of the form @code{(-
217 @var{pos})}, actually specifies the position of the right edge of the
218 window with respect to the right edge of the screen. A positive value
219 of @var{pos} counts toward the left. If the property is a negative
220 integer @minus{}@var{pos} then @var{pos} is positive!
223 The screen position of the top edge, in pixels, with respect to the
224 top edge of the screen. The value may be a positive number @var{pos},
225 or a list of the form @code{(+ @var{pos})} which permits specifying a
226 negative @var{pos} value.
228 A negative number @minus{}@var{pos}, or a list of the form @code{(-
229 @var{pos})}, actually specifies the position of the bottom edge of the
230 window with respect to the bottom edge of the screen. A positive value
231 of @var{pos} counts toward the top. If the property is a negative
232 integer @minus{}@var{pos} then @var{pos} is positive!
235 The screen position of the left edge @emph{of the frame's icon}, in
236 pixels, counting from the left edge of the screen. This takes effect if
237 and when the frame is iconified.
240 The screen position of the top edge @emph{of the frame's icon}, in
241 pixels, counting from the top edge of the screen. This takes effect if
242 and when the frame is iconified.
245 Non-@code{nil} if the screen position of the frame was explicitly
246 requested by the user (for example, with the @samp{-geometry} option).
247 Nothing automatically makes this property non-@code{nil}; it is up to
248 Lisp programs that call @code{make-frame} to specify this property as
249 well as specifying the @code{left} and @code{top} properties.
252 The height of the frame contents, in characters. (To get the height in
253 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
256 The width of the frame contents, in characters. (To get the height in
257 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
260 The number of the X window for the frame.
263 Whether this frame has its own minibuffer. The value @code{t} means
264 yes, @code{nil} means no, @code{only} means this frame is just a
265 minibuffer. If the value is a minibuffer window (in some other frame),
266 the new frame uses that minibuffer. (Minibuffer-only and minibuffer-less
267 frames are not yet implemented in XEmacs.)
269 @item buffer-predicate
270 The buffer-predicate function for this frame. The function
271 @code{other-buffer} uses this predicate (from the selected frame) to
272 decide which buffers it should consider, if the predicate is not
273 @code{nil}. It calls the predicate with one arg, a buffer, once for
274 each buffer; if the predicate returns a non-@code{nil} value, it
275 considers that buffer.
277 @item scroll-bar-width
278 The width of the vertical scroll bar, in pixels.
280 @ignore Not in XEmacs
282 The type of icon to use for this frame when it is iconified. If the
283 value is a string, that specifies a file containing a bitmap to use.
284 Any other non-@code{nil} value specifies the default bitmap icon (a
285 picture of a gnu); @code{nil} specifies a text icon.
288 The name to use in the icon for this frame, when and if the icon
289 appears. If this is @code{nil}, the frame's title is used.
293 The color for the cursor that shows point.
296 The color for the border of the frame.
298 @ignore Not in XEmacs
300 The way to display the cursor. The legitimate values are @code{bar},
301 @code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
302 specifies an ordinary black box overlaying the character after point;
303 that is the default. The symbol @code{bar} specifies a vertical bar
304 between characters as the cursor. @code{(bar . @var{width})} specifies
305 a bar @var{width} pixels wide.
309 The width in pixels of the window border.
311 @item internal-border-width
312 The distance in pixels between text and border.
315 If non-@code{nil}, this frame's window is never split automatically.
317 @item inter-line-space
318 The space in pixels between adjacent lines of text. (Not currently
322 Whether the frame has a modeline.
325 @node Size and Position
326 @subsection Frame Size And Position
327 @cindex size of frame
329 @cindex display lines
330 @cindex display columns
331 @cindex resize redisplay
332 @cindex frame position
333 @cindex position of frame
335 You can read or change the size and position of a frame using the
336 frame properties @code{left}, @code{top}, @code{height}, and
337 @code{width}. Whatever geometry properties you don't specify are chosen
338 by the window manager in its usual fashion.
340 Here are some special features for working with sizes and positions:
342 @defun set-frame-position frame left top
343 This function sets the position of the top left corner of @var{frame} to
344 @var{left} and @var{top}. These arguments are measured in pixels, and
345 count from the top left corner of the screen. Negative property values
346 count up or rightward from the top left corner of the screen.
349 @defun frame-height &optional frame
350 @defunx frame-width &optional frame
351 These functions return the height and width of @var{frame}, measured in
352 lines and columns. If you don't supply @var{frame}, they use the selected
356 @defun frame-pixel-height &optional frame
357 @defunx frame-pixel-width &optional frame
358 These functions return the height and width of @var{frame}, measured in
359 pixels. If you don't supply @var{frame}, they use the selected frame.
362 @defun set-frame-size frame cols rows &optional pretend
363 This function sets the size of @var{frame}, measured in characters;
364 @var{cols} and @var{rows} specify the new width and height. (If
365 @var{pretend} is non-nil, it means that redisplay should act as if
366 the frame's size is @var{cols} by @var{rows}, but the actual size
367 of the frame should not be changed. You should not normally use
371 You can also use the functions @code{set-frame-height} and
372 @code{set-frame-width} to set the height and width individually.
373 The frame is the first argument and the size (in rows or columns)
374 is the second. (There is an optional third argument, @var{pretend},
375 which has the same purpose as the corresponding argument in
376 @code{set-frame-size}.)
378 @ignore @c Not in XEmacs
379 @defun x-parse-geometry geom
380 @cindex geometry specification
381 The function @code{x-parse-geometry} converts a standard X windows
382 geometry string to a plist that you can use as part of the argument to
385 The plist describes which properties were specified in @var{geom}, and
386 gives the values specified for them. Each element looks like
387 @code{(@var{property} . @var{value})}. The possible @var{property}
388 values are @code{left}, @code{top}, @code{width}, and @code{height}.
390 For the size properties, the value must be an integer. The position
391 property names @code{left} and @code{top} are not totally accurate,
392 because some values indicate the position of the right or bottom edges
393 instead. These are the @var{value} possibilities for the position
398 A positive integer relates the left edge or top edge of the window to
399 the left or top edge of the screen. A negative integer relates the
400 right or bottom edge of the window to the right or bottom edge of the
403 @item @code{(+ @var{position})}
404 This specifies the position of the left or top edge of the window
405 relative to the left or top edge of the screen. The integer
406 @var{position} may be positive or negative; a negative value specifies a
407 position outside the screen.
409 @item @code{(- @var{position})}
410 This specifies the position of the right or bottom edge of the window
411 relative to the right or bottom edge of the screen. The integer
412 @var{position} may be positive or negative; a negative value specifies a
413 position outside the screen.
419 (x-parse-geometry "35x70+0-0")
420 @result{} ((width . 35) (height . 70)
421 (left . 0) (top - 0))
427 @subsection The Name of a Frame (As Opposed to Its Title)
430 Under X, every frame has a name, which is not the same as the title of
431 the frame. A frame's name is used to look up its resources and does
432 not normally change over the lifetime of a frame. It is perfectly
433 allowable, and quite common, for multiple frames to have the same
436 @defun frame-name &optional frame
437 This function returns the name of @var{frame}, which defaults to the
438 selected frame if not specified. The name of a frame can also be
439 obtained from the frame's properties. @xref{Frame Properties}.
442 @defvar default-frame-name
443 This variable holds the default name to assign to newly-created frames.
444 This can be overridden by arguments to @code{make-frame}. This
449 @section Frame Titles
451 Every frame has a title; most window managers display the frame title at
452 the top of the frame. You can specify an explicit title with the
453 @code{name} frame property. But normally you don't specify this
454 explicitly, and XEmacs computes the title automatically.
456 XEmacs computes the frame title based on a template stored in the
457 variable @code{frame-title-format}.
459 @defvar frame-title-format
460 This variable specifies how to compute a title for a frame
461 when you have not explicitly specified one.
463 The variable's value is actually a modeline construct, just like
464 @code{modeline-format}. @xref{Modeline Data}.
467 @defvar frame-icon-title-format
468 This variable specifies how to compute the title for an iconified frame,
469 when you have not explicitly specified the frame title. This title
470 appears in the icon itself.
473 @defun x-set-frame-icon-pixmap frame pixmap &optional mask
474 This function sets the icon of the given frame to the given image
475 instance, which should be an image instance object (as returned by
476 @code{make-image-instance}), a glyph object (as returned by
477 @code{make-glyph}), or @code{nil}. If a glyph object is given, the
478 glyph will be instantiated on the frame to produce an image instance
481 If the given image instance has a mask, that will be used as the icon mask;
482 however, not all window managers support this.
484 The window manager is also not required to support color pixmaps,
485 only bitmaps (one plane deep).
487 If the image instance does not have a mask, then the optional
488 third argument may be the image instance to use as the mask (it must be
493 @node Deleting Frames
494 @section Deleting Frames
495 @cindex deletion of frames
497 Frames remain potentially visible until you explicitly @dfn{delete}
498 them. A deleted frame cannot appear on the screen, but continues to
499 exist as a Lisp object until there are no references to it.
501 @deffn Command delete-frame &optional frame
502 This function deletes the frame @var{frame}. By default, @var{frame} is
506 @defun frame-live-p frame
507 The function @code{frame-live-p} returns non-@code{nil} if the frame
508 @var{frame} has not been deleted.
511 @ignore Not in XEmacs currently
512 Some window managers provide a command to delete a window. These work
513 by sending a special message to the program that operates the window.
514 When XEmacs gets one of these commands, it generates a
515 @code{delete-frame} event, whose normal definition is a command that
516 calls the function @code{delete-frame}. @xref{Misc Events}.
519 @node Finding All Frames
520 @section Finding All Frames
523 The function @code{frame-list} returns a list of all the frames that
524 have not been deleted. It is analogous to @code{buffer-list} for
525 buffers. The list that you get is newly created, so modifying the list
526 doesn't have any effect on the internals of XEmacs.
529 @defun device-frame-list &optional device
530 This function returns a list of all frames on @var{device}. If
531 @var{device} is @code{nil}, the selected device will be used.
534 @defun visible-frame-list &optional device
535 This function returns a list of just the currently visible frames.
536 If @var{device} is specified only frames on that device will be returned.
537 @xref{Visibility of Frames}. (TTY frames always count as
538 ``visible'', even though only the selected one is actually displayed.)
541 @defun next-frame &optional frame minibuf
542 The function @code{next-frame} lets you cycle conveniently through all
543 the frames from an arbitrary starting point. It returns the ``next''
544 frame after @var{frame} in the cycle. If @var{frame} is omitted or
545 @code{nil}, it defaults to the selected frame.
547 The second argument, @var{minibuf}, says which frames to consider:
551 Exclude minibuffer-only frames.
553 Consider all visible frames.
555 Consider all visible or iconified frames.
557 Consider only the frames using that particular window as their
559 @item the symbol @code{visible}
560 Include all visible frames.
562 Include all visible and iconified frames.
568 @defun previous-frame &optional frame minibuf
569 Like @code{next-frame}, but cycles through all frames in the opposite
573 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
576 @node Frames and Windows
577 @section Frames and Windows
579 Each window is part of one and only one frame; you can get the frame
580 with @code{window-frame}.
582 @defun frame-root-window &optional frame
583 This returns the root window of frame @var{frame}. @var{frame}
584 defaults to the selected frame if not specified.
587 @defun window-frame &optional window
588 This function returns the frame that @var{window} is on. @var{window}
589 defaults to the selected window if omitted.
592 All the non-minibuffer windows in a frame are arranged in a cyclic
593 order. The order runs from the frame's top window, which is at the
594 upper left corner, down and to the right, until it reaches the window at
595 the lower right corner (always the minibuffer window, if the frame has
596 one), and then it moves back to the top.
598 @defun frame-top-window frame
599 This returns the topmost, leftmost window of frame @var{frame}.
602 At any time, exactly one window on any frame is @dfn{selected within the
603 frame}. The significance of this designation is that selecting the
604 frame also selects this window. You can get the frame's current
605 selected window with @code{frame-selected-window}.
607 @defun frame-selected-window &optional frame
608 This function returns the window on @var{frame} that is selected within
609 @var{frame}. @var{frame} defaults to the selected frame if not
613 Conversely, selecting a window for XEmacs with @code{select-window} also
614 makes that window selected within its frame. @xref{Selecting Windows}.
616 Another function that (usually) returns one of the windows in a frame is
617 @code{minibuffer-window}. @xref{Minibuffer Misc}.
619 @node Minibuffers and Frames
620 @section Minibuffers and Frames
622 Normally, each frame has its own minibuffer window at the bottom, which
623 is used whenever that frame is selected. If the frame has a minibuffer,
624 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
626 However, you can also create a frame with no minibuffer. Such a frame
627 must use the minibuffer window of some other frame. When you create the
628 frame, you can specify explicitly the minibuffer window to use (in some
629 other frame). If you don't, then the minibuffer is found in the frame
630 which is the value of the variable @code{default-minibuffer-frame}. Its
631 value should be a frame which does have a minibuffer.
633 @ignore Not yet in XEmacs
634 If you use a minibuffer-only frame, you might want that frame to raise
635 when you enter the minibuffer. If so, set the variable
636 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
639 @defvar default-minibuffer-frame
640 This variable specifies the frame to use for the minibuffer window, by
647 @cindex selected frame
649 At any time, one frame in XEmacs is the @dfn{selected frame}. The selected
650 window always resides on the selected frame. As the focus moves from
651 device to device, the selected frame on each device is remembered and
652 restored when the focus moves back to that device.
654 @defun selected-frame &optional device
655 This function returns the selected frame on @var{device}. If
656 @var{device} is not specified, the selected device will be used. If no
657 frames exist on the device, @code{nil} is returned.
660 The X server normally directs keyboard input to the X window that the
661 mouse is in. Some window managers use mouse clicks or keyboard events
662 to @dfn{shift the focus} to various X windows, overriding the normal
663 behavior of the server.
665 Lisp programs can switch frames ``temporarily'' by calling
666 the function @code{select-frame}. This does not override the window
667 manager; rather, it escapes from the window manager's control until
668 that control is somehow reasserted.
670 When using a text-only terminal, there is no window manager; therefore,
671 @code{select-frame} is the only way to switch frames, and the effect
672 lasts until overridden by a subsequent call to @code{select-frame}.
673 Only the selected terminal frame is actually displayed on the terminal.
674 Each terminal screen except for the initial one has a number, and the
675 number of the selected frame appears in the mode line after the word
676 @samp{XEmacs} (@pxref{Modeline Variables}).
678 @defun select-frame frame
679 This function selects frame @var{frame}, temporarily disregarding the
680 focus of the X server if any. The selection of @var{frame} lasts until
681 the next time the user does something to select a different frame, or
682 until the next time this function is called.
684 Note that @code{select-frame} does not actually cause the window-system
685 focus to be set to this frame, or the @code{select-frame-hook} or
686 @code{deselect-frame-hook} to be run, until the next time that XEmacs is
687 waiting for an event.
689 Also note that when the variable @code{focus-follows-mouse} is
690 non-@code{nil}, the frame selection is temporary and is reverted when
691 the current command terminates, much like the buffer selected by
692 @code{set-buffer}. In order to effect a permanent focus change use
696 @defun focus-frame frame
697 This function selects @var{frame} and gives it the window system focus.
698 The operation of @code{focus-frame} is not affected by the value of
699 @code{focus-follows-mouse}.
702 @defmac save-selected-frame forms@dots{}
703 This macro records the selected frame, executes @var{forms} in sequence,
704 then restores the earlier selected frame. The value returned is the
705 value of the last form.
708 @defmac with-selected-frame frame forms@dots{}
709 This macro records the selected frame, then selects @var{frame} and
710 executes @var{forms} in sequence. After the last form is finished, the
711 earlier selected frame is restored. The value returned is the value of
715 @ignore (FSF Emacs, continued from defun select-frame)
716 XEmacs cooperates with the X server and the window managers by arranging
717 to select frames according to what the server and window manager ask
718 for. It does so by generating a special kind of input event, called a
719 @dfn{focus} event. The command loop handles a focus event by calling
720 @code{handle-select-frame}. @xref{Focus Events}.
722 @deffn Command handle-switch-frame frame
723 This function handles a focus event by selecting frame @var{frame}.
725 Focus events normally do their job by invoking this command.
726 Don't call it for any other reason.
729 @defun redirect-frame-focus frame focus-frame
730 This function redirects focus from @var{frame} to @var{focus-frame}.
731 This means that @var{focus-frame} will receive subsequent keystrokes
732 intended for @var{frame}. After such an event, the value of
733 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
734 events specifying @var{frame} will instead select @var{focus-frame}.
736 If @var{focus-frame} is @code{nil}, that cancels any existing
737 redirection for @var{frame}, which therefore once again receives its own
740 One use of focus redirection is for frames that don't have minibuffers.
741 These frames use minibuffers on other frames. Activating a minibuffer
742 on another frame redirects focus to that frame. This puts the focus on
743 the minibuffer's frame, where it belongs, even though the mouse remains
744 in the frame that activated the minibuffer.
746 Selecting a frame can also change focus redirections. Selecting frame
747 @code{bar}, when @code{foo} had been selected, changes any redirections
748 pointing to @code{foo} so that they point to @code{bar} instead. This
749 allows focus redirection to work properly when the user switches from
750 one frame to another using @code{select-window}.
752 This means that a frame whose focus is redirected to itself is treated
753 differently from a frame whose focus is not redirected.
754 @code{select-frame} affects the former but not the latter.
756 The redirection lasts until @code{redirect-frame-focus} is called to
761 @node Visibility of Frames
762 @section Visibility of Frames
763 @cindex visible frame
764 @cindex invisible frame
765 @cindex iconified frame
766 @cindex frame visibility
768 An X window frame may be @dfn{visible}, @dfn{invisible}, or
769 @dfn{iconified}. If it is visible, you can see its contents. If it is
770 iconified, the frame's contents do not appear on the screen, but an icon
771 does. If the frame is invisible, it doesn't show on the screen, not
774 Visibility is meaningless for TTY frames, since only the selected
775 one is actually displayed in any case.
777 @deffn Command make-frame-visible &optional frame
778 This function makes frame @var{frame} visible. If you omit @var{frame},
779 it makes the selected frame visible.
782 @deffn Command make-frame-invisible &optional frame
783 This function makes frame @var{frame} invisible.
786 @deffn Command iconify-frame &optional frame
787 This function iconifies frame @var{frame}.
790 @deffn Command deiconify-frame &optional frame
791 This function de-iconifies frame @var{frame}. Under X, this is
792 equivalent to @code{make-frame-visible}.
795 @defun frame-visible-p frame
796 This returns whether @var{frame} is currently ``visible'' (actually in
797 use for display). A frame that is not visible is not updated, and, if
798 it works through a window system, may not show at all.
801 @defun frame-iconified-p frame
802 This returns whether @var{frame} is iconified. Not all window managers
803 use icons; some merely unmap the window, so this function is not the
804 inverse of @code{frame-visible-p}. It is possible for a frame to not
805 be visible and not be iconified either. However, if the frame is
806 iconified, it will not be visible. (Under FSF Emacs, the functionality
807 of this function is obtained through @code{frame-visible-p}.)
810 @defun frame-totally-visible-p frame
811 This returns whether @var{frame} is not obscured by any other X
812 windows. On TTY frames, this is the same as @code{frame-visible-p}.
815 @ignore @c Not in XEmacs.
816 The visibility status of a frame is also available as a frame
817 property. You can read or change it as such. @xref{X Frame
820 The user can iconify and deiconify frames with the window manager. This
821 happens below the level at which XEmacs can exert any control, but XEmacs
822 does provide events that you can use to keep track of such changes.
826 @node Raising and Lowering
827 @section Raising and Lowering Frames
829 The X Window System uses a desktop metaphor. Part of this metaphor is
830 the idea that windows are stacked in a notional third dimension
831 perpendicular to the screen surface, and thus ordered from ``highest''
832 to ``lowest''. Where two windows overlap, the one higher up covers the
833 one underneath. Even a window at the bottom of the stack can be seen if
834 no other window overlaps it.
836 @cindex raising a frame
837 @cindex lowering a frame
838 A window's place in this ordering is not fixed; in fact, users tend to
839 change the order frequently. @dfn{Raising} a window means moving it
840 ``up'', to the top of the stack. @dfn{Lowering} a window means moving
841 it to the bottom of the stack. This motion is in the notional third
842 dimension only, and does not change the position of the window on the
845 You can raise and lower XEmacs's X windows with these functions:
847 @deffn Command raise-frame &optional frame
848 This function raises frame @var{frame}.
851 @deffn Command lower-frame &optional frame
852 This function lowers frame @var{frame}.
855 You can also specify auto-raise (raising automatically when a frame is
856 selected) or auto-lower (lowering automatically when it is deselected).
857 Under X, most ICCCM-compliant window managers will have an option to do
858 this for you, but the following variables are provided in case you're
859 using a broken WM. (Under FSF Emacs, the same functionality is
860 provided through the @code{auto-raise} and @code{auto-lower}
863 @defvar auto-raise-frame
864 This variable's value is @code{t} if frames will be raised to the top
868 @ignore Not in XEmacs
869 @defopt minibuffer-auto-raise
870 If this is non-@code{nil}, activation of the minibuffer raises the frame
871 that the minibuffer window is in.
875 @defvar auto-lower-frame
876 This variable's value is @code{t} if frames will be lowered to the bottom
877 when no longer selected.
880 Auto-raising and auto-lowering is implemented through functions attached
881 to @code{select-frame-hook} and @code{deselect-frame-hook}
882 (@pxref{Frame Hooks}). Under normal circumstances, you should not call
883 these functions directly.
885 @defun default-select-frame-hook
886 This hook function implements the @code{auto-raise-frame} variable; it is
887 for use as the value of @code{select-frame-hook}.
890 @defun default-deselect-frame-hook
891 This hook function implements the @code{auto-lower-frame} variable; it is
892 for use as the value of @code{deselect-frame-hook}.
895 @node Frame Configurations
896 @section Frame Configurations
897 @cindex frame configuration
899 A @dfn{frame configuration} records the current arrangement of frames,
900 all their properties, and the window configuration of each one.
902 @defun current-frame-configuration
903 This function returns a frame configuration list that describes
904 the current arrangement of frames and their contents.
907 @defun set-frame-configuration configuration
908 This function restores the state of frames described in
913 @section Hooks for Customizing Frame Behavior
916 XEmacs provides many hooks that are called at various times during a
917 frame's lifetime. @xref{Hooks}.
919 @defvar create-frame-hook
920 This hook is called each time a frame is created. The functions are called
921 with one argument, the newly-created frame.
924 @defvar delete-frame-hook
925 This hook is called each time a frame is deleted. The functions are called
926 with one argument, the about-to-be-deleted frame.
929 @defvar select-frame-hook
930 This is a normal hook that is run just after a frame is selected. The
931 function @code{default-select-frame-hook}, which implements auto-raising
932 (@pxref{Raising and Lowering}), is normally attached to this hook.
934 Note that calling @code{select-frame} does not necessarily set the
935 focus: The actual window-system focus will not be changed until the next
936 time that XEmacs is waiting for an event, and even then, the window
937 manager may refuse the focus-change request.
940 @defvar deselect-frame-hook
941 This is a normal hook that is run just before a frame is deselected
942 (and another frame is selected). The function
943 @code{default-deselect-frame-hook}, which implements auto-lowering
944 (@pxref{Raising and Lowering}), is normally attached to this hook.
947 @defvar map-frame-hook
948 This hook is called each time a frame is mapped (i.e. made visible).
949 The functions are called with one argument, the newly mapped frame.
952 @defvar unmap-frame-hook
953 This hook is called each time a frame is unmapped (i.e. made invisible
954 or iconified). The functions are called with one argument, the
955 newly unmapped frame.