info/lispref.info-27

   1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
  19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
  20
  21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  23 Copyright (C) 1995, 1996 Ben Wing.
  24
  25    Permission is granted to make and distribute verbatim copies of this
  26 manual provided the copyright notice and this permission notice are
  27 preserved on all copies.
  28
  29    Permission is granted to copy and distribute modified versions of
  30 this manual under the conditions for verbatim copying, provided that the
  31 entire resulting derived work is distributed under the terms of a
  32 permission notice identical to this one.
  33
  34    Permission is granted to copy and distribute translations of this
  35 manual into another language, under the above conditions for modified
  36 versions, except that this permission notice may be stated in a
  37 translation approved by the Foundation.
  38
  39    Permission is granted to copy and distribute modified versions of
  40 this manual under the conditions for verbatim copying, provided also
  41 that the section entitled "GNU General Public License" is included
  42 exactly as in the original, and provided that the entire resulting
  43 derived work is distributed under the terms of a permission notice
  44 identical to this one.
  45
  46    Permission is granted to copy and distribute translations of this
  47 manual into another language, under the above conditions for modified
  48 versions, except that the section entitled "GNU General Public License"
  49 may be included in a translation approved by the Free Software
  50 Foundation instead of in the original English.
  51
  52 \1f
  53 File: lispref.info,  Node: Resizing Windows,  Next: Window Configurations,  Prev: Position of Window,  Up: Windows
  54
  55 Changing the Size of a Window
  56 =============================
  57
  58    The window size functions fall into two classes: high-level commands
  59 that change the size of windows and low-level functions that access
  60 window size.  XEmacs does not permit overlapping windows or gaps between
  61 windows, so resizing one window affects other windows.
  62
  63  - Command: enlarge-window size &optional horizontal window
  64      This function makes the selected window SIZE lines taller,
  65      stealing lines from neighboring windows.  It takes the lines from
  66      one window at a time until that window is used up, then takes from
  67      another.  If a window from which lines are stolen shrinks below
  68      `window-min-height' lines, that window disappears.
  69
  70      If HORIZONTAL is non-`nil', this function makes WINDOW wider by
  71      SIZE columns, stealing columns instead of lines.  If a window from
  72      which columns are stolen shrinks below `window-min-width' columns,
  73      that window disappears.
  74
  75      If the requested size would exceed that of the window's frame,
  76      then the function makes the window occupy the entire height (or
  77      width) of the frame.
  78
  79      If SIZE is negative, this function shrinks the window by -SIZE
  80      lines or columns.  If that makes the window smaller than the
  81      minimum size (`window-min-height' and `window-min-width'),
  82      `enlarge-window' deletes the window.
  83
  84      If WINDOW is non-`nil', it specifies a window to change instead of
  85      the selected window.
  86
  87      `enlarge-window' returns `nil'.
  88
  89  - Command: enlarge-window-horizontally columns
  90      This function makes the selected window COLUMNS wider.  It could
  91      be defined as follows:
  92
  93           (defun enlarge-window-horizontally (columns)
  94             (enlarge-window columns t))
  95
  96  - Command: enlarge-window-pixels count &optional side window
  97      This function makes the selected window COUNT pixels larger.  When
  98      called from Lisp, optional second argument SIDE non-`nil' means to
  99      grow sideways COUNT pixels, and optional third argument WINDOW
 100      specifies the window to change instead of the selected window.
 101
 102  - Command: shrink-window size &optional horizontal window
 103      This function is like `enlarge-window' but negates the argument
 104      SIZE, making the selected window smaller by giving lines (or
 105      columns) to the other windows.  If the window shrinks below
 106      `window-min-height' or `window-min-width', then it disappears.
 107
 108      If SIZE is negative, the window is enlarged by -SIZE lines or
 109      columns.
 110
 111      If WINDOW is non-`nil', it specifies a window to change instead of
 112      the selected window.
 113
 114  - Command: shrink-window-horizontally columns
 115      This function makes the selected window COLUMNS narrower.  It
 116      could be defined as follows:
 117
 118           (defun shrink-window-horizontally (columns)
 119             (shrink-window columns t))
 120
 121  - Command: shrink-window-pixels count &optional side window
 122      This function makes the selected window COUNT pixels smaller.
 123      When called from Lisp, optional second argument SIDE non-`nil'
 124      means to shrink sideways COUNT pixels, and optional third argument
 125      WINDOW specifies the window to change instead of the selected
 126      window.
 127
 128    The following two variables constrain the window-size-changing
 129 functions to a minimum height and width.
 130
 131  - User Option: window-min-height
 132      The value of this variable determines how short a window may become
 133      before it is automatically deleted.  Making a window smaller than
 134      `window-min-height' automatically deletes it, and no window may be
 135      created shorter than this.  The absolute minimum height is two
 136      (allowing one line for the mode line, and one line for the buffer
 137      display).  Actions that change window sizes reset this variable to
 138      two if it is less than two.  The default value is 4.
 139
 140  - User Option: window-min-width
 141      The value of this variable determines how narrow a window may
 142      become before it automatically deleted.  Making a window smaller
 143      than `window-min-width' automatically deletes it, and no window
 144      may be created narrower than this.  The absolute minimum width is
 145      one; any value below that is ignored.  The default value is 10.
 146
 147  - Variable: window-size-change-functions
 148      This variable holds a list of functions to be called if the size
 149      of any window changes for any reason.  The functions are called
 150      just once per redisplay, and just once for each frame on which
 151      size changes have occurred.
 152
 153      Each function receives the frame as its sole argument.  There is no
 154      direct way to find out which windows changed size, or precisely
 155      how; however, if your size-change function keeps track, after each
 156      change, of the windows that interest you, you can figure out what
 157      has changed by comparing the old size data with the new.
 158
 159      Creating or deleting windows counts as a size change, and therefore
 160      causes these functions to be called.  Changing the frame size also
 161      counts, because it changes the sizes of the existing windows.
 162
 163      It is not a good idea to use `save-window-excursion' in these
 164      functions, because that always counts as a size change, and it
 165      would cause these functions to be called over and over.  In most
 166      cases, `save-selected-window' is what you need here.
 167
 168 \1f
 169 File: lispref.info,  Node: Window Configurations,  Prev: Resizing Windows,  Up: Windows
 170
 171 Window Configurations
 172 =====================
 173
 174    A "window configuration" records the entire layout of a frame--all
 175 windows, their sizes, which buffers they contain, what part of each
 176 buffer is displayed, and the values of point and the mark.  You can
 177 bring back an entire previous layout by restoring a window
 178 configuration previously saved.
 179
 180    If you want to record all frames instead of just one, use a frame
 181 configuration instead of a window configuration.  *Note Frame
 182 Configurations::.
 183
 184  - Function: current-window-configuration
 185      This function returns a new object representing XEmacs's current
 186      window configuration, namely the number of windows, their sizes
 187      and current buffers, which window is the selected window, and for
 188      each window the displayed buffer, the display-start position, and
 189      the positions of point and the mark.  An exception is made for
 190      point in the current buffer, whose value is not saved.
 191
 192  - Function: set-window-configuration configuration
 193      This function restores the configuration of XEmacs's windows and
 194      buffers to the state specified by CONFIGURATION.  The argument
 195      CONFIGURATION must be a value that was previously returned by
 196      `current-window-configuration'.
 197
 198      This function always counts as a window size change and triggers
 199      execution of the `window-size-change-functions'.  (It doesn't know
 200      how to tell whether the new configuration actually differs from
 201      the old one.)
 202
 203      Here is a way of using this function to get the same effect as
 204      `save-window-excursion':
 205
 206           (let ((config (current-window-configuration)))
 207             (unwind-protect
 208                 (progn (split-window-vertically nil)
 209                        ...)
 210               (set-window-configuration config)))
 211
 212  - Special Form: save-window-excursion forms...
 213      This special form records the window configuration, executes FORMS
 214      in sequence, then restores the earlier window configuration.  The
 215      window configuration includes the value of point and the portion
 216      of the buffer that is visible.  It also includes the choice of
 217      selected window.  However, it does not include the value of point
 218      in the current buffer; use `save-excursion' if you wish to
 219      preserve that.
 220
 221      Don't use this construct when `save-selected-window' is all you
 222      need.
 223
 224      Exit from `save-window-excursion' always triggers execution of the
 225      `window-size-change-functions'.  (It doesn't know how to tell
 226      whether the restored configuration actually differs from the one in
 227      effect at the end of the FORMS.)
 228
 229      The return value is the value of the final form in FORMS.  For
 230      example:
 231
 232           (split-window)
 233                => #<window 25 on control.texi>
 234           (setq w (selected-window))
 235                => #<window 19 on control.texi>
 236           (save-window-excursion
 237             (delete-other-windows w)
 238             (switch-to-buffer "foo")
 239             'do-something)
 240                => do-something
 241                ;; The frame is now split again.
 242
 243  - Function: window-configuration-p object
 244      This function returns `t' if OBJECT is a window configuration.
 245
 246    Primitives to look inside of window configurations would make sense,
 247 but none are implemented.  It is not clear they are useful enough to be
 248 worth implementing.
 249
 250 \1f
 251 File: lispref.info,  Node: Frames,  Next: Consoles and Devices,  Prev: Windows,  Up: Top
 252
 253 Frames
 254 ******
 255
 256    A FRAME is a rectangle on the screen that contains one or more
 257 XEmacs windows (*note Windows::).  A frame initially contains a single
 258 main window (plus perhaps an echo area), which you can subdivide
 259 vertically or horizontally into smaller windows.  Each window is
 260 associated with a modeline (*note Modeline Format::), and optionally two
 261 scrollbars (*note Scrollbars::).  By default the vertical scrollbar is
 262 on, the horizontal scrollbar is off.
 263
 264    The frame may also contain menubars (*note Menubar::), toolbars
 265 (*note Toolbar Intro::), and gutters (*note Gutter Intro::).  By default
 266 there is one of each at the top of the frame, with menubar topmost,
 267 toolbar next, and gutter lowest, immediately above the windows.
 268 (Warning: the gutter is a new, experimental, and unstable feature of
 269 XEmacs version 21.2.)
 270
 271    When XEmacs runs on a text-only terminal, it starts with one "TTY
 272 frame".  If you create additional ones, XEmacs displays one and only
 273 one at any given time--on the terminal screen, of course.
 274
 275    When XEmacs communicates directly with an X server, it does not have
 276 a TTY frame; instead, it starts with a single "X window frame".  It can
 277 display multiple X window frames at the same time, each in its own X
 278 window.
 279
 280  - Function: framep object
 281      This predicate returns `t' if OBJECT is a frame, and `nil'
 282      otherwise.
 283
 284 * Menu:
 285
 286 * Creating Frames::             Creating additional frames.
 287 * Frame Properties::            Controlling frame size, position, font, etc.
 288 * Frame Titles::                Automatic updating of frame titles.
 289 * Deleting Frames::             Frames last until explicitly deleted.
 290 * Finding All Frames::          How to examine all existing frames.
 291 * Frames and Windows::          A frame contains windows;
 292                                   display of text always works through windows.
 293 * Minibuffers and Frames::      How a frame finds the minibuffer to use.
 294 * Input Focus::                 Specifying the selected frame.
 295 * Visibility of Frames::        Frames may be visible or invisible, or icons.
 296 * Raising and Lowering::        Raising a frame makes it hide other X windows;
 297                                   lowering it makes the others hide them.
 298 * Frame Configurations::        Saving the state of all frames.
 299 * Frame Hooks::                 Hooks for customizing frame behavior.
 300
 301    *Note Display::, for related information.
 302
 303 \1f
 304 File: lispref.info,  Node: Creating Frames,  Next: Frame Properties,  Up: Frames
 305
 306 Creating Frames
 307 ===============
 308
 309    To create a new frame, call the function `make-frame'.
 310
 311  - Function: make-frame &optional props device
 312      This function creates a new frame on DEVICE, if DEVICE permits
 313      creation of frames.  (An X server does; an ordinary terminal does
 314      not (yet).)  DEVICE defaults to the selected device if omitted.
 315      *Note Consoles and Devices::.
 316
 317      The argument PROPS is a property list (a list of alternating
 318      keyword-value specifications) of properties for the new frame. (An
 319      alist is accepted for backward compatibility but should not be
 320      passed in.) Any properties not mentioned in PROPS default
 321      according to the value of the variable `default-frame-plist'.  For
 322      X devices, properties not specified in `default-frame-plist'
 323      default in turn from `default-x-frame-plist' and, if not specified
 324      there, from the X resources.  For TTY devices,
 325      `default-tty-frame-plist' is consulted as well as
 326      `default-frame-plist'.
 327
 328      The set of possible properties depends in principle on what kind of
 329      window system XEmacs uses to display its frames.  *Note X Frame
 330      Properties::, for documentation of individual properties you can
 331      specify when creating an X window frame.
 332
 333 \1f
 334 File: lispref.info,  Node: Frame Properties,  Next: Frame Titles,  Prev: Creating Frames,  Up: Frames
 335
 336 Frame Properties
 337 ================
 338
 339    A frame has many properties that control its appearance and behavior.
 340 Just what properties a frame has depends on which display mechanism it
 341 uses.
 342
 343    Frame properties exist for the sake of window systems.  A terminal
 344 frame has few properties, mostly for compatibility's sake; only the
 345 height, width and `buffer-predicate' properties really do something.
 346
 347 * Menu:
 348
 349 * Property Access::     How to change a frame's properties.
 350 * Initial Properties::  Specifying frame properties when you make a frame.
 351 * X Frame Properties::  List of frame properties.
 352 * Size and Position::   Changing the size and position of a frame.
 353 * Frame Name::          The name of a frame (as opposed to its title).
 354
 355 \1f
 356 File: lispref.info,  Node: Property Access,  Next: Initial Properties,  Up: Frame Properties
 357
 358 Access to Frame Properties
 359 --------------------------
 360
 361    These functions let you read and change the properties of a frame.
 362
 363  - Function: frame-properties &optional frame
 364      This function returns a plist listing all the properties of FRAME
 365      and their values.
 366
 367  - Function: frame-property frame property &optional default
 368      This function returns FRAME's value for the property PROPERTY.
 369
 370  - Function: set-frame-properties frame plist
 371      This function alters the properties of frame FRAME based on the
 372      elements of property list PLIST.  If you don't mention a property
 373      in PLIST, its value doesn't change.
 374
 375  - Function: set-frame-property frame prop val
 376      This function sets the property PROP of frame FRAME to the value
 377      VAL.
 378
 379 \1f
 380 File: lispref.info,  Node: Initial Properties,  Next: X Frame Properties,  Prev: Property Access,  Up: Frame Properties
 381
 382 Initial Frame Properties
 383 ------------------------
 384
 385    You can specify the properties for the initial startup frame by
 386 setting `initial-frame-plist' in your `.emacs' file.
 387
 388  - Variable: initial-frame-plist
 389      This variable's value is a plist of alternating property-value
 390      pairs used when creating the initial X window frame.
 391
 392      XEmacs creates the initial frame before it reads your `~/.emacs'
 393      file.  After reading that file, XEmacs checks
 394      `initial-frame-plist', and applies the property settings in the
 395      altered value to the already created initial frame.
 396
 397      If these settings affect the frame geometry and appearance, you'll
 398      see the frame appear with the wrong ones and then change to the
 399      specified ones.  If that bothers you, you can specify the same
 400      geometry and appearance with X resources; those do take affect
 401      before the frame is created.  *Note X Resources: (xemacs)Resources
 402      X.
 403
 404      X resource settings typically apply to all frames.  If you want to
 405      specify some X resources solely for the sake of the initial frame,
 406      and you don't want them to apply to subsequent frames, here's how
 407      to achieve this: specify properties in `default-frame-plist' to
 408      override the X resources for subsequent frames; then, to prevent
 409      these from affecting the initial frame, specify the same
 410      properties in `initial-frame-plist' with values that match the X
 411      resources.
 412
 413    If these properties specify a separate minibuffer-only frame via a
 414 `minibuffer' property of `nil', and you have not yet created one,
 415 XEmacs creates one for you.
 416
 417  - Variable: minibuffer-frame-plist
 418      This variable's value is a plist of properties used when creating
 419      an initial minibuffer-only frame--if such a frame is needed,
 420      according to the properties for the main initial frame.
 421
 422  - Variable: default-frame-plist
 423      This is a plist specifying default values of frame properties for
 424      subsequent XEmacs frames (not the initial ones).
 425
 426    See also `special-display-frame-plist', in *Note Choosing Window::.
 427
 428    If you use options that specify window appearance when you invoke
 429 XEmacs, they take effect by adding elements to `default-frame-plist'.
 430 One exception is `-geometry', which adds the specified position to
 431 `initial-frame-plist' instead.  *Note Command Arguments:
 432 (xemacs)Command Arguments.
 433
 434 \1f
 435 File: lispref.info,  Node: X Frame Properties,  Next: Size and Position,  Prev: Initial Properties,  Up: Frame Properties
 436
 437 X Window Frame Properties
 438 -------------------------
 439
 440    Just what properties a frame has depends on what display mechanism it
 441 uses.  Here is a table of the properties of an X window frame; of these,
 442 `name', `height', `width', and `buffer-predicate' provide meaningful
 443 information in non-X frames.
 444
 445 `name'
 446      The name of the frame.  Most window managers display the frame's
 447      name in the frame's border, at the top of the frame.  If you don't
 448      specify a name, and you have more than one frame, XEmacs sets the
 449      frame name based on the buffer displayed in the frame's selected
 450      window.
 451
 452      If you specify the frame name explicitly when you create the
 453      frame, the name is also used (instead of the name of the XEmacs
 454      executable) when looking up X resources for the frame.
 455
 456 `display'
 457      The display on which to open this frame.  It should be a string of
 458      the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
 459      variable.
 460
 461 `left'
 462      The screen position of the left edge, in pixels, with respect to
 463      the left edge of the screen.  The value may be a positive number
 464      POS, or a list of the form `(+ POS)' which permits specifying a
 465      negative POS value.
 466
 467      A negative number -POS, or a list of the form `(- POS)', actually
 468      specifies the position of the right edge of the window with
 469      respect to the right edge of the screen.  A positive value of POS
 470      counts toward the left.  If the property is a negative integer
 471      -POS then POS is positive!
 472
 473 `top'
 474      The screen position of the top edge, in pixels, with respect to the
 475      top edge of the screen.  The value may be a positive number POS,
 476      or a list of the form `(+ POS)' which permits specifying a
 477      negative POS value.
 478
 479      A negative number -POS, or a list of the form `(- POS)', actually
 480      specifies the position of the bottom edge of the window with
 481      respect to the bottom edge of the screen.  A positive value of POS
 482      counts toward the top.  If the property is a negative integer -POS
 483      then POS is positive!
 484
 485 `icon-left'
 486      The screen position of the left edge _of the frame's icon_, in
 487      pixels, counting from the left edge of the screen.  This takes
 488      effect if and when the frame is iconified.
 489
 490 `icon-top'
 491      The screen position of the top edge _of the frame's icon_, in
 492      pixels, counting from the top edge of the screen.  This takes
 493      effect if and when the frame is iconified.
 494
 495 `user-position'
 496      Non-`nil' if the screen position of the frame was explicitly
 497      requested by the user (for example, with the `-geometry' option).
 498      Nothing automatically makes this property non-`nil'; it is up to
 499      Lisp programs that call `make-frame' to specify this property as
 500      well as specifying the `left' and `top' properties.
 501
 502 `height'
 503      The height of the frame contents, in characters.  (To get the
 504      height in pixels, call `frame-pixel-height'; see *Note Size and
 505      Position::.)
 506
 507 `width'
 508      The width of the frame contents, in characters.  (To get the
 509      height in pixels, call `frame-pixel-width'; see *Note Size and
 510      Position::.)
 511
 512 `window-id'
 513      The number of the X window for the frame.
 514
 515 `minibuffer'
 516      Whether this frame has its own minibuffer.  The value `t' means
 517      yes, `nil' means no, `only' means this frame is just a minibuffer.
 518      If the value is a minibuffer window (in some other frame), the
 519      new frame uses that minibuffer. (Minibuffer-only and
 520      minibuffer-less frames are not yet implemented in XEmacs.)
 521
 522 `buffer-predicate'
 523      The buffer-predicate function for this frame.  The function
 524      `other-buffer' uses this predicate (from the selected frame) to
 525      decide which buffers it should consider, if the predicate is not
 526      `nil'.  It calls the predicate with one arg, a buffer, once for
 527      each buffer; if the predicate returns a non-`nil' value, it
 528      considers that buffer.
 529
 530 `scroll-bar-width'
 531      The width of the vertical scroll bar, in pixels.
 532
 533 `cursor-color'
 534      The color for the cursor that shows point.
 535
 536 `border-color'
 537      The color for the border of the frame.
 538
 539 `border-width'
 540      The width in pixels of the window border.
 541
 542 `internal-border-width'
 543      The distance in pixels between text and border.
 544
 545 `unsplittable'
 546      If non-`nil', this frame's window is never split automatically.
 547
 548 `inter-line-space'
 549      The space in pixels between adjacent lines of text. (Not currently
 550      implemented.)
 551
 552 `modeline'
 553      Whether the frame has a modeline.
 554
 555 \1f
 556 File: lispref.info,  Node: Size and Position,  Next: Frame Name,  Prev: X Frame Properties,  Up: Frame Properties
 557
 558 Frame Size And Position
 559 -----------------------
 560
 561    You can read or change the size and position of a frame using the
 562 frame properties `left', `top', `height', and `width'.  Whatever
 563 geometry properties you don't specify are chosen by the window manager
 564 in its usual fashion.
 565
 566    Here are some special features for working with sizes and positions:
 567
 568  - Function: set-frame-position frame left top
 569      This function sets the position of the top left corner of FRAME to
 570      LEFT and TOP.  These arguments are measured in pixels, and count
 571      from the top left corner of the screen.  Negative property values
 572      count up or rightward from the top left corner of the screen.
 573
 574  - Function: frame-height &optional frame
 575  - Function: frame-width &optional frame
 576      These functions return the height and width of FRAME, measured in
 577      lines and columns.  If you don't supply FRAME, they use the
 578      selected frame.
 579
 580  - Function: frame-pixel-height &optional frame
 581  - Function: frame-pixel-width &optional frame
 582      These functions return the height and width of FRAME, measured in
 583      pixels.  If you don't supply FRAME, they use the selected frame.
 584
 585  - Function: set-frame-size frame cols rows &optional pretend
 586      This function sets the size of FRAME, measured in characters; COLS
 587      and ROWS specify the new width and height.  (If PRETEND is
 588      non-nil, it means that redisplay should act as if the frame's size
 589      is COLS by ROWS, but the actual size of the frame should not be
 590      changed.  You should not normally use this option.)
 591
 592    You can also use the functions `set-frame-height' and
 593 `set-frame-width' to set the height and width individually.  The frame
 594 is the first argument and the size (in rows or columns) is the second.
 595 (There is an optional third argument, PRETEND, which has the same
 596 purpose as the corresponding argument in `set-frame-size'.)
 597
 598 \1f
 599 File: lispref.info,  Node: Frame Name,  Prev: Size and Position,  Up: Frame Properties
 600
 601 The Name of a Frame (As Opposed to Its Title)
 602 ---------------------------------------------
 603
 604    Under X, every frame has a name, which is not the same as the title
 605 of the frame.  A frame's name is used to look up its resources and does
 606 not normally change over the lifetime of a frame.  It is perfectly
 607 allowable, and quite common, for multiple frames to have the same name.
 608
 609  - Function: frame-name &optional frame
 610      This function returns the name of FRAME, which defaults to the
 611      selected frame if not specified.  The name of a frame can also be
 612      obtained from the frame's properties.  *Note Frame Properties::.
 613
 614  - Variable: default-frame-name
 615      This variable holds the default name to assign to newly-created
 616      frames.  This can be overridden by arguments to `make-frame'.  This
 617      must be a string.
 618
 619 \1f
 620 File: lispref.info,  Node: Frame Titles,  Next: Deleting Frames,  Prev: Frame Properties,  Up: Frames
 621
 622 Frame Titles
 623 ============
 624
 625    Every frame has a title; most window managers display the frame
 626 title at the top of the frame.  You can specify an explicit title with
 627 the `name' frame property.  But normally you don't specify this
 628 explicitly, and XEmacs computes the title automatically.
 629
 630    XEmacs computes the frame title based on a template stored in the
 631 variable `frame-title-format'.
 632
 633  - Variable: frame-title-format
 634      This variable specifies how to compute a title for a frame when
 635      you have not explicitly specified one.
 636
 637      The variable's value is actually a modeline construct, just like
 638      `modeline-format'.  *Note Modeline Data::.
 639
 640  - Variable: frame-icon-title-format
 641      This variable specifies how to compute the title for an iconified
 642      frame, when you have not explicitly specified the frame title.
 643      This title appears in the icon itself.
 644
 645  - Function: x-set-frame-icon-pixmap frame pixmap &optional mask
 646      This function sets the icon of the given frame to the given image
 647      instance, which should be an image instance object (as returned by
 648      `make-image-instance'), a glyph object (as returned by
 649      `make-glyph'), or `nil'.  If a glyph object is given, the glyph
 650      will be instantiated on the frame to produce an image instance
 651      object.
 652
 653      If the given image instance has a mask, that will be used as the
 654      icon mask; however, not all window managers support this.
 655
 656      The window manager is also not required to support color pixmaps,
 657      only bitmaps (one plane deep).
 658
 659      If the image instance does not have a mask, then the optional
 660      third argument may be the image instance to use as the mask (it
 661      must be one plane deep).  *Note Glyphs::.
 662
 663 \1f
 664 File: lispref.info,  Node: Deleting Frames,  Next: Finding All Frames,  Prev: Frame Titles,  Up: Frames
 665
 666 Deleting Frames
 667 ===============
 668
 669    Frames remain potentially visible until you explicitly "delete"
 670 them.  A deleted frame cannot appear on the screen, but continues to
 671 exist as a Lisp object until there are no references to it.
 672
 673  - Command: delete-frame &optional frame
 674      This function deletes the frame FRAME.  By default, FRAME is the
 675      selected frame.
 676
 677  - Function: frame-live-p frame
 678      The function `frame-live-p' returns non-`nil' if the frame FRAME
 679      has not been deleted.
 680
 681 \1f
 682 File: lispref.info,  Node: Finding All Frames,  Next: Frames and Windows,  Prev: Deleting Frames,  Up: Frames
 683
 684 Finding All Frames
 685 ==================
 686
 687  - Function: frame-list
 688      The function `frame-list' returns a list of all the frames that
 689      have not been deleted.  It is analogous to `buffer-list' for
 690      buffers.  The list that you get is newly created, so modifying the
 691      list doesn't have any effect on the internals of XEmacs.
 692
 693  - Function: device-frame-list &optional device
 694      This function returns a list of all frames on DEVICE.  If DEVICE
 695      is `nil', the selected device will be used.
 696
 697  - Function: visible-frame-list &optional device
 698      This function returns a list of just the currently visible frames.
 699      If DEVICE is specified only frames on that device will be returned.
 700      *Note Visibility of Frames::.  (TTY frames always count as
 701      "visible", even though only the selected one is actually
 702      displayed.)
 703
 704  - Function: next-frame &optional frame minibuf
 705      The function `next-frame' lets you cycle conveniently through all
 706      the frames from an arbitrary starting point.  It returns the "next"
 707      frame after FRAME in the cycle.  If FRAME is omitted or `nil', it
 708      defaults to the selected frame.
 709
 710      The second argument, MINIBUF, says which frames to consider:
 711
 712     `nil'
 713           Exclude minibuffer-only frames.
 714
 715     `visible'
 716           Consider all visible frames.
 717
 718     0
 719           Consider all visible or iconified frames.
 720
 721     a window
 722           Consider only the frames using that particular window as their
 723           minibuffer.
 724
 725     the symbol `visible'
 726           Include all visible frames.
 727
 728     `0'
 729           Include all visible and iconified frames.
 730
 731     anything else
 732           Consider all frames.
 733
 734  - Function: previous-frame &optional frame minibuf
 735      Like `next-frame', but cycles through all frames in the opposite
 736      direction.
 737
 738    See also `next-window' and `previous-window', in *Note Cyclic Window
 739 Ordering::.
 740
 741 \1f
 742 File: lispref.info,  Node: Frames and Windows,  Next: Minibuffers and Frames,  Prev: Finding All Frames,  Up: Frames
 743
 744 Frames and Windows
 745 ==================
 746
 747    Each window is part of one and only one frame; you can get the frame
 748 with `window-frame'.
 749
 750  - Function: frame-root-window &optional frame
 751      This returns the root window of frame FRAME.  FRAME defaults to
 752      the selected frame if not specified.
 753
 754  - Function: window-frame &optional window
 755      This function returns the frame that WINDOW is on.  WINDOW
 756      defaults to the selected window if omitted.
 757
 758    All the non-minibuffer windows in a frame are arranged in a cyclic
 759 order.  The order runs from the frame's top window, which is at the
 760 upper left corner, down and to the right, until it reaches the window at
 761 the lower right corner (always the minibuffer window, if the frame has
 762 one), and then it moves back to the top.
 763
 764  - Function: frame-top-window frame
 765      This returns the topmost, leftmost window of frame FRAME.
 766
 767    At any time, exactly one window on any frame is "selected within the
 768 frame".  The significance of this designation is that selecting the
 769 frame also selects this window.  You can get the frame's current
 770 selected window with `frame-selected-window'.
 771
 772  - Function: frame-selected-window &optional frame
 773      This function returns the window on FRAME that is selected within
 774      FRAME.  FRAME defaults to the selected frame if not specified.
 775
 776    Conversely, selecting a window for XEmacs with `select-window' also
 777 makes that window selected within its frame.  *Note Selecting Windows::.
 778
 779    Another function that (usually) returns one of the windows in a
 780 frame is `minibuffer-window'.  *Note Minibuffer Misc::.
 781
 782 \1f
 783 File: lispref.info,  Node: Minibuffers and Frames,  Next: Input Focus,  Prev: Frames and Windows,  Up: Frames
 784
 785 Minibuffers and Frames
 786 ======================
 787
 788    Normally, each frame has its own minibuffer window at the bottom,
 789 which is used whenever that frame is selected.  If the frame has a
 790 minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
 791 Misc::).
 792
 793    However, you can also create a frame with no minibuffer.  Such a
 794 frame must use the minibuffer window of some other frame.  When you
 795 create the frame, you can specify explicitly the minibuffer window to
 796 use (in some other frame).  If you don't, then the minibuffer is found
 797 in the frame which is the value of the variable
 798 `default-minibuffer-frame'.  Its value should be a frame which does
 799 have a minibuffer.
 800
 801  - Variable: default-minibuffer-frame
 802      This variable specifies the frame to use for the minibuffer
 803      window, by default.
 804
 805 \1f
 806 File: lispref.info,  Node: Input Focus,  Next: Visibility of Frames,  Prev: Minibuffers and Frames,  Up: Frames
 807
 808 Input Focus
 809 ===========
 810
 811    At any time, one frame in XEmacs is the "selected frame".  The
 812 selected window always resides on the selected frame.  As the focus
 813 moves from device to device, the selected frame on each device is
 814 remembered and restored when the focus moves back to that device.
 815
 816  - Function: selected-frame &optional device
 817      This function returns the selected frame on DEVICE.  If DEVICE is
 818      not specified, the selected device will be used.  If no frames
 819      exist on the device, `nil' is returned.
 820
 821    The X server normally directs keyboard input to the X window that the
 822 mouse is in.  Some window managers use mouse clicks or keyboard events
 823 to "shift the focus" to various X windows, overriding the normal
 824 behavior of the server.
 825
 826    Lisp programs can switch frames "temporarily" by calling the
 827 function `select-frame'.  This does not override the window manager;
 828 rather, it escapes from the window manager's control until that control
 829 is somehow reasserted.
 830
 831    When using a text-only terminal, there is no window manager;
 832 therefore, `select-frame' is the only way to switch frames, and the
 833 effect lasts until overridden by a subsequent call to `select-frame'.
 834 Only the selected terminal frame is actually displayed on the terminal.
 835 Each terminal screen except for the initial one has a number, and the
 836 number of the selected frame appears in the mode line after the word
 837 `XEmacs' (*note Modeline Variables::).
 838
 839  - Function: select-frame frame
 840      This function selects frame FRAME, temporarily disregarding the
 841      focus of the X server if any.  The selection of FRAME lasts until
 842      the next time the user does something to select a different frame,
 843      or until the next time this function is called.
 844
 845      Note that `select-frame' does not actually cause the window-system
 846      focus to be set to this frame, or the `select-frame-hook' or
 847      `deselect-frame-hook' to be run, until the next time that XEmacs is
 848      waiting for an event.
 849
 850      Also note that when the variable `focus-follows-mouse' is
 851      non-`nil', the frame selection is temporary and is reverted when
 852      the current command terminates, much like the buffer selected by
 853      `set-buffer'.  In order to effect a permanent focus change use
 854      `focus-frame'.
 855
 856  - Function: focus-frame frame
 857      This function selects FRAME and gives it the window system focus.
 858      The operation of `focus-frame' is not affected by the value of
 859      `focus-follows-mouse'.
 860
 861  - Macro: save-selected-frame forms...
 862      This macro records the selected frame, executes FORMS in sequence,
 863      then restores the earlier selected frame.  The value returned is
 864      the value of the last form.
 865
 866  - Macro: with-selected-frame frame forms...
 867      This macro records the selected frame, then selects FRAME and
 868      executes FORMS in sequence.  After the last form is finished, the
 869      earlier selected frame is restored.  The value returned is the
 870      value of the last form.
 871
 872 \1f
 873 File: lispref.info,  Node: Visibility of Frames,  Next: Raising and Lowering,  Prev: Input Focus,  Up: Frames
 874
 875 Visibility of Frames
 876 ====================
 877
 878    An X window frame may be "visible", "invisible", or "iconified".  If
 879 it is visible, you can see its contents.  If it is iconified, the
 880 frame's contents do not appear on the screen, but an icon does.  If the
 881 frame is invisible, it doesn't show on the screen, not even as an icon.
 882
 883    Visibility is meaningless for TTY frames, since only the selected
 884 one is actually displayed in any case.
 885
 886  - Command: make-frame-visible &optional frame
 887      This function makes frame FRAME visible.  If you omit FRAME, it
 888      makes the selected frame visible.
 889
 890  - Command: make-frame-invisible &optional frame
 891      This function makes frame FRAME invisible.
 892
 893  - Command: iconify-frame &optional frame
 894      This function iconifies frame FRAME.
 895
 896  - Command: deiconify-frame &optional frame
 897      This function de-iconifies frame FRAME.  Under X, this is
 898      equivalent to `make-frame-visible'.
 899
 900  - Function: frame-visible-p frame
 901      This returns whether FRAME is currently "visible" (actually in use
 902      for display).  A frame that is not visible is not updated, and, if
 903      it works through a window system, may not show at all.
 904
 905  - Function: frame-iconified-p frame
 906      This returns whether FRAME is iconified.  Not all window managers
 907      use icons; some merely unmap the window, so this function is not
 908      the inverse of `frame-visible-p'.  It is possible for a frame to
 909      not be visible and not be iconified either.  However, if the frame
 910      is iconified, it will not be visible.  (Under FSF Emacs, the
 911      functionality of this function is obtained through
 912      `frame-visible-p'.)
 913
 914  - Function: frame-totally-visible-p frame
 915      This returns whether FRAME is not obscured by any other X windows.
 916      On TTY frames, this is the same as `frame-visible-p'.
 917
 918 \1f
 919 File: lispref.info,  Node: Raising and Lowering,  Next: Frame Configurations,  Prev: Visibility of Frames,  Up: Frames
 920
 921 Raising and Lowering Frames
 922 ===========================
 923
 924    The X Window System uses a desktop metaphor.  Part of this metaphor
 925 is the idea that windows are stacked in a notional third dimension
 926 perpendicular to the screen surface, and thus ordered from "highest" to
 927 "lowest".  Where two windows overlap, the one higher up covers the one
 928 underneath.  Even a window at the bottom of the stack can be seen if no
 929 other window overlaps it.
 930
 931    A window's place in this ordering is not fixed; in fact, users tend
 932 to change the order frequently.  "Raising" a window means moving it
 933 "up", to the top of the stack.  "Lowering" a window means moving it to
 934 the bottom of the stack.  This motion is in the notional third
 935 dimension only, and does not change the position of the window on the
 936 screen.
 937
 938    You can raise and lower XEmacs's X windows with these functions:
 939
 940  - Command: raise-frame &optional frame
 941      This function raises frame FRAME.
 942
 943  - Command: lower-frame &optional frame
 944      This function lowers frame FRAME.
 945
 946    You can also specify auto-raise (raising automatically when a frame
 947 is selected) or auto-lower (lowering automatically when it is
 948 deselected).  Under X, most ICCCM-compliant window managers will have
 949 an option to do this for you, but the following variables are provided
 950 in case you're using a broken WM.  (Under FSF Emacs, the same
 951 functionality is provided through the `auto-raise' and `auto-lower'
 952 frame properties.)
 953
 954  - Variable: auto-raise-frame
 955      This variable's value is `t' if frames will be raised to the top
 956      when selected.
 957
 958  - Variable: auto-lower-frame
 959      This variable's value is `t' if frames will be lowered to the
 960      bottom when no longer selected.
 961
 962    Auto-raising and auto-lowering is implemented through functions
 963 attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
 964 Hooks::).  Under normal circumstances, you should not call these
 965 functions directly.
 966
 967  - Function: default-select-frame-hook
 968      This hook function implements the `auto-raise-frame' variable; it
 969      is for use as the value of `select-frame-hook'.
 970
 971  - Function: default-deselect-frame-hook
 972      This hook function implements the `auto-lower-frame' variable; it
 973      is for use as the value of `deselect-frame-hook'.
 974
 975 \1f
 976 File: lispref.info,  Node: Frame Configurations,  Next: Frame Hooks,  Prev: Raising and Lowering,  Up: Frames
 977
 978 Frame Configurations
 979 ====================
 980
 981    A "frame configuration" records the current arrangement of frames,
 982 all their properties, and the window configuration of each one.
 983
 984  - Function: current-frame-configuration
 985      This function returns a frame configuration list that describes
 986      the current arrangement of frames and their contents.
 987
 988  - Function: set-frame-configuration configuration
 989      This function restores the state of frames described in
 990      CONFIGURATION.
 991
 992 \1f
 993 File: lispref.info,  Node: Frame Hooks,  Prev: Frame Configurations,  Up: Frames
 994
 995 Hooks for Customizing Frame Behavior
 996 ====================================
 997
 998    XEmacs provides many hooks that are called at various times during a
 999 frame's lifetime.  *Note Hooks::.
