1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
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
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.
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.
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.
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.
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.
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.
53 File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows
55 Changing the Size of a Window
56 =============================
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.
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.
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.
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
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.
84 If WINDOW is non-`nil', it specifies a window to change instead of
87 `enlarge-window' returns `nil'.
89 - Command: enlarge-window-horizontally columns
90 This function makes the selected window COLUMNS wider. It could
91 be defined as follows:
93 (defun enlarge-window-horizontally (columns)
94 (enlarge-window columns t))
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.
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.
108 If SIZE is negative, the window is enlarged by -SIZE lines or
111 If WINDOW is non-`nil', it specifies a window to change instead of
114 - Command: shrink-window-horizontally columns
115 This function makes the selected window COLUMNS narrower. It
116 could be defined as follows:
118 (defun shrink-window-horizontally (columns)
119 (shrink-window columns t))
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
128 The following two variables constrain the window-size-changing
129 functions to a minimum height and width.
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.
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.
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.
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.
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.
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.
169 File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows
171 Window Configurations
172 =====================
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.
180 If you want to record all frames instead of just one, use a frame
181 configuration instead of a window configuration. *Note Frame
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.
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'.
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
203 Here is a way of using this function to get the same effect as
204 `save-window-excursion':
206 (let ((config (current-window-configuration)))
208 (progn (split-window-vertically nil)
210 (set-window-configuration config)))
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
221 Don't use this construct when `save-selected-window' is all you
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.)
229 The return value is the value of the final form in FORMS. For
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")
241 ;; The frame is now split again.
243 - Function: window-configuration-p object
244 This function returns `t' if OBJECT is a window configuration.
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
251 File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top
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.
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.)
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.
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
280 - Function: framep object
281 This predicate returns `t' if OBJECT is a frame, and `nil'
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.
301 *Note Display::, for related information.
304 File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames
309 To create a new frame, call the function `make-frame'.
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::.
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'.
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.
334 File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
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
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.
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).
356 File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties
358 Access to Frame Properties
359 --------------------------
361 These functions let you read and change the properties of a frame.
363 - Function: frame-properties &optional frame
364 This function returns a plist listing all the properties of FRAME
367 - Function: frame-property frame property &optional default
368 This function returns FRAME's value for the property PROPERTY.
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.
375 - Function: set-frame-property frame prop val
376 This function sets the property PROP of frame FRAME to the value
380 File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties
382 Initial Frame Properties
383 ------------------------
385 You can specify the properties for the initial startup frame by
386 setting `initial-frame-plist' in your `.emacs' file.
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.
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.
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
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
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.
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.
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).
426 See also `special-display-frame-plist', in *Note Choosing Window::.
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.
435 File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties
437 X Window Frame Properties
438 -------------------------
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.
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
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.
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
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
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!
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
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!
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.
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.
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.
503 The height of the frame contents, in characters. (To get the
504 height in pixels, call `frame-pixel-height'; see *Note Size and
508 The width of the frame contents, in characters. (To get the
509 height in pixels, call `frame-pixel-width'; see *Note Size and
513 The number of the X window for the frame.
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.)
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.
531 The width of the vertical scroll bar, in pixels.
534 The color for the cursor that shows point.
537 The color for the border of the frame.
540 The width in pixels of the window border.
542 `internal-border-width'
543 The distance in pixels between text and border.
546 If non-`nil', this frame's window is never split automatically.
549 The space in pixels between adjacent lines of text. (Not currently
553 Whether the frame has a modeline.
556 File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties
558 Frame Size And Position
559 -----------------------
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.
566 Here are some special features for working with sizes and positions:
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.
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
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.
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.)
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'.)
599 File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties
601 The Name of a Frame (As Opposed to Its Title)
602 ---------------------------------------------
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.
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::.
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
620 File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
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.
630 XEmacs computes the frame title based on a template stored in the
631 variable `frame-title-format'.
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.
637 The variable's value is actually a modeline construct, just like
638 `modeline-format'. *Note Modeline Data::.
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.
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
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.
656 The window manager is also not required to support color pixmaps,
657 only bitmaps (one plane deep).
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::.
664 File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
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.
673 - Command: delete-frame &optional frame
674 This function deletes the frame FRAME. By default, FRAME is the
677 - Function: frame-live-p frame
678 The function `frame-live-p' returns non-`nil' if the frame FRAME
679 has not been deleted.
682 File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
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.
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.
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
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.
710 The second argument, MINIBUF, says which frames to consider:
713 Exclude minibuffer-only frames.
716 Consider all visible frames.
719 Consider all visible or iconified frames.
722 Consider only the frames using that particular window as their
726 Include all visible frames.
729 Include all visible and iconified frames.
734 - Function: previous-frame &optional frame minibuf
735 Like `next-frame', but cycles through all frames in the opposite
738 See also `next-window' and `previous-window', in *Note Cyclic Window
742 File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
747 Each window is part of one and only one frame; you can get the frame
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.
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.
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.
764 - Function: frame-top-window frame
765 This returns the topmost, leftmost window of frame FRAME.
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'.
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.
776 Conversely, selecting a window for XEmacs with `select-window' also
777 makes that window selected within its frame. *Note Selecting Windows::.
779 Another function that (usually) returns one of the windows in a
780 frame is `minibuffer-window'. *Note Minibuffer Misc::.
783 File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
785 Minibuffers and Frames
786 ======================
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
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
801 - Variable: default-minibuffer-frame
802 This variable specifies the frame to use for the minibuffer
806 File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
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.
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.
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.
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.
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::).
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.
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.
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
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'.
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.
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.
873 File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
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.
883 Visibility is meaningless for TTY frames, since only the selected
884 one is actually displayed in any case.
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.
890 - Command: make-frame-invisible &optional frame
891 This function makes frame FRAME invisible.
893 - Command: iconify-frame &optional frame
894 This function iconifies frame FRAME.
896 - Command: deiconify-frame &optional frame
897 This function de-iconifies frame FRAME. Under X, this is
898 equivalent to `make-frame-visible'.
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.
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
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'.
919 File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
921 Raising and Lowering Frames
922 ===========================
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.
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
938 You can raise and lower XEmacs's X windows with these functions:
940 - Command: raise-frame &optional frame
941 This function raises frame FRAME.
943 - Command: lower-frame &optional frame
944 This function lowers frame FRAME.
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'
954 - Variable: auto-raise-frame
955 This variable's value is `t' if frames will be raised to the top
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.
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
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'.
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'.
976 File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
981 A "frame configuration" records the current arrangement of frames,
982 all their properties, and the window configuration of each one.
984 - Function: current-frame-configuration
985 This function returns a frame configuration list that describes
986 the current arrangement of frames and their contents.
988 - Function: set-frame-configuration configuration
989 This function restores the state of frames described in
993 File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames
995 Hooks for Customizing Frame Behavior
996 ====================================
998 XEmacs provides many hooks that are called at various times during a
999 frame's lifetime. *Note Hooks::.
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.
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.
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
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.
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.
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
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.
1037 File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top
1039 Consoles and Devices
1040 ********************
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
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.)
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
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.
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.).
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).
1081 - Function: consolep object
1082 This returns non-`nil' if OBJECT is a console.
1084 - Function: devicep object
1085 This returns non-`nil' if OBJECT is a device.
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.
1098 File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices
1100 Basic Console Functions
1101 =======================
1103 - Function: console-list
1104 This function returns a list of all existing consoles.
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.
1111 File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices
1113 Basic Device Functions
1114 ======================
1116 - Function: device-list
1117 This function returns a list of all existing devices.
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.
1124 - Function: device-frame-list device
1125 This function returns a list of all frames on DEVICE.
1127 - Function: frame-device frame
1128 This function returns the device that FRAME is on.
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
1133 Console Types and Device Classes
1134 ================================
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).
1141 The currently-defined device types are
1144 A connection to an X display (such as `willow:0').
1147 A connection to a tty (such as `/dev/ttyp3').
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).
1157 The currently-defined device classes are
1162 A grayscale device (a device that can display multiple shades of
1163 gray, but no color).
1166 A device that can only display two colors (e.g. black and white).
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.
1172 - Function: device-or-frame-type device-or-frame
1173 This function returns the type of DEVICE-OR-FRAME.
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
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.
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.
1188 - Variable: terminal-device
1189 This variable holds the initial terminal device object, which
1190 represents XEmacs's stdout.
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
1195 Connecting to a Console or Device
1196 =================================
1198 - Function: make-device &optional type device-data
1199 This function creates a new device.
1201 The following two functions create devices of specific types and are
1202 written in terms of `make-device'.
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.
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
1220 - Function: delete-device device
1221 This function deletes DEVICE, permanently eliminating it from use.
1222 This disconnects XEmacs's connection to the device.
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.
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.
1232 - Function: console-live-p object
1233 This function returns non-`nil' if OBJECT is a console that has
1236 - Function: device-live-p object
1237 This function returns non-`nil' if OBJECT is a device that has not
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.