|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
444
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
428
|
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
|
|
442
|
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.
|
|
|
18
|
|
|
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
|
|
|
24 XEmacs version 21.2.)
|
|
428
|
25
|
|
|
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.
|
|
|
31
|
|
|
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
|
|
|
35 own X window.
|
|
|
36
|
|
|
37 @defun framep object
|
|
|
38 This predicate returns @code{t} if @var{object} is a frame, and
|
|
|
39 @code{nil} otherwise.
|
|
|
40 @end defun
|
|
|
41
|
|
|
42 @menu
|
|
|
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.
|
|
|
57 @end menu
|
|
|
58
|
|
|
59 @xref{Display}, for related information.
|
|
|
60
|
|
|
61 @node Creating Frames
|
|
|
62 @section Creating Frames
|
|
|
63
|
|
|
64 To create a new frame, call the function @code{make-frame}.
|
|
|
65
|
|
444
|
66 @deffn Command make-frame &optional props device
|
|
428
|
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}.
|
|
|
71
|
|
|
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}.
|
|
|
81
|
|
|
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.
|
|
444
|
86 @end deffn
|
|
428
|
87
|
|
|
88 @node Frame Properties
|
|
|
89 @section Frame Properties
|
|
|
90
|
|
|
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
|
|
|
93 uses.
|
|
|
94
|
|
|
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.
|
|
|
98
|
|
|
99 @menu
|
|
|
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).
|
|
|
105 @end menu
|
|
|
106
|
|
|
107 @node Property Access
|
|
|
108 @subsection Access to Frame Properties
|
|
|
109
|
|
|
110 These functions let you read and change the properties of a frame.
|
|
|
111
|
|
|
112 @defun frame-properties &optional frame
|
|
|
113 This function returns a plist listing all the properties of @var{frame}
|
|
|
114 and their values.
|
|
|
115 @end defun
|
|
|
116
|
|
|
117 @defun frame-property frame property &optional default
|
|
|
118 This function returns @var{frame}'s value for the property
|
|
444
|
119 @var{property}, or @var{default} if there is no such property.
|
|
428
|
120 @end defun
|
|
|
121
|
|
|
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.
|
|
|
126 @end defun
|
|
|
127
|
|
444
|
128 @defun set-frame-property frame property value
|
|
|
129 This function sets the property @var{property} of frame @var{frame} to the
|
|
|
130 value @var{value}.
|
|
428
|
131 @end defun
|
|
|
132
|
|
|
133 @node Initial Properties
|
|
|
134 @subsection Initial Frame Properties
|
|
|
135
|
|
|
136 You can specify the properties for the initial startup frame by setting
|
|
|
137 @code{initial-frame-plist} in your @file{.emacs} file.
|
|
|
138
|
|
|
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.
|
|
|
142
|
|
|
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.
|
|
|
147
|
|
|
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}.
|
|
|
153
|
|
|
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.
|
|
|
161 @end defvar
|
|
|
162
|
|
|
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.
|
|
|
166
|
|
|
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.
|
|
|
171 @end defvar
|
|
|
172
|
|
|
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).
|
|
|
176 @end defvar
|
|
|
177
|
|
|
178 See also @code{special-display-frame-plist}, in @ref{Choosing Window}.
|
|
|
179
|
|
|
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}.
|
|
|
185
|
|
|
186 @node X Frame Properties
|
|
|
187 @subsection X Window Frame Properties
|
|
|
188
|
|
|
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.
|
|
|
193
|
|
|
194 @table @code
|
|
|
195 @item name
|
|
|
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.
|
|
|
200
|
|
|
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.
|
|
|
204
|
|
|
205 @item display
|
|
|
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.
|
|
|
209
|
|
|
210 @item left
|
|
|
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.
|
|
|
215
|
|
|
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!
|
|
|
221
|
|
|
222 @item top
|
|
|
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.
|
|
|
227
|
|
|
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!
|
|
|
233
|
|
|
234 @item icon-left
|
|
|
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.
|
|
|
238
|
|
|
239 @item icon-top
|
|
|
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.
|
|
|
243
|
|
|
244 @item user-position
|
|
|
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.
|
|
|
250
|
|
|
251 @item height
|
|
|
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}.)
|
|
|
254
|
|
|
255 @item width
|
|
|
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}.)
|
|
|
258
|
|
|
259 @item window-id
|
|
|
260 The number of the X window for the frame.
|
|
|
261
|
|
|
262 @item minibuffer
|
|
|
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.)
|
|
|
268
|
|
|
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.
|
|
|
276
|
|
|
277 @item scroll-bar-width
|
|
|
278 The width of the vertical scroll bar, in pixels.
|
|
|
279
|
|
|
280 @ignore Not in XEmacs
|
|
|
281 @item icon-type
|
|
|
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.
|
|
|
286
|
|
|
287 @item icon-name
|
|
|
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.
|
|
|
290 @end ignore
|
|
|
291
|
|
|
292 @item cursor-color
|
|
|
293 The color for the cursor that shows point.
|
|
|
294
|
|
|
295 @item border-color
|
|
|
296 The color for the border of the frame.
|
|
|
297
|
|
|
298 @ignore Not in XEmacs
|
|
|
299 @item cursor-type
|
|
|
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.
|
|
|
306 @end ignore
|
|
|
307
|
|
|
308 @item border-width
|
|
|
309 The width in pixels of the window border.
|
|
|
310
|
|
|
311 @item internal-border-width
|
|
|
312 The distance in pixels between text and border.
|
|
|
313
|
|
|
314 @item unsplittable
|
|
|
315 If non-@code{nil}, this frame's window is never split automatically.
|
|
|
316
|
|
|
317 @item inter-line-space
|
|
|
318 The space in pixels between adjacent lines of text. (Not currently
|
|
|
319 implemented.)
|
|
|
320
|
|
|
321 @item modeline
|
|
|
322 Whether the frame has a modeline.
|
|
|
323 @end table
|
|
|
324
|
|
|
325 @node Size and Position
|
|
|
326 @subsection Frame Size And Position
|
|
|
327 @cindex size of frame
|
|
|
328 @cindex frame size
|
|
|
329 @cindex display lines
|
|
|
330 @cindex display columns
|
|
|
331 @cindex resize redisplay
|
|
|
332 @cindex frame position
|
|
|
333 @cindex position of frame
|
|
|
334
|
|
|
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.
|
|
|
339
|
|
|
340 Here are some special features for working with sizes and positions:
|
|
|
341
|
|
|
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.
|
|
|
347 @end defun
|
|
|
348
|
|
|
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
|
|
|
353 frame.
|
|
|
354 @end defun
|
|
|
355
|
|
|
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.
|
|
|
360 @end defun
|
|
|
361
|
|
|
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
|
|
444
|
365 @var{pretend} is non-@code{nil}, it means that redisplay should act as if
|
|
428
|
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
|
|
|
368 this option.)
|
|
|
369 @end defun
|
|
|
370
|
|
|
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}.)
|
|
|
377
|
|
|
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
|
|
|
383 @code{make-frame}.
|
|
|
384
|
|
|
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}.
|
|
|
389
|
|
|
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
|
|
|
394 properties:
|
|
|
395
|
|
|
396 @table @asis
|
|
|
397 @item an integer
|
|
|
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
|
|
|
401 screen.
|
|
|
402
|
|
|
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.
|
|
|
408
|
|
|
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.
|
|
|
414 @end table
|
|
|
415
|
|
|
416 Here is an example:
|
|
|
417
|
|
|
418 @example
|
|
|
419 (x-parse-geometry "35x70+0-0")
|
|
|
420 @result{} ((width . 35) (height . 70)
|
|
|
421 (left . 0) (top - 0))
|
|
|
422 @end example
|
|
|
423 @end defun
|
|
|
424 @end ignore
|
|
|
425
|
|
|
426 @node Frame Name
|
|
|
427 @subsection The Name of a Frame (As Opposed to Its Title)
|
|
|
428 @cindex frame name
|
|
|
429
|
|
|
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
|
|
|
434 name.
|
|
|
435
|
|
|
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}.
|
|
|
440 @end defun
|
|
|
441
|
|
|
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
|
|
|
445 must be a string.
|
|
|
446 @end defvar
|
|
|
447
|
|
|
448 @node Frame Titles
|
|
|
449 @section Frame Titles
|
|
|
450
|
|
|
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.
|
|
|
455
|
|
|
456 XEmacs computes the frame title based on a template stored in the
|
|
|
457 variable @code{frame-title-format}.
|
|
|
458
|
|
|
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.
|
|
|
462
|
|
|
463 The variable's value is actually a modeline construct, just like
|
|
|
464 @code{modeline-format}. @xref{Modeline Data}.
|
|
|
465 @end defvar
|
|
|
466
|
|
|
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.
|
|
|
471 @end defvar
|
|
|
472
|
|
|
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
|
|
|
479 object.
|
|
|
480
|
|
|
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.
|
|
|
483
|
|
|
484 The window manager is also not required to support color pixmaps,
|
|
|
485 only bitmaps (one plane deep).
|
|
|
486
|
|
|
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
|
|
|
489 one plane deep).
|
|
|
490 @xref{Glyphs}.
|
|
|
491 @end defun
|
|
|
492
|
|
|
493 @node Deleting Frames
|
|
|
494 @section Deleting Frames
|
|
|
495 @cindex deletion of frames
|
|
|
496
|
|
|
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.
|
|
|
500
|
|
444
|
501 @deffn Command delete-frame &optional frame force
|
|
428
|
502 This function deletes the frame @var{frame}. By default, @var{frame} is
|
|
|
503 the selected frame.
|
|
444
|
504
|
|
|
505 A frame may not be deleted if its minibuffer is used by other frames.
|
|
|
506 Normally, you cannot delete the last non-minibuffer-only frame (you must
|
|
|
507 use @code{save-buffers-kill-emacs} or @code{kill-emacs}). However, if
|
|
|
508 optional second argument @var{force} is non-@code{nil}, you can delete
|
|
|
509 the last frame. (This will automatically call
|
|
|
510 @code{save-buffers-kill-emacs}.)
|
|
428
|
511 @end deffn
|
|
|
512
|
|
|
513 @defun frame-live-p frame
|
|
|
514 The function @code{frame-live-p} returns non-@code{nil} if the frame
|
|
|
515 @var{frame} has not been deleted.
|
|
|
516 @end defun
|
|
|
517
|
|
|
518 @ignore Not in XEmacs currently
|
|
|
519 Some window managers provide a command to delete a window. These work
|
|
|
520 by sending a special message to the program that operates the window.
|
|
|
521 When XEmacs gets one of these commands, it generates a
|
|
|
522 @code{delete-frame} event, whose normal definition is a command that
|
|
|
523 calls the function @code{delete-frame}. @xref{Misc Events}.
|
|
|
524 @end ignore
|
|
|
525
|
|
|
526 @node Finding All Frames
|
|
|
527 @section Finding All Frames
|
|
|
528
|
|
|
529 @defun frame-list
|
|
|
530 The function @code{frame-list} returns a list of all the frames that
|
|
|
531 have not been deleted. It is analogous to @code{buffer-list} for
|
|
|
532 buffers. The list that you get is newly created, so modifying the list
|
|
|
533 doesn't have any effect on the internals of XEmacs.
|
|
|
534 @end defun
|
|
|
535
|
|
|
536 @defun device-frame-list &optional device
|
|
|
537 This function returns a list of all frames on @var{device}. If
|
|
|
538 @var{device} is @code{nil}, the selected device will be used.
|
|
|
539 @end defun
|
|
|
540
|
|
|
541 @defun visible-frame-list &optional device
|
|
|
542 This function returns a list of just the currently visible frames.
|
|
|
543 If @var{device} is specified only frames on that device will be returned.
|
|
|
544 @xref{Visibility of Frames}. (TTY frames always count as
|
|
|
545 ``visible'', even though only the selected one is actually displayed.)
|
|
|
546 @end defun
|
|
|
547
|
|
444
|
548 @defun next-frame &optional frame which-frames which-devices
|
|
428
|
549 The function @code{next-frame} lets you cycle conveniently through all
|
|
|
550 the frames from an arbitrary starting point. It returns the ``next''
|
|
444
|
551 frame after @var{frame} in the cycle. If @var{frame} defaults to the
|
|
|
552 selected frame.
|
|
|
553
|
|
|
554 The second argument, @var{which-frames}, says which frames to consider:
|
|
|
555
|
|
|
556 @table @asis
|
|
|
557 @item @code{visible}
|
|
|
558 Consider only frames that are visible.
|
|
|
559
|
|
|
560 @item @code{iconic}
|
|
|
561 Consider only frames that are iconic.
|
|
|
562
|
|
|
563 @item @code{invisible}
|
|
|
564 Consider only frames that are invisible (this is different from iconic).
|
|
|
565
|
|
|
566 @item @code{visible-iconic}
|
|
|
567 Consider frames that are visible or iconic.
|
|
|
568
|
|
|
569 @item @code{invisible-iconic}
|
|
|
570 Consider frames that are invisible or iconic.
|
|
|
571
|
|
|
572 @item @code{nomini}
|
|
|
573 Consider all frames except minibuffer-only ones.
|
|
428
|
574
|
|
444
|
575 @item @code{visible-nomini}
|
|
|
576 Like @code{visible} but omits minibuffer-only frames.
|
|
|
577
|
|
|
578 @item @code{iconic-nomini}
|
|
|
579 Like @code{iconic} but omits minibuffer-only frames.
|
|
|
580
|
|
|
581 @item @code{invisible-nomini}
|
|
|
582 Like @code{invisible} but omits minibuffer-only frames.
|
|
|
583
|
|
|
584 @item @code{visible-iconic-nomini}
|
|
|
585 Like @code{visible-iconic} but omits minibuffer-only frames.
|
|
|
586
|
|
|
587 @item @code{invisible-iconic-nomini}
|
|
|
588 Like @code{invisible-iconic} but omits minibuffer-only frames.
|
|
|
589
|
|
|
590 @item @code{nil}
|
|
|
591 Identical to @code{nomini}.
|
|
|
592
|
|
|
593 @item @var{window}
|
|
|
594 Consider only the window @var{window}'s frame and any frame now using
|
|
|
595 @var{window} as the minibuffer.
|
|
|
596
|
|
|
597 @item any other value
|
|
|
598 Consider all frames.
|
|
|
599 @end table
|
|
|
600
|
|
|
601 The optional argument @var{which-devices} further clarifies on which
|
|
|
602 devices to search for frames as specified by @var{which-frames}.
|
|
428
|
603
|
|
|
604 @table @asis
|
|
|
605 @item @code{nil}
|
|
444
|
606 Consider all devices on the selected console.
|
|
|
607
|
|
|
608 @item @var{device}
|
|
|
609 Consider only the one device @var{device}.
|
|
|
610
|
|
|
611 @item @var{console}
|
|
|
612 Consider all devices on @var{console}.
|
|
|
613
|
|
|
614 @item @var{device-type}
|
|
|
615 Consider all devices with device type @var{device-type}.
|
|
|
616
|
|
|
617 @item @code{window-system}
|
|
|
618 Consider all devices on window system consoles.
|
|
|
619
|
|
428
|
620 @item anything else
|
|
444
|
621 Consider all devices without restriction.
|
|
428
|
622 @end table
|
|
|
623 @end defun
|
|
|
624
|
|
444
|
625 @defun previous-frame &optional frame which-frames which-devices
|
|
428
|
626 Like @code{next-frame}, but cycles through all frames in the opposite
|
|
|
627 direction.
|
|
|
628 @end defun
|
|
|
629
|
|
|
630 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
|
|
|
631 Window Ordering}.
|
|
|
632
|
|
|
633 @node Frames and Windows
|
|
|
634 @section Frames and Windows
|
|
|
635
|
|
|
636 Each window is part of one and only one frame; you can get the frame
|
|
|
637 with @code{window-frame}.
|
|
|
638
|
|
|
639 @defun frame-root-window &optional frame
|
|
|
640 This returns the root window of frame @var{frame}. @var{frame}
|
|
|
641 defaults to the selected frame if not specified.
|
|
|
642 @end defun
|
|
|
643
|
|
|
644 @defun window-frame &optional window
|
|
|
645 This function returns the frame that @var{window} is on. @var{window}
|
|
|
646 defaults to the selected window if omitted.
|
|
|
647 @end defun
|
|
|
648
|
|
|
649 All the non-minibuffer windows in a frame are arranged in a cyclic
|
|
|
650 order. The order runs from the frame's top window, which is at the
|
|
|
651 upper left corner, down and to the right, until it reaches the window at
|
|
|
652 the lower right corner (always the minibuffer window, if the frame has
|
|
|
653 one), and then it moves back to the top.
|
|
|
654
|
|
444
|
655 @defun frame-highest-window &optional frame position
|
|
|
656 This function returns the topmost, leftmost window of frame @var{frame}
|
|
|
657 at position @var{position}.
|
|
|
658
|
|
|
659 If omitted, @var{frame} defaults to the currently selected frame.
|
|
|
660
|
|
|
661 @var{position} is used to distinguish between multiple windows that abut
|
|
|
662 the top of the frame: 0 means the leftmost window abutting the top of
|
|
|
663 the frame, 1 the next-leftmost, etc. @var{position} can also be less
|
|
|
664 than zero: -1 means the rightmost window abutting the top of the frame,
|
|
|
665 -2 the next-rightmost, etc. If omitted, @var{position} defaults to 0,
|
|
|
666 i.e. the leftmost highest window. If there is no window at the given
|
|
|
667 @var{position}, @code{nil} is returned.
|
|
428
|
668 @end defun
|
|
|
669
|
|
444
|
670 The following three functions work similarly.
|
|
|
671
|
|
|
672 @defun frame-lowest-window &optional frame position
|
|
|
673 This function returns the lowest window on @var{frame} which is at
|
|
|
674 @var{position}.
|
|
|
675 @end defun
|
|
|
676
|
|
|
677 @defun frame-leftmost-window &optional frame position
|
|
|
678 This function returns the leftmost window on @var{frame} which is at
|
|
|
679 @var{position}.
|
|
|
680 @end defun
|
|
|
681
|
|
|
682 @defun frame-rightmost-window &optional frame position
|
|
|
683 This function returns the rightmost window on @var{frame} which is at
|
|
|
684 @var{position}.
|
|
|
685 @end defun
|
|
|
686
|
|
|
687
|
|
428
|
688 At any time, exactly one window on any frame is @dfn{selected within the
|
|
|
689 frame}. The significance of this designation is that selecting the
|
|
|
690 frame also selects this window. You can get the frame's current
|
|
|
691 selected window with @code{frame-selected-window}.
|
|
|
692
|
|
|
693 @defun frame-selected-window &optional frame
|
|
|
694 This function returns the window on @var{frame} that is selected within
|
|
|
695 @var{frame}. @var{frame} defaults to the selected frame if not
|
|
|
696 specified.
|
|
|
697 @end defun
|
|
|
698
|
|
|
699 Conversely, selecting a window for XEmacs with @code{select-window} also
|
|
|
700 makes that window selected within its frame. @xref{Selecting Windows}.
|
|
|
701
|
|
|
702 Another function that (usually) returns one of the windows in a frame is
|
|
|
703 @code{minibuffer-window}. @xref{Minibuffer Misc}.
|
|
|
704
|
|
|
705 @node Minibuffers and Frames
|
|
|
706 @section Minibuffers and Frames
|
|
|
707
|
|
|
708 Normally, each frame has its own minibuffer window at the bottom, which
|
|
|
709 is used whenever that frame is selected. If the frame has a minibuffer,
|
|
|
710 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
|
|
|
711
|
|
|
712 However, you can also create a frame with no minibuffer. Such a frame
|
|
|
713 must use the minibuffer window of some other frame. When you create the
|
|
|
714 frame, you can specify explicitly the minibuffer window to use (in some
|
|
|
715 other frame). If you don't, then the minibuffer is found in the frame
|
|
|
716 which is the value of the variable @code{default-minibuffer-frame}. Its
|
|
|
717 value should be a frame which does have a minibuffer.
|
|
|
718
|
|
|
719 @ignore Not yet in XEmacs
|
|
|
720 If you use a minibuffer-only frame, you might want that frame to raise
|
|
|
721 when you enter the minibuffer. If so, set the variable
|
|
|
722 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
|
|
|
723 @end ignore
|
|
|
724
|
|
|
725 @defvar default-minibuffer-frame
|
|
|
726 This variable specifies the frame to use for the minibuffer window, by
|
|
|
727 default.
|
|
|
728 @end defvar
|
|
|
729
|
|
|
730 @node Input Focus
|
|
|
731 @section Input Focus
|
|
|
732 @cindex input focus
|
|
|
733 @cindex selected frame
|
|
|
734
|
|
|
735 At any time, one frame in XEmacs is the @dfn{selected frame}. The selected
|
|
|
736 window always resides on the selected frame. As the focus moves from
|
|
|
737 device to device, the selected frame on each device is remembered and
|
|
|
738 restored when the focus moves back to that device.
|
|
|
739
|
|
|
740 @defun selected-frame &optional device
|
|
|
741 This function returns the selected frame on @var{device}. If
|
|
|
742 @var{device} is not specified, the selected device will be used. If no
|
|
|
743 frames exist on the device, @code{nil} is returned.
|
|
|
744 @end defun
|
|
|
745
|
|
|
746 The X server normally directs keyboard input to the X window that the
|
|
|
747 mouse is in. Some window managers use mouse clicks or keyboard events
|
|
|
748 to @dfn{shift the focus} to various X windows, overriding the normal
|
|
|
749 behavior of the server.
|
|
|
750
|
|
|
751 Lisp programs can switch frames ``temporarily'' by calling
|
|
|
752 the function @code{select-frame}. This does not override the window
|
|
|
753 manager; rather, it escapes from the window manager's control until
|
|
|
754 that control is somehow reasserted.
|
|
|
755
|
|
|
756 When using a text-only terminal, there is no window manager; therefore,
|
|
|
757 @code{select-frame} is the only way to switch frames, and the effect
|
|
|
758 lasts until overridden by a subsequent call to @code{select-frame}.
|
|
|
759 Only the selected terminal frame is actually displayed on the terminal.
|
|
|
760 Each terminal screen except for the initial one has a number, and the
|
|
|
761 number of the selected frame appears in the mode line after the word
|
|
|
762 @samp{XEmacs} (@pxref{Modeline Variables}).
|
|
|
763
|
|
|
764 @defun select-frame frame
|
|
|
765 This function selects frame @var{frame}, temporarily disregarding the
|
|
|
766 focus of the X server if any. The selection of @var{frame} lasts until
|
|
|
767 the next time the user does something to select a different frame, or
|
|
|
768 until the next time this function is called.
|
|
|
769
|
|
|
770 Note that @code{select-frame} does not actually cause the window-system
|
|
|
771 focus to be set to this frame, or the @code{select-frame-hook} or
|
|
|
772 @code{deselect-frame-hook} to be run, until the next time that XEmacs is
|
|
|
773 waiting for an event.
|
|
|
774
|
|
|
775 Also note that when the variable @code{focus-follows-mouse} is
|
|
|
776 non-@code{nil}, the frame selection is temporary and is reverted when
|
|
|
777 the current command terminates, much like the buffer selected by
|
|
|
778 @code{set-buffer}. In order to effect a permanent focus change use
|
|
|
779 @code{focus-frame}.
|
|
|
780 @end defun
|
|
|
781
|
|
|
782 @defun focus-frame frame
|
|
|
783 This function selects @var{frame} and gives it the window system focus.
|
|
|
784 The operation of @code{focus-frame} is not affected by the value of
|
|
|
785 @code{focus-follows-mouse}.
|
|
|
786 @end defun
|
|
|
787
|
|
444
|
788 @defspec save-selected-frame forms@dots{}
|
|
|
789 This special form records the selected frame, executes @var{forms} in
|
|
|
790 sequence, then restores the earlier selected frame. The value returned
|
|
|
791 is the value of the last form.
|
|
|
792 @end defspec
|
|
428
|
793
|
|
444
|
794 @defspec with-selected-frame frame forms@dots{}
|
|
|
795 This special form records the selected frame, then selects @var{frame}
|
|
|
796 and executes @var{forms} in sequence. After the last form is finished,
|
|
|
797 the earlier selected frame is restored. The value returned is the value
|
|
|
798 of the last form.
|
|
|
799 @end defspec
|
|
428
|
800
|
|
|
801 @ignore (FSF Emacs, continued from defun select-frame)
|
|
|
802 XEmacs cooperates with the X server and the window managers by arranging
|
|
|
803 to select frames according to what the server and window manager ask
|
|
|
804 for. It does so by generating a special kind of input event, called a
|
|
|
805 @dfn{focus} event. The command loop handles a focus event by calling
|
|
|
806 @code{handle-select-frame}. @xref{Focus Events}.
|
|
|
807
|
|
|
808 @deffn Command handle-switch-frame frame
|
|
|
809 This function handles a focus event by selecting frame @var{frame}.
|
|
|
810
|
|
|
811 Focus events normally do their job by invoking this command.
|
|
|
812 Don't call it for any other reason.
|
|
|
813 @end deffn
|
|
|
814
|
|
|
815 @defun redirect-frame-focus frame focus-frame
|
|
|
816 This function redirects focus from @var{frame} to @var{focus-frame}.
|
|
|
817 This means that @var{focus-frame} will receive subsequent keystrokes
|
|
|
818 intended for @var{frame}. After such an event, the value of
|
|
|
819 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
|
|
|
820 events specifying @var{frame} will instead select @var{focus-frame}.
|
|
|
821
|
|
|
822 If @var{focus-frame} is @code{nil}, that cancels any existing
|
|
|
823 redirection for @var{frame}, which therefore once again receives its own
|
|
|
824 events.
|
|
|
825
|
|
|
826 One use of focus redirection is for frames that don't have minibuffers.
|
|
|
827 These frames use minibuffers on other frames. Activating a minibuffer
|
|
|
828 on another frame redirects focus to that frame. This puts the focus on
|
|
|
829 the minibuffer's frame, where it belongs, even though the mouse remains
|
|
|
830 in the frame that activated the minibuffer.
|
|
|
831
|
|
|
832 Selecting a frame can also change focus redirections. Selecting frame
|
|
|
833 @code{bar}, when @code{foo} had been selected, changes any redirections
|
|
|
834 pointing to @code{foo} so that they point to @code{bar} instead. This
|
|
|
835 allows focus redirection to work properly when the user switches from
|
|
|
836 one frame to another using @code{select-window}.
|
|
|
837
|
|
|
838 This means that a frame whose focus is redirected to itself is treated
|
|
|
839 differently from a frame whose focus is not redirected.
|
|
|
840 @code{select-frame} affects the former but not the latter.
|
|
|
841
|
|
|
842 The redirection lasts until @code{redirect-frame-focus} is called to
|
|
|
843 change it.
|
|
|
844 @end defun
|
|
|
845 @end ignore
|
|
|
846
|
|
|
847 @node Visibility of Frames
|
|
|
848 @section Visibility of Frames
|
|
|
849 @cindex visible frame
|
|
|
850 @cindex invisible frame
|
|
|
851 @cindex iconified frame
|
|
|
852 @cindex frame visibility
|
|
|
853
|
|
444
|
854 An frame on a window system may be @dfn{visible}, @dfn{invisible}, or
|
|
428
|
855 @dfn{iconified}. If it is visible, you can see its contents. If it is
|
|
|
856 iconified, the frame's contents do not appear on the screen, but an icon
|
|
|
857 does. If the frame is invisible, it doesn't show on the screen, not
|
|
|
858 even as an icon.
|
|
|
859
|
|
|
860 Visibility is meaningless for TTY frames, since only the selected
|
|
|
861 one is actually displayed in any case.
|
|
|
862
|
|
444
|
863 @defun make-frame-visible &optional frame
|
|
428
|
864 This function makes frame @var{frame} visible. If you omit @var{frame},
|
|
|
865 it makes the selected frame visible.
|
|
444
|
866 @end defun
|
|
428
|
867
|
|
444
|
868 @defun make-frame-invisible &optional frame force
|
|
428
|
869 This function makes frame @var{frame} invisible.
|
|
444
|
870 @end defun
|
|
428
|
871
|
|
|
872 @deffn Command iconify-frame &optional frame
|
|
|
873 This function iconifies frame @var{frame}.
|
|
|
874 @end deffn
|
|
|
875
|
|
444
|
876 @defun Command deiconify-frame &optional frame
|
|
|
877 This function de-iconifies frame @var{frame}. Under a window system,
|
|
|
878 this is equivalent to @code{make-frame-visible}.
|
|
|
879 @end defun
|
|
428
|
880
|
|
444
|
881 @defun frame-visible-p &optional frame
|
|
428
|
882 This returns whether @var{frame} is currently ``visible'' (actually in
|
|
|
883 use for display). A frame that is not visible is not updated, and, if
|
|
|
884 it works through a window system, may not show at all.
|
|
|
885 @end defun
|
|
|
886
|
|
444
|
887 @defun frame-iconified-p &optional frame
|
|
428
|
888 This returns whether @var{frame} is iconified. Not all window managers
|
|
|
889 use icons; some merely unmap the window, so this function is not the
|
|
|
890 inverse of @code{frame-visible-p}. It is possible for a frame to not
|
|
|
891 be visible and not be iconified either. However, if the frame is
|
|
|
892 iconified, it will not be visible. (Under FSF Emacs, the functionality
|
|
|
893 of this function is obtained through @code{frame-visible-p}.)
|
|
|
894 @end defun
|
|
|
895
|
|
444
|
896 @defun frame-totally-visible-p &optional frame
|
|
428
|
897 This returns whether @var{frame} is not obscured by any other X
|
|
|
898 windows. On TTY frames, this is the same as @code{frame-visible-p}.
|
|
|
899 @end defun
|
|
|
900
|
|
|
901 @ignore @c Not in XEmacs.
|
|
|
902 The visibility status of a frame is also available as a frame
|
|
|
903 property. You can read or change it as such. @xref{X Frame
|
|
|
904 Properties}.
|
|
|
905
|
|
|
906 The user can iconify and deiconify frames with the window manager. This
|
|
|
907 happens below the level at which XEmacs can exert any control, but XEmacs
|
|
|
908 does provide events that you can use to keep track of such changes.
|
|
|
909 @xref{Misc Events}.
|
|
|
910 @end ignore
|
|
|
911
|
|
|
912 @node Raising and Lowering
|
|
|
913 @section Raising and Lowering Frames
|
|
|
914
|
|
|
915 The X Window System uses a desktop metaphor. Part of this metaphor is
|
|
|
916 the idea that windows are stacked in a notional third dimension
|
|
|
917 perpendicular to the screen surface, and thus ordered from ``highest''
|
|
|
918 to ``lowest''. Where two windows overlap, the one higher up covers the
|
|
|
919 one underneath. Even a window at the bottom of the stack can be seen if
|
|
|
920 no other window overlaps it.
|
|
|
921
|
|
|
922 @cindex raising a frame
|
|
|
923 @cindex lowering a frame
|
|
|
924 A window's place in this ordering is not fixed; in fact, users tend to
|
|
|
925 change the order frequently. @dfn{Raising} a window means moving it
|
|
|
926 ``up'', to the top of the stack. @dfn{Lowering} a window means moving
|
|
|
927 it to the bottom of the stack. This motion is in the notional third
|
|
|
928 dimension only, and does not change the position of the window on the
|
|
|
929 screen.
|
|
|
930
|
|
|
931 You can raise and lower XEmacs's X windows with these functions:
|
|
|
932
|
|
|
933 @deffn Command raise-frame &optional frame
|
|
|
934 This function raises frame @var{frame}.
|
|
|
935 @end deffn
|
|
|
936
|
|
|
937 @deffn Command lower-frame &optional frame
|
|
|
938 This function lowers frame @var{frame}.
|
|
|
939 @end deffn
|
|
|
940
|
|
|
941 You can also specify auto-raise (raising automatically when a frame is
|
|
|
942 selected) or auto-lower (lowering automatically when it is deselected).
|
|
|
943 Under X, most ICCCM-compliant window managers will have an option to do
|
|
|
944 this for you, but the following variables are provided in case you're
|
|
|
945 using a broken WM. (Under FSF Emacs, the same functionality is
|
|
|
946 provided through the @code{auto-raise} and @code{auto-lower}
|
|
|
947 frame properties.)
|
|
|
948
|
|
|
949 @defvar auto-raise-frame
|
|
|
950 This variable's value is @code{t} if frames will be raised to the top
|
|
|
951 when selected.
|
|
|
952 @end defvar
|
|
|
953
|
|
|
954 @ignore Not in XEmacs
|
|
|
955 @defopt minibuffer-auto-raise
|
|
|
956 If this is non-@code{nil}, activation of the minibuffer raises the frame
|
|
|
957 that the minibuffer window is in.
|
|
|
958 @end defopt
|
|
|
959 @end ignore
|
|
|
960
|
|
|
961 @defvar auto-lower-frame
|
|
|
962 This variable's value is @code{t} if frames will be lowered to the bottom
|
|
|
963 when no longer selected.
|
|
|
964 @end defvar
|
|
|
965
|
|
|
966 Auto-raising and auto-lowering is implemented through functions attached
|
|
|
967 to @code{select-frame-hook} and @code{deselect-frame-hook}
|
|
|
968 (@pxref{Frame Hooks}). Under normal circumstances, you should not call
|
|
|
969 these functions directly.
|
|
|
970
|
|
|
971 @defun default-select-frame-hook
|
|
|
972 This hook function implements the @code{auto-raise-frame} variable; it is
|
|
|
973 for use as the value of @code{select-frame-hook}.
|
|
|
974 @end defun
|
|
|
975
|
|
|
976 @defun default-deselect-frame-hook
|
|
|
977 This hook function implements the @code{auto-lower-frame} variable; it is
|
|
|
978 for use as the value of @code{deselect-frame-hook}.
|
|
|
979 @end defun
|
|
|
980
|
|
|
981 @node Frame Configurations
|
|
|
982 @section Frame Configurations
|
|
|
983 @cindex frame configuration
|
|
|
984
|
|
|
985 A @dfn{frame configuration} records the current arrangement of frames,
|
|
|
986 all their properties, and the window configuration of each one.
|
|
|
987
|
|
|
988 @defun current-frame-configuration
|
|
|
989 This function returns a frame configuration list that describes
|
|
|
990 the current arrangement of frames and their contents.
|
|
|
991 @end defun
|
|
|
992
|
|
444
|
993 @defun set-frame-configuration configuration &optional nodelete
|
|
|
994 This function restores the state of frames described by
|
|
|
995 @var{configuration}, which should be the return value from a previous
|
|
|
996 call to @code{current-frame-configuration}.
|
|
|
997
|
|
|
998 Each frame listed in @var{configuration} has its position, size, window
|
|
|
999 configuration, and other properties set as specified in
|
|
428
|
1000 @var{configuration}.
|
|
444
|
1001
|
|
|
1002 Ordinarily, this function deletes all existing frames not listed in
|
|
|
1003 @var{configuration}. But if optional second argument @var{nodelete} is
|
|
|
1004 non-@code{nil}, the unwanted frames are iconified instead.
|
|
428
|
1005 @end defun
|
|
|
1006
|
|
|
1007 @node Frame Hooks
|
|
|
1008 @section Hooks for Customizing Frame Behavior
|
|
|
1009 @cindex frame hooks
|
|
|
1010
|
|
|
1011 XEmacs provides many hooks that are called at various times during a
|
|
|
1012 frame's lifetime. @xref{Hooks}.
|
|
|
1013
|
|
|
1014 @defvar create-frame-hook
|
|
|
1015 This hook is called each time a frame is created. The functions are called
|
|
|
1016 with one argument, the newly-created frame.
|
|
|
1017 @end defvar
|
|
|
1018
|
|
|
1019 @defvar delete-frame-hook
|
|
|
1020 This hook is called each time a frame is deleted. The functions are called
|
|
|
1021 with one argument, the about-to-be-deleted frame.
|
|
|
1022 @end defvar
|
|
|
1023
|
|
|
1024 @defvar select-frame-hook
|
|
|
1025 This is a normal hook that is run just after a frame is selected. The
|
|
|
1026 function @code{default-select-frame-hook}, which implements auto-raising
|
|
|
1027 (@pxref{Raising and Lowering}), is normally attached to this hook.
|
|
|
1028
|
|
|
1029 Note that calling @code{select-frame} does not necessarily set the
|
|
|
1030 focus: The actual window-system focus will not be changed until the next
|
|
|
1031 time that XEmacs is waiting for an event, and even then, the window
|
|
|
1032 manager may refuse the focus-change request.
|
|
|
1033 @end defvar
|
|
|
1034
|
|
|
1035 @defvar deselect-frame-hook
|
|
|
1036 This is a normal hook that is run just before a frame is deselected
|
|
|
1037 (and another frame is selected). The function
|
|
|
1038 @code{default-deselect-frame-hook}, which implements auto-lowering
|
|
|
1039 (@pxref{Raising and Lowering}), is normally attached to this hook.
|
|
|
1040 @end defvar
|
|
|
1041
|
|
|
1042 @defvar map-frame-hook
|
|
|
1043 This hook is called each time a frame is mapped (i.e. made visible).
|
|
|
1044 The functions are called with one argument, the newly mapped frame.
|
|
|
1045 @end defvar
|
|
|
1046
|
|
|
1047 @defvar unmap-frame-hook
|
|
|
1048 This hook is called each time a frame is unmapped (i.e. made invisible
|
|
|
1049 or iconified). The functions are called with one argument, the
|
|
|
1050 newly unmapped frame.
|
|
|
1051 @end defvar
|
