This is Info file elisp, produced by Makeinfo version 1.68 from the input file elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This version is the edition 2.5 of the GNU Emacs Lisp Reference Manual. It corresponds to Emacs Version 20.3 Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: elisp, Node: Resizing Windows, Next: Coordinates and Windows, Prev: Size of Window, Up: Windows Changing the Size of a Window ============================= The window size functions fall into two classes: high-level commands that change the size of windows and low-level functions that access window size. Emacs does not permit overlapping windows or gaps between windows, so resizing one window affects other windows. - Command: enlarge-window SIZE &optional HORIZONTAL This function makes the selected window SIZE lines taller, stealing lines from neighboring windows. It takes the lines from one window at a time until that window is used up, then takes from another. If a window from which lines are stolen shrinks below `window-min-height' lines, that window disappears. If HORIZONTAL is non-`nil', this function makes WINDOW wider by SIZE columns, stealing columns instead of lines. If a window from which columns are stolen shrinks below `window-min-width' columns, that window disappears. If the requested size would exceed that of the window's frame, then the function makes the window occupy the entire height (or width) of the frame. If SIZE is negative, this function shrinks the window by -SIZE lines or columns. If that makes the window smaller than the minimum size (`window-min-height' and `window-min-width'), `enlarge-window' deletes the window. `enlarge-window' returns `nil'. - Command: enlarge-window-horizontally COLUMNS This function makes the selected window COLUMNS wider. It could be defined as follows: (defun enlarge-window-horizontally (columns) (enlarge-window columns t)) - Command: shrink-window SIZE &optional HORIZONTAL This function is like `enlarge-window' but negates the argument SIZE, making the selected window smaller by giving lines (or columns) to the other windows. If the window shrinks below `window-min-height' or `window-min-width', then it disappears. If SIZE is negative, the window is enlarged by -SIZE lines or columns. - Command: shrink-window-horizontally COLUMNS This function makes the selected window COLUMNS narrower. It could be defined as follows: (defun shrink-window-horizontally (columns) (shrink-window columns t)) - Command: shrink-window-if-larger-than-buffer WINDOW This command shrinks WINDOW to be as small as possible while still showing the full contents of its buffer--but not less than `window-min-height' lines. However, the command does nothing if the window is already too small to display the whole text of the buffer, or if part of the contents are currently scrolled off screen, or if the window is not the full width of its frame, or if the window is the only window in its frame. The following two variables constrain the window-size-changing functions to a minimum height and width. - User Option: window-min-height The value of this variable determines how short a window may become before it is automatically deleted. Making a window smaller than `window-min-height' automatically deletes it, and no window may be created shorter than this. The absolute minimum height is two (allowing one line for the mode line, and one line for the buffer display). Actions that change window sizes reset this variable to two if it is less than two. The default value is 4. - User Option: window-min-width The value of this variable determines how narrow a window may become before it is automatically deleted. Making a window smaller than `window-min-width' automatically deletes it, and no window may be created narrower than this. The absolute minimum width is one; any value below that is ignored. The default value is 10.  File: elisp, Node: Coordinates and Windows, Next: Window Configurations, Prev: Resizing Windows, Up: Windows Coordinates and Windows ======================= This section describes how to relate screen coordinates to windows. - Function: window-at X Y &optional FRAME This function returns the window containing the specified cursor position in the frame FRAME. The coordinates X and Y are measured in characters and count from the top left corner of the frame. If they are out of range, `window-at' returns `nil'. If you omit FRAME, the selected frame is used. - Function: coordinates-in-window-p COORDINATES WINDOW This function checks whether a particular frame position falls within the window WINDOW. The argument COORDINATES is a cons cell of the form `(X . Y)'. The coordinates X and Y are measured in characters, and count from the top left corner of the screen or frame. The value returned by `coordinates-in-window-p' is non-`nil' if the coordinates are inside WINDOW. The value also indicates what part of the window the position is in, as follows: `(RELX . RELY)' The coordinates are inside WINDOW. The numbers RELX and RELY are the equivalent window-relative coordinates for the specified position, counting from 0 at the top left corner of the window. `mode-line' The coordinates are in the mode line of WINDOW. `vertical-split' The coordinates are in the vertical line between WINDOW and its neighbor to the right. This value occurs only if the window doesn't have a scroll bar; positions in a scroll bar are considered outside the window. `nil' The coordinates are not in any part of WINDOW. The function `coordinates-in-window-p' does not require a frame as argument because it always uses the frame that WINDOW is on.  File: elisp, Node: Window Configurations, Next: Window Hooks, Prev: Coordinates and Windows, Up: Windows Window Configurations ===================== A "window configuration" records the entire layout of one frame--all windows, their sizes, which buffers they contain, what part of each buffer is displayed, and the values of point and the mark. You can bring back an entire previous layout by restoring a window configuration previously saved. If you want to record all frames instead of just one, use a frame configuration instead of a window configuration. *Note Frame Configurations::. - Function: current-window-configuration This function returns a new object representing the selected frame's current window configuration, including the number of windows, their sizes and current buffers, which window is the selected window, and for each window the displayed buffer, the display-start position, and the positions of point and the mark. It also includes the values of `window-min-height', `window-min-width' and `minibuffer-scroll-window'. An exception is made for point in the current buffer, whose value is not saved. - Function: set-window-configuration CONFIGURATION This function restores the configuration of windows and buffers as specified by CONFIGURATION. The argument CONFIGURATION must be a value that was previously returned by `current-window-configuration'. This configuration is restored in the frame from which CONFIGURATION was made, whether that frame is selected or not. This always counts as a window size change and triggers execution of the `window-size-change-functions' (*note Window Hooks::.), because `set-window-configuration' doesn't know how to tell whether the new configuration actually differs from the old one. If the frame which CONFIGURATION was saved from is dead, all this function does is restore the three variables `window-min-height', `window-min-width' and `minibuffer-scroll-window'. Here is a way of using this function to get the same effect as `save-window-excursion': (let ((config (current-window-configuration))) (unwind-protect (progn (split-window-vertically nil) ...) (set-window-configuration config))) - Special Form: save-window-excursion FORMS... This special form records the window configuration, executes FORMS in sequence, then restores the earlier window configuration. The window configuration includes the value of point and the portion of the buffer that is visible. It also includes the choice of selected window. However, it does not include the value of point in the current buffer; use `save-excursion' also, if you wish to preserve that. Don't use this construct when `save-selected-window' is all you need. Exit from `save-window-excursion' always triggers execution of the `window-size-change-functions'. (It doesn't know how to tell whether the restored configuration actually differs from the one in effect at the end of the FORMS.) The return value is the value of the final form in FORMS. For example: (split-window) => # (setq w (selected-window)) => # (save-window-excursion (delete-other-windows w) (switch-to-buffer "foo") 'do-something) => do-something ;; The screen is now split again. - Function: window-configuration-p OBJECT This function returns `t' if OBJECT is a window configuration. - Function: compare-window-configurations CONFIG1 CONFIG2 This function compares two window configurations as regards the structure of windows, but ignores the values of point and mark and the saved scrolling positions--it can return `t' even if those aspects differ. The function `equal' can also compare two window configurations; it regards configurations as unequal if they differ in any respect, even a saved point or mark. Primitives to look inside of window configurations would make sense, but none are implemented. It is not clear they are useful enough to be worth implementing.  File: elisp, Node: Window Hooks, Prev: Window Configurations, Up: Windows Hooks for Window Scrolling and Changes ====================================== This section describes how a Lisp program can take action whenever a window displays a different part of its buffer or a different buffer. There are three actions that can change this: scrolling the window, switching buffers in the window, and changing the size of the window. The first two actions run `window-scroll-functions'; the last runs `window-size-change-functions'. The paradigmatic use of these hooks is in the implementation of Lazy Lock mode; see *Note Lazy Lock: (emacs)Support Modes. - Variable: window-scroll-functions This variable holds a list of functions that Emacs should call before redisplaying a window with scrolling. It is not a normal hook, because each function is called with two arguments: the window, and its new display-start position. Displaying a different buffer in the window also runs these functions. These functions must be careful in using `window-end' (*note Window Start::.); if you need an up-to-date value, you must use the UPDATE argument to ensure you get it. - Variable: window-size-change-functions This variable holds a list of functions to be called if the size of any window changes for any reason. The functions are called just once per redisplay, and just once for each frame on which size changes have occurred. Each function receives the frame as its sole argument. There is no direct way to find out which windows on that frame have changed size, or precisely how. However, if a size-change function records, at each call, the existing windows and their sizes, it can also compare the present sizes and the previous sizes. Creating or deleting windows counts as a size change, and therefore causes these functions to be called. Changing the frame size also counts, because it changes the sizes of the existing windows. It is not a good idea to use `save-window-excursion' (*note Window Configurations::.) in these functions, because that always counts as a size change, and it would cause these functions to be called over and over. In most cases, `save-selected-window' (*note Selecting Windows::.) is what you need here. - Variable: redisplay-end-trigger-functions This abnormal hook is run whenever redisplay in a window uses text that extends past a specified end trigger position. You set the end trigger position with the function `set-window-redisplay-end-trigger'. The functions are called with two arguments: the window, and the end trigger position. Storing `nil' for the end trigger position turns off the feature, and the trigger value is automatically reset to `nil' just after the hook is run. - Function: set-window-redisplay-end-trigger WINDOW POSITION This function sets WINDOW's end trigger position at POSITION. - Function: window-redisplay-end-trigger WINDOW This function returns WINDOW's current end trigger position. - Variable: window-configuration-change-hook A normal hook that is run every time you change the window configuration of an existing frame. This includes splitting or deleting windows, changing the sizes of windows, or displaying a different buffer in a window. The frame whose window configuration has changed is the selected frame when this hook runs.  File: elisp, Node: Frames, Next: Positions, Prev: Windows, Up: Top Frames ****** A "frame" is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window), which you can subdivide vertically or horizontally into smaller windows. When Emacs runs on a text-only terminal, it starts with one "terminal frame". If you create additional ones, Emacs displays one and only one at any given time--on the terminal screen, of course. When Emacs communicates directly with a supported window system, such as X Windows, it does not have a terminal frame; instead, it starts with a single "window frame", but you can create more, and Emacs can display several such frames at once as is usual for window systems. - Function: framep OBJECT This predicate returns `t' if OBJECT is a frame, and `nil' otherwise. * Menu: * Creating Frames:: Creating additional frames. * Multiple Displays:: Creating frames on other displays. * Frame Parameters:: Controlling frame size, position, font, etc. * Frame Titles:: Automatic updating of frame titles. * Deleting Frames:: Frames last until explicitly deleted. * Finding All Frames:: How to examine all existing frames. * Frames and Windows:: A frame contains windows; display of text always works through windows. * Minibuffers and Frames:: How a frame finds the minibuffer to use. * Input Focus:: Specifying the selected frame. * Visibility of Frames:: Frames may be visible or invisible, or icons. * Raising and Lowering:: Raising a frame makes it hide other windows; lowering it makes the others hide them. * Frame Configurations:: Saving the state of all frames. * Mouse Tracking:: Getting events that say when the mouse moves. * Mouse Position:: Asking where the mouse is, or moving it. * Pop-Up Menus:: Displaying a menu for the user to select from. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shapes:: Specifying the shape of the mouse pointer. * Window System Selections:: Transferring text to and from other X clients. * Font Names:: Looking up font names. * Fontsets:: A fontset is a collection of fonts for displaying various character sets. * Color Names:: Getting the definitions of color names. * Resources:: Getting resource values from the server. * Server Data:: Getting info about the X server. *Note Display::, for information about the related topic of controlling Emacs redisplay.  File: elisp, Node: Creating Frames, Next: Multiple Displays, Up: Frames Creating Frames =============== To create a new frame, call the function `make-frame'. - Function: make-frame &optional ALIST This function creates a new frame. If you are using a supported window system, it makes a window frame; otherwise, it makes a terminal frame. The argument is an alist specifying frame parameters. Any parameters not mentioned in ALIST default according to the value of the variable `default-frame-alist'; parameters not specified even there default from the standard X resources or whatever is used instead on your system. The set of possible parameters depends in principle on what kind of window system Emacs uses to display its frames. *Note Window Frame Parameters::, for documentation of individual parameters you can specify. - Variable: before-make-frame-hook A normal hook run by `make-frame' before it actually creates the frame. - Variable: after-make-frame-hook An abnormal hook run by `make-frame' after it creates the frame. Each function in `after-make-frame-hook' receives one argument, the frame just created.  File: elisp, Node: Multiple Displays, Next: Frame Parameters, Prev: Creating Frames, Up: Frames Multiple Displays ================= A single Emacs can talk to more than one X display. Initially, Emacs uses just one display--the one chosen with the `DISPLAY' environment variable or with the `--display' option (*note Initial Options: (emacs)Initial Options.). To connect to another display, use the command `make-frame-on-display' or specify the `display' frame parameter when you create the frame. Emacs treats each X server as a separate terminal, giving each one its own selected frame and its own minibuffer windows. A few Lisp variables are "terminal-local"; that is, they have a separate binding for each terminal. The binding in effect at any time is the one for the terminal that the currently selected frame belongs to. These variables include `default-minibuffer-frame', `defining-kbd-macro', `last-kbd-macro', and `system-key-alist'. They are always terminal-local, and can never be buffer-local (*note Buffer-Local Variables::.) or frame-local. A single X server can handle more than one screen. A display name `HOST:SERVER.SCREEN' has three parts; the last part specifies the screen number for a given server. When you use two screens belonging to one server, Emacs knows by the similarity in their names that they share a single keyboard, and it treats them as a single terminal. - Command: make-frame-on-display DISPLAY &optional PARAMETERS This creates a new frame on display DISPLAY, taking the other frame parameters from PARAMETERS. Aside from the DISPLAY argument, it is like `make-frame' (*note Creating Frames::.). - Function: x-display-list This returns a list that indicates which X displays Emacs has a connection to. The elements of the list are strings, and each one is a display name. - Function: x-open-connection DISPLAY &optional XRM-STRING This function opens a connection to the X display DISPLAY. It does not create a frame on that display, but it permits you to check that communication can be established with that display. The optional argument XRM-STRING, if not `nil', is a string of resource names and values, in the same format used in the `.Xresources' file. The values you specify override the resource values recorded in the X server itself; they apply to all Emacs frames created on this display. Here's an example of what this string might look like: "*BorderWidth: 3\n*InternalBorder: 2\n" *Note Resources::. - Function: x-close-connection DISPLAY This function closes the connection to display DISPLAY. Before you can do this, you must first delete all the frames that were open on that display (*note Deleting Frames::.).  File: elisp, Node: Frame Parameters, Next: Frame Titles, Prev: Multiple Displays, Up: Frames Frame Parameters ================ A frame has many parameters that control its appearance and behavior. Just what parameters a frame has depends on what display mechanism it uses. Frame parameters exist for the sake of window systems. A terminal frame has a few parameters, mostly for compatibility's sake; only the `height', `width', `name', `title', `buffer-list' and `buffer-predicate' parameters do something special. * Menu: * Parameter Access:: How to change a frame's parameters. * Initial Parameters:: Specifying frame parameters when you make a frame. * Window Frame Parameters:: List of frame parameters for window systems. * Size and Position:: Changing the size and position of a frame.  File: elisp, Node: Parameter Access, Next: Initial Parameters, Up: Frame Parameters Access to Frame Parameters -------------------------- These functions let you read and change the parameter values of a frame. - Function: frame-parameters FRAME The function `frame-parameters' returns an alist listing all the parameters of FRAME and their values. - Function: modify-frame-parameters FRAME ALIST This function alters the parameters of frame FRAME based on the elements of ALIST. Each element of ALIST has the form `(PARM . VALUE)', where PARM is a symbol naming a parameter. If you don't mention a parameter in ALIST, its value doesn't change.  File: elisp, Node: Initial Parameters, Next: Window Frame Parameters, Prev: Parameter Access, Up: Frame Parameters Initial Frame Parameters ------------------------ You can specify the parameters for the initial startup frame by setting `initial-frame-alist' in your `.emacs' file. - Variable: initial-frame-alist This variable's value is an alist of parameter values used when creating the initial window frame. You can set this variable to specify the appearance of the initial frame without altering subsequent frames. Each element has the form: (PARAMETER . VALUE) Emacs creates the initial frame before it reads your `~/.emacs' file. After reading that file, Emacs checks `initial-frame-alist', and applies the parameter settings in the altered value to the already created initial frame. If these settings affect the frame geometry and appearance, you'll see the frame appear with the wrong ones and then change to the specified ones. If that bothers you, you can specify the same geometry and appearance with X resources; those do take affect before the frame is created. *Note X Resources: (emacs)Resources X. X resource settings typically apply to all frames. If you want to specify some X resources solely for the sake of the initial frame, and you don't want them to apply to subsequent frames, here's how to achieve this. Specify parameters in `default-frame-alist' to override the X resources for subsequent frames; then, to prevent these from affecting the initial frame, specify the same parameters in `initial-frame-alist' with values that match the X resources. If these parameters specify a separate minibuffer-only frame with `(minibuffer . nil)', and you have not created one, Emacs creates one for you. - Variable: minibuffer-frame-alist This variable's value is an alist of parameter values used when creating an initial minibuffer-only frame--if such a frame is needed, according to the parameters for the main initial frame. - Variable: default-frame-alist This is an alist specifying default values of frame parameters for all Emacs frames--the first frame, and subsequent frames. When using the X Window System, you can get the same results by means of X resources in many cases. See also `special-display-frame-alist', in *Note Choosing Window::. If you use options that specify window appearance when you invoke Emacs, they take effect by adding elements to `default-frame-alist'. One exception is `-geometry', which adds the specified position to `initial-frame-alist' instead. *Note Command Arguments: (emacs)Command Arguments.  File: elisp, Node: Window Frame Parameters, Next: Size and Position, Prev: Initial Parameters, Up: Frame Parameters Window Frame Parameters ----------------------- Just what parameters a frame has depends on what display mechanism it uses. Here is a table of the parameters that have special meanings in a window frame; of these, `name', `title', `height', `width', `buffer-list' and `buffer-predicate' provide meaningful information in terminal frames. `display' The display on which to open this frame. It should be a string of the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment variable. `title' If a frame has a non-`nil' title, it appears in the window system's border for the frame, and also in the mode line of windows in that frame if `mode-line-frame-identification' uses `%F' (*note %-Constructs::.). This is normally the case when Emacs is not using a window system, and can only display one frame at a time. *Note Frame Titles::. `name' The name of the frame. The frame name serves as a default for the frame title, if the `title' parameter is unspecified or `nil'. If you don't specify a name, Emacs sets the frame name automatically (*note Frame Titles::.). If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame. `left' The screen position of the left edge, in pixels, with respect to the left edge of the screen. The value may be a positive number POS, or a list of the form `(+ POS)' which permits specifying a negative POS value. A negative number -POS, or a list of the form `(- POS)', actually specifies the position of the right edge of the window with respect to the right edge of the screen. A positive value of POS counts toward the left. *Reminder:* if the parameter is a negative integer -POS, then POS is positive. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-`nil' value for the `user-position' parameter as well. `top' The screen position of the top edge, in pixels, with respect to the top edge of the screen. The value may be a positive number POS, or a list of the form `(+ POS)' which permits specifying a negative POS value. A negative number -POS, or a list of the form `(- POS)', actually specifies the position of the bottom edge of the window with respect to the bottom edge of the screen. A positive value of POS counts toward the top. *Reminder:* if the parameter is a negative integer -POS, then POS is positive. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-`nil' value for the `user-position' parameter as well. `icon-left' The screen position of the left edge *of the frame's icon*, in pixels, counting from the left edge of the screen. This takes effect if and when the frame is iconified. `icon-top' The screen position of the top edge *of the frame's icon*, in pixels, counting from the top edge of the screen. This takes effect if and when the frame is iconified. `user-position' When you create a frame and specify its screen position with the `left' and `top' parameters, use this parameter to say whether the specified position was user-specified (explicitly requested in some way by a human user) or merely program-specified (chosen by a program). A non-`nil' value says the position was user-specified. Window managers generally heed user-specified positions, and some heed program-specified positions too. But many ignore program-specified positions, placing the window in a default fashion or letting the user place it with the mouse. Some window managers, including `twm', let the user specify whether to obey program-specified positions or ignore them. When you call `make-frame', you should specify a non-`nil' value for this parameter if the values of the `left' and `top' parameters represent the user's stated preference; otherwise, use `nil'. `height' The height of the frame contents, in characters. (To get the height in pixels, call `frame-pixel-height'; see *Note Size and Position::.) `width' The width of the frame contents, in characters. (To get the height in pixels, call `frame-pixel-width'; see *Note Size and Position::.) `window-id' The number of the window-system window used by the frame. `minibuffer' Whether this frame has its own minibuffer. The value `t' means yes, `nil' means no, `only' means this frame is just a minibuffer. If the value is a minibuffer window (in some other frame), the new frame uses that minibuffer. `buffer-predicate' The buffer-predicate function for this frame. The function `other-buffer' uses this predicate (from the selected frame) to decide which buffers it should consider, if the predicate is not `nil'. It calls the predicate with one argument, a buffer, once for each buffer; if the predicate returns a non-`nil' value, it considers that buffer. `buffer-list' A list of buffers that have been selected in this frame, ordered most-recently-selected first. `font' The name of the font for displaying text in the frame. This is a string, either a valid font name for your system or the name of an Emacs fontset (*note Fontsets::.). `auto-raise' Whether selecting the frame raises it (non-`nil' means yes). `auto-lower' Whether deselecting the frame lowers it (non-`nil' means yes). `vertical-scroll-bars' Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are `left', `right', and `nil' for no scroll bars. `horizontal-scroll-bars' Whether the frame has scroll bars for horizontal scrolling (non-`nil' means yes). (Horizontal scroll bars are not currently implemented.) `scroll-bar-width' The width of the vertical scroll bar, in pixels. `icon-type' The type of icon to use for this frame when it is iconified. If the value is a string, that specifies a file containing a bitmap to use. Any other non-`nil' value specifies the default bitmap icon (a picture of a gnu); `nil' specifies a text icon. `icon-name' The name to use in the icon for this frame, when and if the icon appears. If this is `nil', the frame's title is used. `foreground-color' The color to use for the image of a character. This is a string; the window system defines the meaningful color names. If you set the `foreground-color' frame parameter, you should call `frame-update-face-colors' to update faces accordingly. `background-color' The color to use for the background of characters. If you set the `background-color' frame parameter, you should call `frame-update-face-colors' to update faces accordingly. *Note Face Functions::. `background-mode' This parameter is either `dark' or `light', according to whether the background color is a light one or a dark one. `mouse-color' The color for the mouse pointer. `cursor-color' The color for the cursor that shows point. `border-color' The color for the border of the frame. `display-type' This parameter describes the range of possible colors that can be used in this frame. Its value is `color', `grayscale' or `mono'. `cursor-type' The way to display the cursor. The legitimate values are `bar', `box', and `(bar . WIDTH)'. The symbol `box' specifies an ordinary black box overlaying the character after point; that is the default. The symbol `bar' specifies a vertical bar between characters as the cursor. `(bar . WIDTH)' specifies a bar WIDTH pixels wide. `border-width' The width in pixels of the window border. `internal-border-width' The distance in pixels between text and border. `unsplittable' If non-`nil', this frame's window is never split automatically. `visibility' The state of visibility of the frame. There are three possibilities: `nil' for invisible, `t' for visible, and `icon' for iconified. *Note Visibility of Frames::. `menu-bar-lines' The number of lines to allocate at the top of the frame for a menu bar. The default is 1. *Note Menu Bar::. (In Emacs versions that use the X toolkit, there is only one menu bar line; all that matters about the number you specify is whether it is greater than zero.)  File: elisp, Node: Size and Position, Prev: Window Frame Parameters, Up: Frame Parameters Frame Size And Position ----------------------- You can read or change the size and position of a frame using the frame parameters `left', `top', `height', and `width'. Whatever geometry parameters you don't specify are chosen by the window manager in its usual fashion. Here are some special features for working with sizes and positions: - Function: set-frame-position FRAME LEFT TOP This function sets the position of the top left corner of FRAME to LEFT and TOP. These arguments are measured in pixels, and normally count from the top left corner of the screen. Negative parameter values position the bottom edge of the window up from the bottom edge of the screen, or the right window edge to the left of the right edge of the screen. It would probably be better if the values were always counted from the left and top, so that negative arguments would position the frame partly off the top or left edge of the screen, but it seems inadvisable to change that now. - Function: frame-height &optional FRAME - Function: frame-width &optional FRAME These functions return the height and width of FRAME, measured in lines and columns. If you don't supply FRAME, they use the selected frame. - Function: screen-height - Function: screen-width These functions are old aliases for `frame-height' and `frame-width'. When you are using a non-window terminal, the size of the frame is normally the same as the size of the terminal screen. - Function: frame-pixel-height &optional FRAME - Function: frame-pixel-width &optional FRAME These functions return the height and width of FRAME, measured in pixels. If you don't supply FRAME, they use the selected frame. - Function: frame-char-height &optional FRAME - Function: frame-char-width &optional FRAME These functions return the height and width of a character in FRAME, measured in pixels. The values depend on the choice of font. If you don't supply FRAME, these functions use the selected frame. - Function: set-frame-size FRAME COLS ROWS This function sets the size of FRAME, measured in characters; COLS and ROWS specify the new width and height. To set the size based on values measured in pixels, use `frame-char-height' and `frame-char-width' to convert them to units of characters. - Function: set-frame-height FRAME LINES &optional PRETEND This function resizes FRAME to a height of LINES lines. The sizes of existing windows in FRAME are altered proportionally to fit. If PRETEND is non-`nil', then Emacs displays LINES lines of output in FRAME, but does not change its value for the actual height of the frame. This is only useful for a terminal frame. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame height "for real" does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on a terminal frame. - Function: set-frame-width FRAME WIDTH &optional PRETEND This function sets the width of FRAME, measured in characters. The argument PRETEND has the same meaning as in `set-frame-height'. The older functions `set-screen-height' and `set-screen-width' were used to specify the height and width of the screen, in Emacs versions that did not support multiple frames. They are semi-obsolete, but still work; they apply to the selected frame. - Function: x-parse-geometry GEOM The function `x-parse-geometry' converts a standard X window geometry string to an alist that you can use as part of the argument to `make-frame'. The alist describes which parameters were specified in GEOM, and gives the values specified for them. Each element looks like `(PARAMETER . VALUE)'. The possible PARAMETER values are `left', `top', `width', and `height'. For the size parameters, the value must be an integer. The position parameter names `left' and `top' are not totally accurate, because some values indicate the position of the right or bottom edges instead. These are the VALUE possibilities for the position parameters: an integer A positive integer relates the left edge or top edge of the window to the left or top edge of the screen. A negative integer relates the right or bottom edge of the window to the right or bottom edge of the screen. `(+ POSITION)' This specifies the position of the left or top edge of the window relative to the left or top edge of the screen. The integer POSITION may be positive or negative; a negative value specifies a position outside the screen. `(- POSITION)' This specifies the position of the right or bottom edge of the window relative to the right or bottom edge of the screen. The integer POSITION may be positive or negative; a negative value specifies a position outside the screen. Here is an example: (x-parse-geometry "35x70+0-0") => ((height . 70) (width . 35) (top - 0) (left . 0))  File: elisp, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Parameters, Up: Frames Frame Titles ============ Every frame has a `name' parameter; this serves as the default for the frame title which window systems typically display at the top of the frame. You can specify a name explicitly by setting the `name' frame property. Normally you don't specify the name explicitly, and Emacs computes the frame name automatically based on a template stored in the variable `frame-title-format'. Emacs recomputes the name each time the frame is redisplayed. - Variable: frame-title-format This variable specifies how to compute a name for a frame when you have not explicitly specified one. The variable's value is actually a mode line construct, just like `mode-line-format'. *Note Mode Line Data::. - Variable: icon-title-format This variable specifies how to compute the name for an iconified frame, when you have not explicitly specified the frame title. This title appears in the icon itself. - Variable: multiple-frames This variable is set automatically by Emacs. Its value is `t' when there are two or more frames (not counting minibuffer-only frames or invisible frames). The default value of `frame-title-format' uses `multiple-frames' so as to put the buffer name in the frame title only when there is more than one frame.  File: elisp, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames Deleting Frames =============== Frames remain potentially visible until you explicitly "delete" them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a frame aside from restoring a saved frame configuration (*note Frame Configurations::.); this is similar to the way windows behave. - Command: delete-frame &optional FRAME This function deletes the frame FRAME. By default, FRAME is the selected frame. - Function: frame-live-p FRAME The function `frame-live-p' returns non-`nil' if the frame FRAME has not been deleted. Some window managers provide a command to delete a window. These work by sending a special message to the program that operates the window. When Emacs gets one of these commands, it generates a `delete-frame' event, whose normal definition is a command that calls the function `delete-frame'. *Note Misc Events::.  File: elisp, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames Finding All Frames ================== - Function: frame-list The function `frame-list' returns a list of all the frames that have not been deleted. It is analogous to `buffer-list' for buffers. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of Emacs. - Function: visible-frame-list This function returns a list of just the currently visible frames. *Note Visibility of Frames::. (Terminal frames always count as "visible", even though only the selected one is actually displayed.) - Function: next-frame &optional FRAME MINIBUF The function `next-frame' lets you cycle conveniently through all the frames from an arbitrary starting point. It returns the "next" frame after FRAME in the cycle. If FRAME is omitted or `nil', it defaults to the selected frame. The second argument, MINIBUF, says which frames to consider: `nil' Exclude minibuffer-only frames. `visible' Consider all visible frames. 0 Consider all visible or iconified frames. a window Consider only the frames using that particular window as their minibuffer. anything else Consider all frames. - Function: previous-frame &optional FRAME MINIBUF Like `next-frame', but cycles through all frames in the opposite direction. See also `next-window' and `previous-window', in *Note Cyclic Window Ordering::.  File: elisp, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames Frames and Windows ================== Each window is part of one and only one frame; you can get the frame with `window-frame'. - Function: window-frame WINDOW This function returns the frame that WINDOW is on. All the non-minibuffer windows in a frame are arranged in a cyclic order. The order runs from the frame's top window, which is at the upper left corner, down and to the right, until it reaches the window at the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top. *Note Cyclic Window Ordering::. - Function: frame-top-window FRAME This returns the topmost, leftmost window of frame FRAME. At any time, exactly one window on any frame is "selected within the frame". The significance of this designation is that selecting the frame also selects this window. You can get the frame's current selected window with `frame-selected-window'. - Function: frame-selected-window FRAME This function returns the window on FRAME that is selected within FRAME. Conversely, selecting a window for Emacs with `select-window' also makes that window selected within its frame. *Note Selecting Windows::. Another function that (usually) returns one of the windows in a given frame is `minibuffer-window'. *Note Minibuffer Misc::.  File: elisp, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames Minibuffers and Frames ====================== Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. If the frame has a minibuffer, you can get it with `minibuffer-window' (*note Minibuffer Misc::.). However, you can also create a frame with no minibuffer. Such a frame must use the minibuffer window of some other frame. When you create the frame, you can specify explicitly the minibuffer window to use (in some other frame). If you don't, then the minibuffer is found in the frame which is the value of the variable `default-minibuffer-frame'. Its value should be a frame that does have a minibuffer. If you use a minibuffer-only frame, you might want that frame to raise when you enter the minibuffer. If so, set the variable `minibuffer-auto-raise' to `t'. *Note Raising and Lowering::. - Variable: default-minibuffer-frame This variable specifies the frame to use for the minibuffer window, by default. It is always local to the current terminal and cannot be buffer-local. *Note Multiple Displays::.  File: elisp, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames Input Focus =========== At any time, one frame in Emacs is the "selected frame". The selected window always resides on the selected frame. - Function: selected-frame This function returns the selected frame. Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to "shift the focus" to various window objects. Either way, Emacs automatically keeps track of which frame has the focus. Lisp programs can also switch frames "temporarily" by calling the function `select-frame'. This does not alter the window system's concept of focus; rather, it escapes from the window manager's control until that control is somehow reasserted. When using a text-only terminal, only the selected terminal frame is actually displayed on the terminal. `switch-frame' is the only way to switch frames, and the change lasts until overridden by a subsequent call to `switch-frame'. Each terminal screen except for the initial one has a number, and the number of the selected frame appears in the mode line before the buffer name (*note Mode Line Variables::.). - Function: select-frame FRAME This function selects frame FRAME, temporarily disregarding the focus of the X server if any. The selection of FRAME lasts until the next time the user does something to select a different frame, or until the next time this function is called. Emacs cooperates with the window system by arranging to select frames as the server and window manager request. It does so by generating a special kind of input event, called a "focus" event, when appropriate. The command loop handles a focus event by calling `handle-switch-frame'. *Note Focus Events::. - Command: handle-switch-frame FRAME This function handles a focus event by selecting frame FRAME. Focus events normally do their job by invoking this command. Don't call it for any other reason. - Function: redirect-frame-focus FRAME FOCUS-FRAME This function redirects focus from FRAME to FOCUS-FRAME. This means that FOCUS-FRAME will receive subsequent keystrokes and events intended for FRAME. After such an event, the value of `last-event-frame' will be FOCUS-FRAME. Also, switch-frame events specifying FRAME will instead select FOCUS-FRAME. If FOCUS-FRAME is `nil', that cancels any existing redirection for FRAME, which therefore once again receives its own events. One use of focus redirection is for frames that don't have minibuffers. These frames use minibuffers on other frames. Activating a minibuffer on another frame redirects focus to that frame. This puts the focus on the minibuffer's frame, where it belongs, even though the mouse remains in the frame that activated the minibuffer. Selecting a frame can also change focus redirections. Selecting frame `bar', when `foo' had been selected, changes any redirections pointing to `foo' so that they point to `bar' instead. This allows focus redirection to work properly when the user switches from one frame to another using `select-window'. This means that a frame whose focus is redirected to itself is treated differently from a frame whose focus is not redirected. `select-frame' affects the former but not the latter. The redirection lasts until `redirect-frame-focus' is called to change it. - User Option: focus-follows-mouse This option is how you inform Emacs whether the window manager transfers focus when the user moves the mouse. Non-`nil' says that it does. When this is so, the command `other-frame' moves the mouse to a position consistent with the new selected frame.