Mercurial > hg > xemacs-beta
annotate man/lispref/frames.texi @ 4967:0d4c9d0f6a8d
rewrite dynarr code
-------------------- ChangeLog entries follow: --------------------
src/ChangeLog addition:
2010-02-03 Ben Wing <ben@xemacs.org>
* device-x.c (x_get_resource_prefix):
* device-x.c (Fx_get_resource):
* device-x.c (Fx_get_resource_prefix):
* device-x.c (Fx_put_resource):
* dialog-msw.c:
* dialog-msw.c (handle_question_dialog_box):
* dired-msw.c (mswindows_sort_files):
* dired-msw.c (mswindows_get_files):
* extents.c (extent_fragment_sort_by_priority):
* extents.c (Fset_extent_parent):
* file-coding.c (coding_reader):
* file-coding.c (coding_writer):
* file-coding.c (gzip_convert):
* frame.c (generate_title_string):
* gutter.c (calculate_gutter_size_from_display_lines):
* indent.c (vmotion_1):
* lread.c (read_bit_vector):
* mule-coding.c (iso2022_decode):
* rangetab.c:
* rangetab.c (Fcopy_range_table):
* rangetab.c (Fget_range_table):
* rangetab.c (unified_range_table_copy_data):
* redisplay-msw.c (mswindows_output_string):
* redisplay-output.c (output_display_line):
* redisplay-output.c (redisplay_move_cursor):
* redisplay-output.c (redisplay_clear_bottom_of_window):
* redisplay-tty.c (tty_output_ichar_dynarr):
* redisplay-tty.c (set_foreground_to):
* redisplay-tty.c (set_background_to):
* redisplay-xlike-inc.c (XLIKE_output_string):
* redisplay.c (redisplay_window_text_width_string):
* redisplay.c (redisplay_text_width_string):
* redisplay.c (create_text_block):
* redisplay.c (SET_CURRENT_MODE_CHARS_PIXSIZE):
* redisplay.c (generate_fstring_runes):
* redisplay.c (regenerate_modeline):
* redisplay.c (ensure_modeline_generated):
* redisplay.c (real_current_modeline_height):
* redisplay.c (create_string_text_block):
* redisplay.c (regenerate_window):
* redisplay.c (REGEN_INC_FIND_START_END):
* redisplay.c (point_visible):
* redisplay.c (redisplay_window):
* redisplay.c (mark_glyph_block_dynarr):
* redisplay.c (line_start_cache_start):
* redisplay.c (start_with_line_at_pixpos):
* redisplay.c (update_line_start_cache):
* redisplay.c (glyph_to_pixel_translation):
* redisplay.c (pixel_to_glyph_translation):
* sysdep.c (qxe_readdir):
* text.c (dfc_convert_to_external_format):
* text.c (dfc_convert_to_internal_format):
* toolbar-common.c (common_output_toolbar_button):
* window.c (window_modeline_height):
* window.c (Fwindow_last_line_visible_height):
* window.c (window_displayed_height):
* window.c (window_scroll):
* window.c (get_current_pixel_pos):
Use Dynarr_begin() in place of Dynarr_atp (foo, 0).
* dynarr.c (Dynarr_realloc):
* dynarr.c (Dynarr_lisp_realloc):
* dynarr.c (Dynarr_resize):
* dynarr.c (Dynarr_insert_many):
* dynarr.c (Dynarr_delete_many):
* dynarr.c (Dynarr_memory_usage):
* dynarr.c (stack_like_malloc):
* dynarr.c (stack_like_free):
* lisp.h:
* lisp.h (DECLARE_DYNARR_LISP_IMP):
* lisp.h (XD_DYNARR_DESC):
* lisp.h (Dynarr_pop):
* gutter.c (output_gutter):
* redisplay-output.c (sync_rune_structs):
* redisplay-output.c (redisplay_output_window):
Redo the dynarr code, add greater checks.
Rename the `len', `largest' and `max' members to `len_',
`largest_' and `max_' to try and catch existing places that might
directly modify these values. Make new accessors Dynarr_largest()
and Dynarr_max() and make them and existing Dynarr_length() be
non-lvalues by adding '+ 0' to them; fix a couple of places in the
redisplay code that tried to modify the length directly by setting
Dynarr_length(). Use the accessors whenever possible even in the
dynarr code itself. The accessors also verify that 0 <= len <=
largest <= max. Rename settor function Dynarr_set_size() to
Dynarr_set_length() and use it more consistently; also create
lower-level Dynarr_set_length_1(). This latter function should be
the only function that directly modifies the `len_' member of a
Dynarr, and in the process makes sure that the `largest' value is
kept correct.
Consistently use ERROR_CHECK_STRUCTURES instead of
ERROR_CHECK_TYPES for error-checking code. Reintroduce the
temporarily disabled verification code on the positions of
Dynarr_at(), Dynarr_atp() and Dynarr_atp_past_end().
Also create Dynarr_resize_if() in place of a repeated
code fragment. Clean up all the functions that modify Dynarrs to
use the new macros and functions and verify the correctness of the
Dynarr both before and after the change.
Note that there are two kinds of verification -- one for accessing
and one for modifying. The difference is that the modify
verification additionally checks to make sure that the Dynarr
isn't locked. (This is used in redisplay to check for problems
with reentrancy.)
* lrecord.h: Move XD_DYNARR_DESC to lisp.h, grouping with the dynarr code.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Wed, 03 Feb 2010 20:51:18 -0600 |
| parents | 755ae5b97edb |
| children | 62b9ef1ed4ac |
| 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 | |
| 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{} |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
789 This special operator 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. | |
| 792 @end defspec | |
| 428 | 793 |
| 444 | 794 @defspec with-selected-frame frame forms@dots{} |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
795 This special operator 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. | |
| 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 |