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. 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.
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.
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
28 This predicate returns @code{t} if @var{object} is a frame, and
33 * Creating Frames:: Creating additional frames.
34 * Frame Properties:: 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.
49 @xref{Display}, for related information.
52 @section Creating Frames
54 To create a new frame, call the function @code{make-frame}.
56 @defun make-frame &optional props 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 (yet).) @var{device} defaults to the selected device if omitted.
60 @xref{Consoles and Devices}.
62 The argument @var{props} is a property list (a list of alternating
63 keyword-value specifications) of properties for the new frame. (An alist
64 is accepted for backward compatibility but should not be passed in.) Any
65 properties not mentioned in @var{props} default according to the value
66 of the variable @code{default-frame-plist}. For X devices, properties
67 not specified in @code{default-frame-plist} default in turn from
68 @code{default-x-frame-plist} and, if not specified there, from the X
69 resources. For TTY devices, @code{default-tty-frame-plist} is consulted
70 as well as @code{default-frame-plist}.
72 The set of possible properties depends in principle on what kind of
73 window system XEmacs uses to display its frames. @xref{X Frame
74 Properties}, for documentation of individual properties you can specify
75 when creating an X window frame.
78 @node Frame Properties
79 @section Frame Properties
81 A frame has many properties that control its appearance and behavior.
82 Just what properties a frame has depends on which display mechanism it
85 Frame properties exist for the sake of window systems. A terminal frame
86 has few properties, mostly for compatibility's sake; only the height,
87 width and @code{buffer-predicate} properties really do something.
90 * Property Access:: How to change a frame's properties.
91 * Initial Properties:: Specifying frame properties when you make a frame.
92 * X Frame Properties:: List of frame properties.
93 * Size and Position:: Changing the size and position of a frame.
94 * Frame Name:: The name of a frame (as opposed to its title).
98 @subsection Access to Frame Properties
100 These functions let you read and change the properties of a frame.
102 @defun frame-properties &optional frame
103 This function returns a plist listing all the properties of @var{frame}
107 @defun frame-property frame property &optional default
108 This function returns @var{frame}'s value for the property
112 @defun set-frame-properties frame plist
113 This function alters the properties of frame @var{frame} based on the
114 elements of property list @var{plist}. If you don't mention a property
115 in @var{plist}, its value doesn't change.
118 @defun set-frame-property frame prop val
119 This function sets the property @var{prop} of frame @var{frame} to the
123 @node Initial Properties
124 @subsection Initial Frame Properties
126 You can specify the properties for the initial startup frame by setting
127 @code{initial-frame-plist} in your @file{.emacs} file.
129 @defvar initial-frame-plist
130 This variable's value is a plist of alternating property-value pairs
131 used when creating the initial X window frame.
133 XEmacs creates the initial frame before it reads your @file{~/.emacs}
134 file. After reading that file, XEmacs checks @code{initial-frame-plist},
135 and applies the property settings in the altered value to the already
136 created initial frame.
138 If these settings affect the frame geometry and appearance, you'll see
139 the frame appear with the wrong ones and then change to the specified
140 ones. If that bothers you, you can specify the same geometry and
141 appearance with X resources; those do take affect before the frame is
142 created. @xref{Resources X,, X Resources, xemacs, The XEmacs User's Manual}.
144 X resource settings typically apply to all frames. If you want to
145 specify some X resources solely for the sake of the initial frame, and
146 you don't want them to apply to subsequent frames, here's how to achieve
147 this: specify properties in @code{default-frame-plist} to override the X
148 resources for subsequent frames; then, to prevent these from affecting
149 the initial frame, specify the same properties in
150 @code{initial-frame-plist} with values that match the X resources.
153 If these properties specify a separate minibuffer-only frame via a
154 @code{minibuffer} property of @code{nil}, and you have not yet created
155 one, XEmacs creates one for you.
157 @defvar minibuffer-frame-plist
158 This variable's value is a plist of properties used when creating an
159 initial minibuffer-only frame---if such a frame is needed, according to
160 the properties for the main initial frame.
163 @defvar default-frame-plist
164 This is a plist specifying default values of frame properties for
165 subsequent XEmacs frames (not the initial ones).
168 See also @code{special-display-frame-plist}, in @ref{Choosing Window}.
170 If you use options that specify window appearance when you invoke XEmacs,
171 they take effect by adding elements to @code{default-frame-plist}. One
172 exception is @samp{-geometry}, which adds the specified position to
173 @code{initial-frame-plist} instead. @xref{Command Arguments,,, xemacs,
174 The XEmacs User's Manual}.
176 @node X Frame Properties
177 @subsection X Window Frame Properties
179 Just what properties a frame has depends on what display mechanism it
180 uses. Here is a table of the properties of an X window frame; of these,
181 @code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
182 provide meaningful information in non-X frames.
186 The name of the frame. Most window managers display the frame's name in
187 the frame's border, at the top of the frame. If you don't specify a
188 name, and you have more than one frame, XEmacs sets the frame name based
189 on the buffer displayed in the frame's selected window.
191 If you specify the frame name explicitly when you create the frame, the
192 name is also used (instead of the name of the XEmacs executable) when
193 looking up X resources for the frame.
196 The display on which to open this frame. It should be a string of the
197 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
198 @code{DISPLAY} environment variable.
201 The screen position of the left edge, in pixels, with respect to the
202 left edge of the screen. The value may be a positive number @var{pos},
203 or a list of the form @code{(+ @var{pos})} which permits specifying a
204 negative @var{pos} value.
206 A negative number @minus{}@var{pos}, or a list of the form @code{(-
207 @var{pos})}, actually specifies the position of the right edge of the
208 window with respect to the right edge of the screen. A positive value
209 of @var{pos} counts toward the left. If the property is a negative
210 integer @minus{}@var{pos} then @var{pos} is positive!
213 The screen position of the top edge, in pixels, with respect to the
214 top edge of the screen. The value may be a positive number @var{pos},
215 or a list of the form @code{(+ @var{pos})} which permits specifying a
216 negative @var{pos} value.
218 A negative number @minus{}@var{pos}, or a list of the form @code{(-
219 @var{pos})}, actually specifies the position of the bottom edge of the
220 window with respect to the bottom edge of the screen. A positive value
221 of @var{pos} counts toward the top. If the property is a negative
222 integer @minus{}@var{pos} then @var{pos} is positive!
225 The screen position of the left edge @emph{of the frame's icon}, in
226 pixels, counting from the left edge of the screen. This takes effect if
227 and when the frame is iconified.
230 The screen position of the top edge @emph{of the frame's icon}, in
231 pixels, counting from the top edge of the screen. This takes effect if
232 and when the frame is iconified.
235 Non-@code{nil} if the screen position of the frame was explicitly
236 requested by the user (for example, with the @samp{-geometry} option).
237 Nothing automatically makes this property non-@code{nil}; it is up to
238 Lisp programs that call @code{make-frame} to specify this property as
239 well as specifying the @code{left} and @code{top} properties.
242 The height of the frame contents, in characters. (To get the height in
243 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
246 The width of the frame contents, in characters. (To get the height in
247 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
250 The number of the X window for the frame.
253 Whether this frame has its own minibuffer. The value @code{t} means
254 yes, @code{nil} means no, @code{only} means this frame is just a
255 minibuffer. If the value is a minibuffer window (in some other frame),
256 the new frame uses that minibuffer. (Minibuffer-only and minibuffer-less
257 frames are not yet implemented in XEmacs.)
259 @item buffer-predicate
260 The buffer-predicate function for this frame. The function
261 @code{other-buffer} uses this predicate (from the selected frame) to
262 decide which buffers it should consider, if the predicate is not
263 @code{nil}. It calls the predicate with one arg, a buffer, once for
264 each buffer; if the predicate returns a non-@code{nil} value, it
265 considers that buffer.
267 @item scroll-bar-width
268 The width of the vertical scroll bar, in pixels.
270 @ignore Not in XEmacs
272 The type of icon to use for this frame when it is iconified. If the
273 value is a string, that specifies a file containing a bitmap to use.
274 Any other non-@code{nil} value specifies the default bitmap icon (a
275 picture of a gnu); @code{nil} specifies a text icon.
278 The name to use in the icon for this frame, when and if the icon
279 appears. If this is @code{nil}, the frame's title is used.
283 The color for the cursor that shows point.
286 The color for the border of the frame.
288 @ignore Not in XEmacs
290 The way to display the cursor. The legitimate values are @code{bar},
291 @code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
292 specifies an ordinary black box overlaying the character after point;
293 that is the default. The symbol @code{bar} specifies a vertical bar
294 between characters as the cursor. @code{(bar . @var{width})} specifies
295 a bar @var{width} pixels wide.
299 The width in pixels of the window border.
301 @item internal-border-width
302 The distance in pixels between text and border.
305 If non-@code{nil}, this frame's window is never split automatically.
307 @item inter-line-space
308 The space in pixels between adjacent lines of text. (Not currently
312 Whether the frame has a modeline.
315 @node Size and Position
316 @subsection Frame Size And Position
317 @cindex size of frame
319 @cindex display lines
320 @cindex display columns
321 @cindex resize redisplay
322 @cindex frame position
323 @cindex position of frame
325 You can read or change the size and position of a frame using the
326 frame properties @code{left}, @code{top}, @code{height}, and
327 @code{width}. Whatever geometry properties you don't specify are chosen
328 by the window manager in its usual fashion.
330 Here are some special features for working with sizes and positions:
332 @defun set-frame-position frame left top
333 This function sets the position of the top left corner of @var{frame} to
334 @var{left} and @var{top}. These arguments are measured in pixels, and
335 count from the top left corner of the screen. Negative property values
336 count up or rightward from the top left corner of the screen.
339 @defun frame-height &optional frame
340 @defunx frame-width &optional frame
341 These functions return the height and width of @var{frame}, measured in
342 lines and columns. If you don't supply @var{frame}, they use the selected
346 @defun frame-pixel-height &optional frame
347 @defunx frame-pixel-width &optional frame
348 These functions return the height and width of @var{frame}, measured in
349 pixels. If you don't supply @var{frame}, they use the selected frame.
352 @defun set-frame-size frame cols rows &optional pretend
353 This function sets the size of @var{frame}, measured in characters;
354 @var{cols} and @var{rows} specify the new width and height. (If
355 @var{pretend} is non-nil, it means that redisplay should act as if
356 the frame's size is @var{cols} by @var{rows}, but the actual size
357 of the frame should not be changed. You should not normally use
361 You can also use the functions @code{set-frame-height} and
362 @code{set-frame-width} to set the height and width individually.
363 The frame is the first argument and the size (in rows or columns)
364 is the second. (There is an optional third argument, @var{pretend},
365 which has the same purpose as the corresponding argument in
366 @code{set-frame-size}.)
368 @ignore @c Not in XEmacs
369 @defun x-parse-geometry geom
370 @cindex geometry specification
371 The function @code{x-parse-geometry} converts a standard X windows
372 geometry string to a plist that you can use as part of the argument to
375 The plist describes which properties were specified in @var{geom}, and
376 gives the values specified for them. Each element looks like
377 @code{(@var{property} . @var{value})}. The possible @var{property}
378 values are @code{left}, @code{top}, @code{width}, and @code{height}.
380 For the size properties, the value must be an integer. The position
381 property names @code{left} and @code{top} are not totally accurate,
382 because some values indicate the position of the right or bottom edges
383 instead. These are the @var{value} possibilities for the position
388 A positive integer relates the left edge or top edge of the window to
389 the left or top edge of the screen. A negative integer relates the
390 right or bottom edge of the window to the right or bottom edge of the
393 @item @code{(+ @var{position})}
394 This specifies the position of the left or top edge of the window
395 relative to the left or top edge of the screen. The integer
396 @var{position} may be positive or negative; a negative value specifies a
397 position outside the screen.
399 @item @code{(- @var{position})}
400 This specifies the position of the right or bottom edge of the window
401 relative to the right or bottom edge of the screen. The integer
402 @var{position} may be positive or negative; a negative value specifies a
403 position outside the screen.
409 (x-parse-geometry "35x70+0-0")
410 @result{} ((width . 35) (height . 70)
411 (left . 0) (top - 0))
417 @subsection The Name of a Frame (As Opposed to Its Title)
420 Under X, every frame has a name, which is not the same as the title of
421 the frame. A frame's name is used to look up its resources and does
422 not normally change over the lifetime of a frame. It is perfectly
423 allowable, and quite common, for multiple frames to have the same
426 @defun frame-name &optional frame
427 This function returns the name of @var{frame}, which defaults to the
428 selected frame if not specified. The name of a frame can also be
429 obtained from the frame's properties. @xref{Frame Properties}.
432 @defvar default-frame-name
433 This variable holds the default name to assign to newly-created frames.
434 This can be overridden by arguments to @code{make-frame}. This
439 @section Frame Titles
441 Every frame has a title; most window managers display the frame title at
442 the top of the frame. You can specify an explicit title with the
443 @code{name} frame property. But normally you don't specify this
444 explicitly, and XEmacs computes the title automatically.
446 XEmacs computes the frame title based on a template stored in the
447 variable @code{frame-title-format}.
449 @defvar frame-title-format
450 This variable specifies how to compute a title for a frame
451 when you have not explicitly specified one.
453 The variable's value is actually a modeline construct, just like
454 @code{modeline-format}. @xref{Modeline Data}.
457 @defvar frame-icon-title-format
458 This variable specifies how to compute the title for an iconified frame,
459 when you have not explicitly specified the frame title. This title
460 appears in the icon itself.
463 @defun x-set-frame-icon-pixmap frame pixmap &optional mask
464 This function sets the icon of the given frame to the given image
465 instance, which should be an image instance object (as returned by
466 @code{make-image-instance}), a glyph object (as returned by
467 @code{make-glyph}), or @code{nil}. If a glyph object is given, the
468 glyph will be instantiated on the frame to produce an image instance
471 If the given image instance has a mask, that will be used as the icon mask;
472 however, not all window managers support this.
474 The window manager is also not required to support color pixmaps,
475 only bitmaps (one plane deep).
477 If the image instance does not have a mask, then the optional
478 third argument may be the image instance to use as the mask (it must be
483 @node Deleting Frames
484 @section Deleting Frames
485 @cindex deletion of frames
487 Frames remain potentially visible until you explicitly @dfn{delete}
488 them. A deleted frame cannot appear on the screen, but continues to
489 exist as a Lisp object until there are no references to it.
491 @deffn Command delete-frame &optional frame
492 This function deletes the frame @var{frame}. By default, @var{frame} is
496 @defun frame-live-p frame
497 The function @code{frame-live-p} returns non-@code{nil} if the frame
498 @var{frame} has not been deleted.
501 @ignore Not in XEmacs currently
502 Some window managers provide a command to delete a window. These work
503 by sending a special message to the program that operates the window.
504 When XEmacs gets one of these commands, it generates a
505 @code{delete-frame} event, whose normal definition is a command that
506 calls the function @code{delete-frame}. @xref{Misc Events}.
509 @node Finding All Frames
510 @section Finding All Frames
513 The function @code{frame-list} returns a list of all the frames that
514 have not been deleted. It is analogous to @code{buffer-list} for
515 buffers. The list that you get is newly created, so modifying the list
516 doesn't have any effect on the internals of XEmacs.
519 @defun device-frame-list &optional device
520 This function returns a list of all frames on @var{device}. If
521 @var{device} is @code{nil}, the selected device will be used.
524 @defun visible-frame-list &optional device
525 This function returns a list of just the currently visible frames.
526 If @var{device} is specified only frames on that device will be returned.
527 @xref{Visibility of Frames}. (TTY frames always count as
528 ``visible'', even though only the selected one is actually displayed.)
531 @defun next-frame &optional frame minibuf
532 The function @code{next-frame} lets you cycle conveniently through all
533 the frames from an arbitrary starting point. It returns the ``next''
534 frame after @var{frame} in the cycle. If @var{frame} is omitted or
535 @code{nil}, it defaults to the selected frame.
537 The second argument, @var{minibuf}, says which frames to consider:
541 Exclude minibuffer-only frames.
543 Consider all visible frames.
545 Consider all visible or iconified frames.
547 Consider only the frames using that particular window as their
549 @item the symbol @code{visible}
550 Include all visible frames.
552 Include all visible and iconified frames.
558 @defun previous-frame &optional frame minibuf
559 Like @code{next-frame}, but cycles through all frames in the opposite
563 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
566 @node Frames and Windows
567 @section Frames and Windows
569 Each window is part of one and only one frame; you can get the frame
570 with @code{window-frame}.
572 @defun frame-root-window &optional frame
573 This returns the root window of frame @var{frame}. @var{frame}
574 defaults to the selected frame if not specified.
577 @defun window-frame &optional window
578 This function returns the frame that @var{window} is on. @var{window}
579 defaults to the selected window if omitted.
582 All the non-minibuffer windows in a frame are arranged in a cyclic
583 order. The order runs from the frame's top window, which is at the
584 upper left corner, down and to the right, until it reaches the window at
585 the lower right corner (always the minibuffer window, if the frame has
586 one), and then it moves back to the top.
588 @defun frame-top-window frame
589 This returns the topmost, leftmost window of frame @var{frame}.
592 At any time, exactly one window on any frame is @dfn{selected within the
593 frame}. The significance of this designation is that selecting the
594 frame also selects this window. You can get the frame's current
595 selected window with @code{frame-selected-window}.
597 @defun frame-selected-window &optional frame
598 This function returns the window on @var{frame} that is selected within
599 @var{frame}. @var{frame} defaults to the selected frame if not
603 Conversely, selecting a window for XEmacs with @code{select-window} also
604 makes that window selected within its frame. @xref{Selecting Windows}.
606 Another function that (usually) returns one of the windows in a frame is
607 @code{minibuffer-window}. @xref{Minibuffer Misc}.
609 @node Minibuffers and Frames
610 @section Minibuffers and Frames
612 Normally, each frame has its own minibuffer window at the bottom, which
613 is used whenever that frame is selected. If the frame has a minibuffer,
614 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
616 However, you can also create a frame with no minibuffer. Such a frame
617 must use the minibuffer window of some other frame. When you create the
618 frame, you can specify explicitly the minibuffer window to use (in some
619 other frame). If you don't, then the minibuffer is found in the frame
620 which is the value of the variable @code{default-minibuffer-frame}. Its
621 value should be a frame which does have a minibuffer.
623 @ignore Not yet in XEmacs
624 If you use a minibuffer-only frame, you might want that frame to raise
625 when you enter the minibuffer. If so, set the variable
626 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
629 @defvar default-minibuffer-frame
630 This variable specifies the frame to use for the minibuffer window, by
637 @cindex selected frame
639 At any time, one frame in XEmacs is the @dfn{selected frame}. The selected
640 window always resides on the selected frame. As the focus moves from
641 device to device, the selected frame on each device is remembered and
642 restored when the focus moves back to that device.
644 @defun selected-frame &optional device
645 This function returns the selected frame on @var{device}. If
646 @var{device} is not specified, the selected device will be used. If no
647 frames exist on the device, @code{nil} is returned.
650 The X server normally directs keyboard input to the X window that the
651 mouse is in. Some window managers use mouse clicks or keyboard events
652 to @dfn{shift the focus} to various X windows, overriding the normal
653 behavior of the server.
655 Lisp programs can switch frames ``temporarily'' by calling
656 the function @code{select-frame}. This does not override the window
657 manager; rather, it escapes from the window manager's control until
658 that control is somehow reasserted.
660 When using a text-only terminal, there is no window manager; therefore,
661 @code{select-frame} is the only way to switch frames, and the effect
662 lasts until overridden by a subsequent call to @code{select-frame}.
663 Only the selected terminal frame is actually displayed on the terminal.
664 Each terminal screen except for the initial one has a number, and the
665 number of the selected frame appears in the mode line after the word
666 @samp{XEmacs} (@pxref{Modeline Variables}).
668 @defun select-frame frame
669 This function selects frame @var{frame}, temporarily disregarding the
670 focus of the X server if any. The selection of @var{frame} lasts until
671 the next time the user does something to select a different frame, or
672 until the next time this function is called.
674 Note that @code{select-frame} does not actually cause the window-system
675 focus to be set to this frame, or the @code{select-frame-hook} or
676 @code{deselect-frame-hook} to be run, until the next time that XEmacs is
677 waiting for an event.
679 Also note that when the variable @code{focus-follows-mouse} is
680 non-@code{nil}, the frame selection is temporary and is reverted when
681 the current command terminates, much like the buffer selected by
682 @code{set-buffer}. In order to effect a permanent focus change use
686 @defun focus-frame frame
687 This function selects @var{frame} and gives it the window system focus.
688 The operation of @code{focus-frame} is not affected by the value of
689 @code{focus-follows-mouse}.
692 @defmac save-selected-frame forms@dots{}
693 This macro records the selected frame, executes @var{forms} in sequence,
694 then restores the earlier selected frame. The value returned is the
695 value of the last form.
698 @defmac with-selected-frame frame forms@dots{}
699 This macro records the selected frame, then selects @var{frame} and
700 executes @var{forms} in sequence. After the last form is finished, the
701 earlier selected frame is restored. The value returned is the value of
705 @ignore (FSF Emacs, continued from defun select-frame)
706 XEmacs cooperates with the X server and the window managers by arranging
707 to select frames according to what the server and window manager ask
708 for. It does so by generating a special kind of input event, called a
709 @dfn{focus} event. The command loop handles a focus event by calling
710 @code{handle-select-frame}. @xref{Focus Events}.
712 @deffn Command handle-switch-frame frame
713 This function handles a focus event by selecting frame @var{frame}.
715 Focus events normally do their job by invoking this command.
716 Don't call it for any other reason.
719 @defun redirect-frame-focus frame focus-frame
720 This function redirects focus from @var{frame} to @var{focus-frame}.
721 This means that @var{focus-frame} will receive subsequent keystrokes
722 intended for @var{frame}. After such an event, the value of
723 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
724 events specifying @var{frame} will instead select @var{focus-frame}.
726 If @var{focus-frame} is @code{nil}, that cancels any existing
727 redirection for @var{frame}, which therefore once again receives its own
730 One use of focus redirection is for frames that don't have minibuffers.
731 These frames use minibuffers on other frames. Activating a minibuffer
732 on another frame redirects focus to that frame. This puts the focus on
733 the minibuffer's frame, where it belongs, even though the mouse remains
734 in the frame that activated the minibuffer.
736 Selecting a frame can also change focus redirections. Selecting frame
737 @code{bar}, when @code{foo} had been selected, changes any redirections
738 pointing to @code{foo} so that they point to @code{bar} instead. This
739 allows focus redirection to work properly when the user switches from
740 one frame to another using @code{select-window}.
742 This means that a frame whose focus is redirected to itself is treated
743 differently from a frame whose focus is not redirected.
744 @code{select-frame} affects the former but not the latter.
746 The redirection lasts until @code{redirect-frame-focus} is called to
751 @node Visibility of Frames
752 @section Visibility of Frames
753 @cindex visible frame
754 @cindex invisible frame
755 @cindex iconified frame
756 @cindex frame visibility
758 An X window frame may be @dfn{visible}, @dfn{invisible}, or
759 @dfn{iconified}. If it is visible, you can see its contents. If it is
760 iconified, the frame's contents do not appear on the screen, but an icon
761 does. If the frame is invisible, it doesn't show on the screen, not
764 Visibility is meaningless for TTY frames, since only the selected
765 one is actually displayed in any case.
767 @deffn Command make-frame-visible &optional frame
768 This function makes frame @var{frame} visible. If you omit @var{frame},
769 it makes the selected frame visible.
772 @deffn Command make-frame-invisible &optional frame
773 This function makes frame @var{frame} invisible.
776 @deffn Command iconify-frame &optional frame
777 This function iconifies frame @var{frame}.
780 @deffn Command deiconify-frame &optional frame
781 This function de-iconifies frame @var{frame}. Under X, this is
782 equivalent to @code{make-frame-visible}.
785 @defun frame-visible-p frame
786 This returns whether @var{frame} is currently ``visible'' (actually in
787 use for display). A frame that is not visible is not updated, and, if
788 it works through a window system, may not show at all.
791 @defun frame-iconified-p frame
792 This returns whether @var{frame} is iconified. Not all window managers
793 use icons; some merely unmap the window, so this function is not the
794 inverse of @code{frame-visible-p}. It is possible for a frame to not
795 be visible and not be iconified either. However, if the frame is
796 iconified, it will not be visible. (Under FSF Emacs, the functionality
797 of this function is obtained through @code{frame-visible-p}.)
800 @defun frame-totally-visible-p frame
801 This returns whether @var{frame} is not obscured by any other X
802 windows. On TTY frames, this is the same as @code{frame-visible-p}.
805 @ignore @c Not in XEmacs.
806 The visibility status of a frame is also available as a frame
807 property. You can read or change it as such. @xref{X Frame
810 The user can iconify and deiconify frames with the window manager. This
811 happens below the level at which XEmacs can exert any control, but XEmacs
812 does provide events that you can use to keep track of such changes.
816 @node Raising and Lowering
817 @section Raising and Lowering Frames
819 The X Window System uses a desktop metaphor. Part of this metaphor is
820 the idea that windows are stacked in a notional third dimension
821 perpendicular to the screen surface, and thus ordered from ``highest''
822 to ``lowest''. Where two windows overlap, the one higher up covers the
823 one underneath. Even a window at the bottom of the stack can be seen if
824 no other window overlaps it.
826 @cindex raising a frame
827 @cindex lowering a frame
828 A window's place in this ordering is not fixed; in fact, users tend to
829 change the order frequently. @dfn{Raising} a window means moving it
830 ``up'', to the top of the stack. @dfn{Lowering} a window means moving
831 it to the bottom of the stack. This motion is in the notional third
832 dimension only, and does not change the position of the window on the
835 You can raise and lower XEmacs's X windows with these functions:
837 @deffn Command raise-frame &optional frame
838 This function raises frame @var{frame}.
841 @deffn Command lower-frame &optional frame
842 This function lowers frame @var{frame}.
845 You can also specify auto-raise (raising automatically when a frame is
846 selected) or auto-lower (lowering automatically when it is deselected).
847 Under X, most ICCCM-compliant window managers will have an option to do
848 this for you, but the following variables are provided in case you're
849 using a broken WM. (Under FSF Emacs, the same functionality is
850 provided through the @code{auto-raise} and @code{auto-lower}
853 @defvar auto-raise-frame
854 This variable's value is @code{t} if frames will be raised to the top
858 @ignore Not in XEmacs
859 @defopt minibuffer-auto-raise
860 If this is non-@code{nil}, activation of the minibuffer raises the frame
861 that the minibuffer window is in.
865 @defvar auto-lower-frame
866 This variable's value is @code{t} if frames will be lowered to the bottom
867 when no longer selected.
870 Auto-raising and auto-lowering is implemented through functions attached
871 to @code{select-frame-hook} and @code{deselect-frame-hook}
872 (@pxref{Frame Hooks}). Under normal circumstances, you should not call
873 these functions directly.
875 @defun default-select-frame-hook
876 This hook function implements the @code{auto-raise-frame} variable; it is
877 for use as the value of @code{select-frame-hook}.
880 @defun default-deselect-frame-hook
881 This hook function implements the @code{auto-lower-frame} variable; it is
882 for use as the value of @code{deselect-frame-hook}.
885 @node Frame Configurations
886 @section Frame Configurations
887 @cindex frame configuration
889 A @dfn{frame configuration} records the current arrangement of frames,
890 all their properties, and the window configuration of each one.
892 @defun current-frame-configuration
893 This function returns a frame configuration list that describes
894 the current arrangement of frames and their contents.
897 @defun set-frame-configuration configuration
898 This function restores the state of frames described in
903 @section Hooks for Customizing Frame Behavior
906 XEmacs provides many hooks that are called at various times during a
907 frame's lifetime. @xref{Hooks}.
909 @defvar create-frame-hook
910 This hook is called each time a frame is created. The functions are called
911 with one argument, the newly-created frame.
914 @defvar delete-frame-hook
915 This hook is called each time a frame is deleted. The functions are called
916 with one argument, the about-to-be-deleted frame.
919 @defvar select-frame-hook
920 This is a normal hook that is run just after a frame is selected. The
921 function @code{default-select-frame-hook}, which implements auto-raising
922 (@pxref{Raising and Lowering}), is normally attached to this hook.
924 Note that calling @code{select-frame} does not necessarily set the
925 focus: The actual window-system focus will not be changed until the next
926 time that XEmacs is waiting for an event, and even then, the window
927 manager may refuse the focus-change request.
930 @defvar deselect-frame-hook
931 This is a normal hook that is run just before a frame is deselected
932 (and another frame is selected). The function
933 @code{default-deselect-frame-hook}, which implements auto-lowering
934 (@pxref{Raising and Lowering}), is normally attached to this hook.
937 @defvar map-frame-hook
938 This hook is called each time a frame is mapped (i.e. made visible).
939 The functions are called with one argument, the newly mapped frame.
942 @defvar unmap-frame-hook
943 This hook is called each time a frame is unmapped (i.e. made invisible
944 or iconified). The functions are called with one argument, the
945 newly unmapped frame.