Mercurial > hg > xemacs-beta

comparison man/lispref/frames.texi @ 428:3ecd8885ac67 r21-2-22

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-22
author cvs
date Mon, 13 Aug 2007 11:28:15 +0200
parents
children abe6d1db359e
comparison
equal deleted inserted replaced
427:0a0253eac470 428:3ecd8885ac67
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 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.
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 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.
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 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}.
61
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}.
71
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.
76 @end defun
77
78 @node Frame Properties
79 @section Frame Properties
80
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
83 uses.
84
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.
88
89 @menu
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).
95 @end menu
96
97 @node Property Access
98 @subsection Access to Frame Properties
99
100 These functions let you read and change the properties of a frame.
101
102 @defun frame-properties &optional frame
103 This function returns a plist listing all the properties of @var{frame}
104 and their values.
105 @end defun
106
107 @defun frame-property frame property &optional default
108 This function returns @var{frame}'s value for the property
109 @var{property}.
110 @end defun
111
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.
116 @end defun
117
118 @defun set-frame-property frame prop val
119 This function sets the property @var{prop} of frame @var{frame} to the
120 value @var{val}.
121 @end defun
122
123 @node Initial Properties
124 @subsection Initial Frame Properties
125
126 You can specify the properties for the initial startup frame by setting
127 @code{initial-frame-plist} in your @file{.emacs} file.
128
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.
132
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.
137
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}.
143
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.
151 @end defvar
152
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.
156
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.
161 @end defvar
162
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).
166 @end defvar
167
168 See also @code{special-display-frame-plist}, in @ref{Choosing Window}.
169
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}.
175
176 @node X Frame Properties
177 @subsection X Window Frame Properties
178
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.
183
184 @table @code
185 @item name
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.
190
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.
194
195 @item display
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.
199
200 @item left
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.
205
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!
211
212 @item top
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.
217
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!
223
224 @item icon-left
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.
228
229 @item icon-top
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.
233
234 @item user-position
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.
240
241 @item height
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}.)
244
245 @item width
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}.)
248
249 @item window-id
250 The number of the X window for the frame.
251
252 @item minibuffer
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.)
258
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.
266
267 @item scroll-bar-width
268 The width of the vertical scroll bar, in pixels.
269
270 @ignore Not in XEmacs
271 @item icon-type
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.
276
277 @item icon-name
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.
280 @end ignore
281
282 @item cursor-color
283 The color for the cursor that shows point.
284
285 @item border-color
286 The color for the border of the frame.
287
288 @ignore Not in XEmacs
289 @item cursor-type
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.
296 @end ignore
297
298 @item border-width
299 The width in pixels of the window border.
300
301 @item internal-border-width
302 The distance in pixels between text and border.
303
304 @item unsplittable
305 If non-@code{nil}, this frame's window is never split automatically.
306
307 @item inter-line-space
308 The space in pixels between adjacent lines of text. (Not currently
309 implemented.)
310
311 @item modeline
312 Whether the frame has a modeline.
313 @end table
314
315 @node Size and Position
316 @subsection Frame Size And Position
317 @cindex size of frame
318 @cindex frame size
319 @cindex display lines
320 @cindex display columns
321 @cindex resize redisplay
322 @cindex frame position
323 @cindex position of frame
324
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.
329
330 Here are some special features for working with sizes and positions:
331
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.
337 @end defun
338
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
343 frame.
344 @end defun
345
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.
350 @end defun
351
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
358 this option.)
359 @end defun
360
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}.)
367
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
373 @code{make-frame}.
374
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}.
379
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
384 properties:
385
386 @table @asis
387 @item an integer
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
391 screen.
392
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.
398
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.
404 @end table
405
406 Here is an example:
407
408 @example
409 (x-parse-geometry "35x70+0-0")
410 @result{} ((width . 35) (height . 70)
411 (left . 0) (top - 0))
412 @end example
413 @end defun
414 @end ignore
415
416 @node Frame Name
417 @subsection The Name of a Frame (As Opposed to Its Title)
418 @cindex frame name
419
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
424 name.
425
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}.
430 @end defun
431
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
435 must be a string.
436 @end defvar
437
438 @node Frame Titles
439 @section Frame Titles
440
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.
445
446 XEmacs computes the frame title based on a template stored in the
447 variable @code{frame-title-format}.
448
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.
452
453 The variable's value is actually a modeline construct, just like
454 @code{modeline-format}. @xref{Modeline Data}.
455 @end defvar
456
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.
461 @end defvar
462
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
469 object.
470
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.
473
474 The window manager is also not required to support color pixmaps,
475 only bitmaps (one plane deep).
476
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
479 one plane deep).
480 @xref{Glyphs}.
481 @end defun
482
483 @node Deleting Frames
484 @section Deleting Frames
485 @cindex deletion of frames
486
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.
490
491 @deffn Command delete-frame &optional frame
492 This function deletes the frame @var{frame}. By default, @var{frame} is
493 the selected frame.
494 @end deffn
495
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.
499 @end defun
500
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}.
507 @end ignore
508
509 @node Finding All Frames
510 @section Finding All Frames
511
512 @defun frame-list
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.
517 @end defun
518
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.
522 @end defun
523
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.)
529 @end defun
530
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.
536
537 The second argument, @var{minibuf}, says which frames to consider:
538
539 @table @asis
540 @item @code{nil}
541 Exclude minibuffer-only frames.
542 @item @code{visible}
543 Consider all visible frames.
544 @item 0
545 Consider all visible or iconified frames.
546 @item a window
547 Consider only the frames using that particular window as their
548 minibuffer.
549 @item the symbol @code{visible}
550 Include all visible frames.
551 @item @code{0}
552 Include all visible and iconified frames.
553 @item anything else
554 Consider all frames.
555 @end table
556 @end defun
557
558 @defun previous-frame &optional frame minibuf
559 Like @code{next-frame}, but cycles through all frames in the opposite
560 direction.
561 @end defun
562
563 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
564 Window Ordering}.
565
566 @node Frames and Windows
567 @section Frames and Windows
568
569 Each window is part of one and only one frame; you can get the frame
570 with @code{window-frame}.
571
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.
575 @end defun
576
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.
580 @end defun
581
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.
587
588 @defun frame-top-window frame
589 This returns the topmost, leftmost window of frame @var{frame}.
590 @end defun
591
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}.
596
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
600 specified.
601 @end defun
602
603 Conversely, selecting a window for XEmacs with @code{select-window} also
604 makes that window selected within its frame. @xref{Selecting Windows}.
605
606 Another function that (usually) returns one of the windows in a frame is
607 @code{minibuffer-window}. @xref{Minibuffer Misc}.
608
609 @node Minibuffers and Frames
610 @section Minibuffers and Frames
611
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}).
615
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.
622
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}.
627 @end ignore
628
629 @defvar default-minibuffer-frame
630 This variable specifies the frame to use for the minibuffer window, by
631 default.
632 @end defvar
633
634 @node Input Focus
635 @section Input Focus
636 @cindex input focus
637 @cindex selected frame
638
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.
643
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.
648 @end defun
649
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.
654
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.
659
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}).
667
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.
673
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.
678
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
683 @code{focus-frame}.
684 @end defun
685
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}.
690 @end defun
691
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.
696 @end defmac
697
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
702 the last form.
703 @end defmac
704
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}.
711
712 @deffn Command handle-switch-frame frame
713 This function handles a focus event by selecting frame @var{frame}.
714
715 Focus events normally do their job by invoking this command.
716 Don't call it for any other reason.
717 @end deffn
718
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}.
725
726 If @var{focus-frame} is @code{nil}, that cancels any existing
727 redirection for @var{frame}, which therefore once again receives its own
728 events.
729
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.
735
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}.
741
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.
745
746 The redirection lasts until @code{redirect-frame-focus} is called to
747 change it.
748 @end defun
749 @end ignore
750
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
757
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
762 even as an icon.
763
764 Visibility is meaningless for TTY frames, since only the selected
765 one is actually displayed in any case.
766
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.
770 @end deffn
771
772 @deffn Command make-frame-invisible &optional frame
773 This function makes frame @var{frame} invisible.
774 @end deffn
775
776 @deffn Command iconify-frame &optional frame
777 This function iconifies frame @var{frame}.
778 @end deffn
779
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}.
783 @end deffn
784
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.
789 @end defun
790
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}.)
798 @end defun
799
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}.
803 @end defun
804
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
808 Properties}.
809
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.
813 @xref{Misc Events}.
814 @end ignore
815
816 @node Raising and Lowering
817 @section Raising and Lowering Frames
818
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.
825
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
833 screen.
834
835 You can raise and lower XEmacs's X windows with these functions:
836
837 @deffn Command raise-frame &optional frame
838 This function raises frame @var{frame}.
839 @end deffn
840
841 @deffn Command lower-frame &optional frame
842 This function lowers frame @var{frame}.
843 @end deffn
844
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}
851 frame properties.)
852
853 @defvar auto-raise-frame
854 This variable's value is @code{t} if frames will be raised to the top
855 when selected.
856 @end defvar
857
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.
862 @end defopt
863 @end ignore
864
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.
868 @end defvar
869
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.
874
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}.
878 @end defun
879
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}.
883 @end defun
884
885 @node Frame Configurations
886 @section Frame Configurations
887 @cindex frame configuration
888
889 A @dfn{frame configuration} records the current arrangement of frames,
890 all their properties, and the window configuration of each one.
891
892 @defun current-frame-configuration
893 This function returns a frame configuration list that describes
894 the current arrangement of frames and their contents.
895 @end defun
896
897 @defun set-frame-configuration configuration
898 This function restores the state of frames described in
899 @var{configuration}.
900 @end defun
901
902 @node Frame Hooks
903 @section Hooks for Customizing Frame Behavior
904 @cindex frame hooks
905
906 XEmacs provides many hooks that are called at various times during a
907 frame's lifetime. @xref{Hooks}.
908
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.
912 @end defvar
913
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.
917 @end defvar
918
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.
923
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.
928 @end defvar
929
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.
935 @end defvar
936
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.
940 @end defvar
941
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.
946 @end defvar