Mercurial > hg > xemacs-beta
annotate man/lispref/frames.texi @ 5888:a85efdabe237
Call #'read-passwd when requesting a password from the user, tls.c
src/ChangeLog addition:
2015-04-09 Aidan Kehoe <kehoea@parhasard.net>
* tls.c (nss_pk11_password):
* tls.c (gnutls_pk11_password):
* tls.c (openssl_password):
* tls.c (syms_of_tls):
Our read-a-password function is #'read-passwd, not
#'read-password, correct that in this file.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Thu, 09 Apr 2015 14:54:37 +0100 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
61 @node Creating Frames, Frame Properties, Frames, Frames |
| 428 | 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 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
88 @node Frame Properties, Frame Titles, Creating Frames, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
107 @node Property Access, Initial Properties, Frame Properties, Frame Properties |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
133 @node Initial Properties, X Frame Properties, Property Access, Frame Properties |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
186 @node X Frame Properties, Size and Position, Initial Properties, Frame Properties |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
325 @node Size and Position, Frame Name, X Frame Properties, Frame Properties |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
426 @node Frame Name, , Size and Position, Frame Properties |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
448 @node Frame Titles, Deleting Frames, Frame Properties, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
493 @node Deleting Frames, Finding All Frames, Frame Titles, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
526 @node Finding All Frames, Frames and Windows, Deleting Frames, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
633 @node Frames and Windows, Minibuffers and Frames, Finding All Frames, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
705 @node Minibuffers and Frames, Input Focus, Frames and Windows, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
730 @node Input Focus, Visibility of Frames, Minibuffers and Frames, Frames |
| 428 | 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 | |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
788 @defmac save-selected-frame forms@dots{} |
|
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
789 This macro records the selected frame, executes @var{forms} in |
| 444 | 790 sequence, then restores the earlier selected frame. The value returned |
| 791 is the value of the last form. | |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
792 @end defmac |
| 428 | 793 |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
794 @defmac with-selected-frame frame forms@dots{} |
|
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
795 This macro records the selected frame, then selects @var{frame} |
| 444 | 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. | |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
799 @end defmac |
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
847 @node Visibility of Frames, Raising and Lowering, Input Focus, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
912 @node Raising and Lowering, Frame Configurations, Visibility of Frames, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
981 @node Frame Configurations, Frame Hooks, Raising and Lowering, Frames |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1007 @node Frame Hooks, , Frame Configurations, Frames |
| 428 | 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 |