1000
1001  - Variable: create-frame-hook
1002      This hook is called each time a frame is created.  The functions
1003      are called with one argument, the newly-created frame.
1004
1005  - Variable: delete-frame-hook
1006      This hook is called each time a frame is deleted.  The functions
1007      are called with one argument, the about-to-be-deleted frame.
1008
1009  - Variable: select-frame-hook
1010      This is a normal hook that is run just after a frame is selected.
1011      The function `default-select-frame-hook', which implements
1012      auto-raising (*note Raising and Lowering::), is normally attached
1013      to this hook.
1014
1015      Note that calling `select-frame' does not necessarily set the
1016      focus: The actual window-system focus will not be changed until
1017      the next time that XEmacs is waiting for an event, and even then,
1018      the window manager may refuse the focus-change request.
1019
1020  - Variable: deselect-frame-hook
1021      This is a normal hook that is run just before a frame is deselected
1022      (and another frame is selected).  The function
1023      `default-deselect-frame-hook', which implements auto-lowering
1024      (*note Raising and Lowering::), is normally attached to this hook.
1025
1026  - Variable: map-frame-hook
1027      This hook is called each time a frame is mapped (i.e. made
1028      visible).  The functions are called with one argument, the newly
1029      mapped frame.
1030
1031  - Variable: unmap-frame-hook
1032      This hook is called each time a frame is unmapped (i.e. made
1033      invisible or iconified).  The functions are called with one
1034      argument, the newly unmapped frame.
1035
1036 \1f
1037 File: lispref.info,  Node: Consoles and Devices,  Next: Positions,  Prev: Frames,  Up: Top
1038
1039 Consoles and Devices
1040 ********************
1041
1042    A "console" is an object representing a single input connection to
1043 XEmacs, such as an X display or a TTY connection.  It is possible for
1044 XEmacs to have frames on multiple consoles at once (even on
1045 heterogeneous types--you can simultaneously have a frame on an X
1046 display and a TTY connection).  Normally, there is only one console in
1047 existence.
1048
1049    A "device" is an object representing a single output device, such as
1050 a particular screen on an X display. (Usually there is exactly one
1051 device per X console connection, but there may be more than one if you
1052 have a multi-headed X display.  For TTY connections, there is always
1053 exactly one device per console.)
1054
1055    Each device has one or more "frames" in which text can be displayed.
1056 For X displays and the like, a frame corresponds to the normal
1057 window-system concept of a window.  Frames can overlap, be displayed at
1058 various locations within the display, be resized, etc.  For TTY, only
1059 one frame can be displayed at a time, and it occupies the entire TTY
1060 display area.
1061
1062    However, you can still define multiple frames and switch between
1063 them.  Their contents are entirely separate from each other.  These
1064 sorts of frames resemble the "virtual console" capability provided
1065 under Linux or the multiple screens provided by the multiplexing program
1066 `screen' under Unix.
1067
1068    When you start up XEmacs, an initial console and device are created
1069 to receive input and display frames on.  This will either be an X
1070 display or a TTY connection, depending on what mode you started XEmacs
1071 in (this is determined by the `DISPLAY' environment variable, the
1072 `-nw', `-t' and `-display' command-line options, etc.).
1073
1074    You can connect to other X displays and TTY connections by creating
1075 new console objects, and to other X screens on an existing display by
1076 creating new device objects, as described below.  Many functions (for
1077 example the frame-creation functions) take an optional device argument
1078 specifying which device the function pertains to.  If the argument is
1079 omitted, it defaults to the selected device (see below).
1080
1081  - Function: consolep object
1082      This returns non-`nil' if OBJECT is a console.
1083
1084  - Function: devicep object
1085      This returns non-`nil' if OBJECT is a device.
1086
1087 * Menu:
1088
1089 * Basic Console Functions::     Functions for working with consoles.
1090 * Basic Device Functions::      Functions for working with devices.
1091 * Console Types and Device Classes::
1092                                 I/O and color characteristics.
1093 * Connecting to a Console or Device::
1094 * The Selected Console and Device::
1095 * Console and Device I/O::      Controlling input and output.
1096
1097 \1f
1098 File: lispref.info,  Node: Basic Console Functions,  Next: Basic Device Functions,  Up: Consoles and Devices
1099
1100 Basic Console Functions
1101 =======================
1102
1103  - Function: console-list
1104      This function returns a list of all existing consoles.
1105
1106  - Function: console-device-list &optional console
1107      This function returns a list of all devices on CONSOLE.  If
1108      CONSOLE is `nil', the selected console will be used.
1109
1110 \1f
1111 File: lispref.info,  Node: Basic Device Functions,  Next: Console Types and Device Classes,  Prev: Basic Console Functions,  Up: Consoles and Devices
1112
1113 Basic Device Functions
1114 ======================
1115
1116  - Function: device-list
1117      This function returns a list of all existing devices.
1118
1119  - Function: device-or-frame-p object
1120      This function returns non-`nil' if OBJECT is a device or frame.
1121      This function is useful because devices and frames are similar in
1122      many respects and many functions can operate on either one.
1123
1124  - Function: device-frame-list device
1125      This function returns a list of all frames on DEVICE.
1126
1127  - Function: frame-device frame
1128      This function returns the device that FRAME is on.
1129
1130 \1f
1131 File: lispref.info,  Node: Console Types and Device Classes,  Next: Connecting to a Console or Device,  Prev: Basic Device Functions,  Up: Consoles and Devices
1132
1133 Console Types and Device Classes
1134 ================================
1135
1136    Every device is of a particular "type", which describes how the
1137 connection to that device is made and how the device operates, and a
1138 particular "class", which describes other characteristics of the device
1139 (currently, the color capabilities of the device).
1140
1141    The currently-defined device types are
1142
1143 `x'
1144      A connection to an X display (such as `willow:0').
1145
1146 `tty'
1147      A connection to a tty (such as `/dev/ttyp3').
1148
1149 `stream'
1150      A stdio connection.  This describes a device for which input and
1151      output is only possible in a stream-like fashion, such as when
1152      XEmacs in running in batch mode.  The very first device created by
1153      XEmacs is a terminal device and is used to print out messages of
1154      various sorts (for example, the help message when you use the
1155      `-help' command-line option).
1156
1157    The currently-defined device classes are
1158 `color'
1159      A color device.
1160
1161 `grayscale'
1162      A grayscale device (a device that can display multiple shades of
1163      gray, but no color).
1164
1165 `mono'
1166      A device that can only display two colors (e.g. black and white).
1167
1168  - Function: device-type device
1169      This function returns the type of DEVICE.  This is a symbol whose
1170      name is one of the device types mentioned above.
1171
1172  - Function: device-or-frame-type device-or-frame
1173      This function returns the type of DEVICE-OR-FRAME.
1174
1175  - Function: device-class device
1176      This function returns the class (color behavior) of DEVICE.  This
1177      is a symbol whose name is one of the device classes mentioned
1178      above.
1179
1180  - Function: valid-device-type-p device-type
1181      This function returns whether DEVICE-TYPE (which should be a
1182      symbol) species a valid device type.
1183
1184  - Function: valid-device-class-p device-class
1185      This function returns whether DEVICE-CLASS (which should be a
1186      symbol) species a valid device class.
1187
1188  - Variable: terminal-device
1189      This variable holds the initial terminal device object, which
1190      represents XEmacs's stdout.
1191
1192 \1f
1193 File: lispref.info,  Node: Connecting to a Console or Device,  Next: The Selected Console and Device,  Prev: Console Types and Device Classes,  Up: Consoles and Devices
1194
1195 Connecting to a Console or Device
1196 =================================
1197
1198  - Function: make-device &optional type device-data
1199      This function creates a new device.
1200
1201    The following two functions create devices of specific types and are
1202 written in terms of `make-device'.
1203
1204  - Function: make-tty-device &optional tty terminal-type
1205      This function creates a new tty device on TTY.  This also creates
1206      the tty's first frame.  TTY should be a string giving the name of
1207      a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
1208      returned by the `tty' command issued from the Unix shell.  A value
1209      of `nil' means use the stdin and stdout as passed to XEmacs from
1210      the shell.  If TERMINAL-TYPE is non-`nil', it should be a string
1211      specifying the type of the terminal attached to the specified tty.
1212      If it is `nil', the terminal type will be inferred from the
1213      `TERM' environment variable.
1214
1215  - Function: make-x-device &optional display argv-list
1216      This function creates a new device connected to DISPLAY.  Optional
1217      argument ARGV-LIST is a list of strings describing command line
1218      options.
1219
1220  - Function: delete-device device
1221      This function deletes DEVICE, permanently eliminating it from use.
1222      This disconnects XEmacs's connection to the device.
1223
1224  - Variable: create-device-hook
1225      This variable, if non-`nil', should contain a list of functions,
1226      which are called when a device is created.
1227
1228  - Variable: delete-device-hook
1229      This variable, if non-`nil', should contain a list of functions,
1230      which are called when a device is deleted.
1231
1232  - Function: console-live-p object
1233      This function returns non-`nil' if OBJECT is a console that has
1234      not been deleted.
1235
1236  - Function: device-live-p object
1237      This function returns non-`nil' if OBJECT is a device that has not
1238      been deleted.
1239
1240  - Function: device-x-display device
1241      This function returns the X display which DEVICE is connected to,
1242      if DEVICE is an X device.
1243