29.4.3 Window Frame Parameters
Just what parameters a frame has depends on what display mechanism it uses. This section describes the parameters that have special meanings on some or all kinds of terminals. Of these, name, title, height, width, buffer-list and buffer-predicate provide meaningful information in terminal frames, and tty-color-mode is meaningful only for frames on text terminals.
| • Basic Parameters |   | Parameters that are fundamental. |
| • Position Parameters |   | The position of the frame on the screen. |
| • Size Parameters |   | Frame’s size. |
| • Layout Parameters |   | Size of parts of the frame, and enabling or disabling some parts. |
| • Buffer Parameters |   | Which buffers have been or should be shown. |
| • Frame Interaction Parameters |   | Parameters for interacting with other frames. |
| • Mouse Dragging Parameters |   | Parameters for resizing and moving frames with the mouse. |
| • Management Parameters |   | Communicating with the window manager. |
| • Cursor Parameters |   | Controlling the cursor appearance. |
| • Font and Color Parameters |   | Fonts and colors for the frame text. |
29.4.3.1 Basic Parameters​
These frame parameters give the most basic information about the frame. title and name are meaningful on all terminals.
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. See Multiple Terminals, for more details about display names.
display-type​
This parameter describes the range of possible colors that can be used in this frame. Its value is color, grayscale or mono.
title​
If a frame has a non-nil title, it appears in the window system’s title bar at the top of the frame, and also in the mode line of windows in that frame if mode-line-frame-identification uses ‘%F’ (see %-Constructs). This is normally the case when Emacs is not using a window system, and can only display one frame at a time. See 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 (see 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.
explicit-name​
If the frame name was specified explicitly when the frame was created, this parameter will be that name. If the frame wasn’t explicitly named, this parameter will be nil.
29.4.3.2 Position Parameters​
Parameters describing the X- and Y-offsets of a frame are always measured in pixels. For a normal, non-child frame they specify the frame’s outer position (see Frame Geometry) relative to its display’s origin. For a child frame (see Child Frames) they specify the frame’s outer position relative to the native position of the frame’s parent frame. (Note that none of these parameters is meaningful on TTY frames.)
left​
The position, in pixels, of the left outer edge of the frame with respect to the left edge of the frame’s display or parent frame. It can be specified in one of the following ways.
an integer​
A positive integer always relates the left edge of the frame to the left edge of its display or parent frame. A negative integer relates the right frame edge to the right edge of the display or parent frame.
(+ pos)​
This specifies the position of the left frame edge relative to the left edge of its display or parent frame. The integer pos may be positive or negative; a negative value specifies a position outside the screen or parent frame or on a monitor other than the primary one (for multi-monitor displays).
(- pos)​
This specifies the position of the right frame edge relative to the right edge of the display or parent frame. The integer pos may be positive or negative; a negative value specifies a position outside the screen or parent frame or on a monitor other than the primary one (for multi-monitor displays).
a floating-point value​
A floating-point value in the range 0.0 to 1.0 specifies the left edge’s offset via the left position ratio of the frame—the ratio of the left edge of its outer frame to the width of the frame’s workarea (see Multiple Terminals) or its parent’s native frame (see Child Frames) minus the width of the outer frame. Thus, a left position ratio of 0.0 flushes a frame to the left, a ratio of 0.5 centers it and a ratio of 1.0 flushes it to the right of its display or parent frame. Similarly, the top position ratio of a frame is the ratio of the frame’s top position to the height of its workarea or parent frame minus the height of the frame.
Emacs will try to keep the position ratios of a child frame unaltered if that frame has a non-nil keep-ratio parameter (see Frame Interaction Parameters) and its parent frame is resized.
Since the outer size of a frame (see Frame Geometry) is usually unavailable before a frame has been made visible, it is generally not advisable to use floating-point values when creating decorated frames. Floating-point values are more suited for ensuring that an (undecorated) child frame is positioned nicely within the area of its parent frame.
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 in the following example:
(modify-frame-parameters
nil '((user-position . t) (left . (+ -4))))
In general, it is not a good idea to position a frame relative to the right or bottom edge of its display. Positioning the initial or a new frame is either not accurate (because the size of the outer frame is not yet fully known before the frame has been made visible) or will cause additional flicker (if the frame has to be repositioned after becoming visible).
Note also, that positions specified relative to the right/bottom edge of a display, workarea or parent frame as well as floating-point offsets are stored internally as integer offsets relative to the left/top edge of the display, workarea or parent frame edge. They are also returned as such by functions like frame-parameters and restored as such by the desktop saving routines.
top​
The screen position of the top (or bottom) edge, in pixels, with respect to the top (or bottom) edge of the display or parent frame. It works just like left, except vertically instead of horizontally.
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 when the frame is iconified, if the window manager supports this feature. If you specify a value for this parameter, then you must also specify a value for icon-top and vice versa.
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 when the frame is iconified, if the window manager supports this feature.
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.
z-group​
This parameter specifies a relative position of the frame’s window-system window in the stacking (Z-) order of the frame’s display.
If this is above, the window-system will display the window that corresponds to the frame above all other window-system windows that do not have the above property set. If this is nil, the frame’s window is displayed below all windows that have the above property set and above all windows that have the below property set. If this is below, the frame’s window is displayed below all windows that do not have the below property set.
To position the frame above or below a specific other frame use the function frame-restack (see Raising and Lowering).
29.4.3.3 Size Parameters​
Frame parameters usually specify frame sizes in character units. On graphical displays, the default face determines the actual pixel sizes of these character units (see Face Attributes).
width​
This parameter specifies the width of the frame. It can be specified as in the following ways:
an integer​
A positive integer specifies the width of the frame’s text area (see Frame Geometry) in characters.
a cons cell​
If this is a cons cell with the symbol text-pixels in its CAR, the CDR of that cell specifies the width of the frame’s text area in pixels.
a floating-point value​
A floating-point number between 0.0 and 1.0 can be used to specify the width of a frame via its width ratio—the ratio of its outer width (see Frame Geometry) to the width of the frame’s workarea (see Multiple Terminals) or its parent frame’s (see Child Frames) native frame. Thus, a value of 0.5 makes the frame occupy half of the width of its workarea or parent frame, a value of 1.0 the full width. Similarly, the height ratio of a frame is the ratio of its outer height to the height of its workarea or its parent’s native frame.
Emacs will try to keep the width and height ratio of a child frame unaltered if that frame has a non-nil keep-ratio parameter (see Frame Interaction Parameters) and its parent frame is resized.
Since the outer size of a frame is usually unavailable before a frame has been made visible, it is generally not advisable to use floating-point values when creating decorated frames. Floating-point values are more suited to ensure that a child frame always fits within the area of its parent frame as, for example, when customizing display-buffer-alist (see Choosing Window) via display-buffer-in-child-frame.
Regardless of how this parameter was specified, functions reporting the value of this parameter like frame-parameters always report the width of the frame’s text area in characters as an integer rounded, if necessary, to a multiple of the frame’s default character width. That value is also used by the desktop saving routines.
height​
This parameter specifies the height of the frame. It works just like width, except vertically instead of horizontally.
user-size​
This does for the size parameters height and width what the user-position parameter (see user-position) does for the position parameters top and left.
min-width​
This parameter specifies the minimum native width (see Frame Geometry) of the frame, in characters. Normally, the functions that establish a frame’s initial width or resize a frame horizontally make sure that all the frame’s windows, vertical scroll bars, fringes, margins and vertical dividers can be displayed. This parameter, if non-nil allows to make a frame narrower than that with the consequence that any components that do not fit will be clipped by the window manager.
min-height​
This parameter specifies the minimum native height (see Frame Geometry) of the frame, in characters. Normally, the functions that establish a frame’s initial size or resize a frame make sure that all the frame’s windows, horizontal scroll bars and dividers, mode and header lines, the echo area and the internal menu and tool bar can be displayed. This parameter, if non-nil allows to make a frame smaller than that with the consequence that any components that do not fit will be clipped by the window manager.
fullscreen​
This parameter specifies whether to maximize the frame’s width, height or both. Its value can be fullwidth, fullheight, fullboth, or maximized. A fullwidth frame is as wide as possible, a fullheight frame is as tall as possible, and a fullboth frame is both as wide and as tall as possible. A maximized frame is like a “fullboth" frame, except that it usually keeps its title bar and the buttons for resizing and closing the frame. Also, maximized frames typically avoid hiding any task bar or panels displayed on the desktop. A “fullboth" frame, on the other hand, usually omits the title bar and occupies the entire available screen space.
Full-height and full-width frames are more similar to maximized frames in this regard. However, these typically display an external border which might be absent with maximized frames. Hence the heights of maximized and full-height frames and the widths of maximized and full-width frames often differ by a few pixels.
With some window managers you may have to customize the variable frame-resize-pixelwise (see Frame Size) in order to make a frame truly appear maximized or full-screen. Moreover, some window managers might not support smooth transition between the various full-screen or maximization states. Customizing the variable x-frame-normalize-before-maximize can help to overcome that.
Full-screen on macOS hides both the tool-bar and the menu-bar, however both will be displayed if the mouse pointer is moved to the top of the screen.
fullscreen-restore​
This parameter specifies the desired fullscreen state of the frame after invoking the toggle-frame-fullscreen command (see Frame Commands in The GNU Emacs Manual) in the “fullboth" state. Normally this parameter is installed automatically by that command when toggling the state to fullboth. If, however, you start Emacs in the “fullboth" state, you have to specify the desired behavior in your initial file as, for example
(setq default-frame-alist
'((fullscreen . fullboth)
(fullscreen-restore . fullheight)))
This will give a new frame full height after typing in it F11 for the first time.
fit-frame-to-buffer-margins​
This parameter allows to override the value of the option fit-frame-to-buffer-margins when fitting this frame to the buffer of its root window with fit-frame-to-buffer (see Resizing Windows).
fit-frame-to-buffer-sizes​
This parameter allows to override the value of the option fit-frame-to-buffer-sizes when fitting this frame to the buffer of its root window with fit-frame-to-buffer (see Resizing Windows).
29.4.3.4 Layout Parameters​
These frame parameters enable or disable various parts of the frame, or control their sizes.
border-width​
The width in pixels of the frame’s outer border (see Frame Geometry).
internal-border-width​
The width in pixels of the frame’s internal border (see Frame Geometry).
vertical-scroll-bars​
Whether the frame has scroll bars (see 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 (t and bottom mean yes, nil means no).
scroll-bar-width​
The width of vertical scroll bars, in pixels, or nil meaning to use the default width.
scroll-bar-height​
The height of horizontal scroll bars, in pixels, or nil meaning to use the default height.
left-fringe​
right-fringe​
The default width of the left and right fringes of windows in this frame (see Fringes). If either of these is zero, that effectively removes the corresponding fringe.
When you use frame-parameter to query the value of either of these two frame parameters, the return value is always an integer. When using set-frame-parameter, passing a nil value imposes an actual default value of 8 pixels.
right-divider-width​
The width (thickness) reserved for the right divider (see Window Dividers) of any window on the frame, in pixels. A value of zero means to not draw right dividers.
bottom-divider-width​
The width (thickness) reserved for the bottom divider (see Window Dividers) of any window on the frame, in pixels. A value of zero means to not draw bottom dividers.
menu-bar-lines​
The number of lines to allocate at the top of the frame for a menu bar (see Menu Bar). The default is one if Menu Bar mode is enabled and zero otherwise. See Menu Bars in The GNU Emacs Manual. For an external menu bar (see Frame Layout), this value remains unchanged even when the menu bar wraps to two or more lines. In that case, the menu-bar-size value returned by frame-geometry (see Frame Geometry) allows to derive whether the menu bar actually occupies one or more lines.
tool-bar-lines​
The number of lines to use for the tool bar (see Tool Bar). The default is one if Tool Bar mode is enabled and zero otherwise. See Tool Bars in The GNU Emacs Manual. This value may change whenever the tool bar wraps (see Frame Layout).
tool-bar-position​
The position of the tool bar when Emacs was built with GTK+. Its value can be one of top, bottom left, right. The default is top.
line-spacing​
Additional space to leave below each text line, in pixels (a positive integer). See Line Height, for more information.
no-special-glyphs​
If this is non-nil, it suppresses the display of any truncation and continuation glyphs (see Truncation) for all buffers displayed by this frame. This is useful to eliminate such glyphs when fitting a frame to its buffer via fit-frame-to-buffer (see Resizing Windows).
29.4.3.5 Buffer Parameters​
These frame parameters, meaningful on all kinds of terminals, deal with which buffers have been, or should, be displayed in 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 frame uses that minibuffer.
This parameter takes effect when the frame is created. If specified as nil, Emacs will try to set it to the minibuffer window of default-minibuffer-frame (see Minibuffers and Frames). For an existing frame, this parameter can be used exclusively to specify another minibuffer window. It is not allowed to change it from a minibuffer window to t and vice-versa, or from t to nil. If the parameter specifies a minibuffer window already, setting it to nil has no effect.
The special value child-frame means to make a minibuffer-only child frame (see Child Frames) whose parent becomes the frame created. As if specified as nil, Emacs will set this parameter to the minibuffer window of the child frame but will not select the child frame after its creation.
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.
unsplittable​
If non-nil, this frame’s window is never split automatically.
29.4.3.6 Frame Interaction Parameters​
These parameters supply forms of interactions between different frames.
parent-frame​
If non-nil, this means that this frame is a child frame (see Child Frames), and this parameter specifies its parent frame. If nil, this means that this frame is a normal, top-level frame.
delete-before​
If non-nil, this parameter specifies another frame whose deletion will automatically trigger the deletion of this frame. See Deleting Frames.
mouse-wheel-frame​
If non-nil, this parameter specifies the frame whose windows will be scrolled whenever the mouse wheel is scrolled with the mouse pointer hovering over this frame, see Mouse Commands in The GNU Emacs Manual.
no-other-frame​
If this is non-nil, then this frame is not eligible as candidate for the functions next-frame, previous-frame (see Finding All Frames) and other-frame, see Frame Commands in The GNU Emacs Manual.
auto-hide-function​
When this parameter specifies a function, that function will be called instead of the function specified by the variable frame-auto-hide-function when quitting the frame’s only window (see Quitting Windows) and there are other frames left.
minibuffer-exit​
When this parameter is non-nil, Emacs will by default make this frame invisible whenever the minibuffer (see Minibuffers) is exited. Alternatively, it can specify the functions iconify-frame and delete-frame. This parameter is useful to make a child frame disappear automatically (similar to how Emacs deals with a window) when exiting the minibuffer.
keep-ratio​
This parameter is currently meaningful for child frames (see Child Frames) only. If it is non-nil, then Emacs will try to keep the frame’s size (width and height) ratios (see Size Parameters) as well as its left and right position ratios (see Position Parameters) unaltered whenever its parent frame is resized.
If the value of this parameter is nil, the frame’s position and size remain unaltered when the parent frame is resized, so the position and size ratios may change. If the value of this parameter is t, Emacs will try to preserve the frame’s size and position ratios, hence the frame’s size and position relative to its parent frame may change.
More individual control is possible by using a cons cell: In that case the frame’s width ratio is preserved if the CAR of the cell is either t or width-only. The height ratio is preserved if the CAR of the cell is either t or height-only. The left position ratio is preserved if the CDR of the cell is either t or left-only. The top position ratio is preserved if the CDR of the cell is either t or top-only.
29.4.3.7 Mouse Dragging Parameters​
The parameters described below provide support for resizing a frame by dragging its internal borders with the mouse. They also allow moving a frame with the mouse by dragging the header line of its topmost or the mode line of its bottommost window.
These parameters are mostly useful for child frames (see Child Frames) that come without window manager decorations. If necessary, they can be used for undecorated top-level frames as well.
drag-internal-border​
If non-nil, the frame can be resized by dragging its internal borders, if present, with the mouse.
drag-with-header-line​
If non-nil, the frame can be moved with the mouse by dragging the header line of its topmost window.
drag-with-mode-line​
If non-nil, the frame can be moved with the mouse by dragging the mode line of its bottommost window. Note that such a frame is not allowed to have its own minibuffer window.
snap-width​
A frame that is moved with the mouse will “snap" at the border(s) of the display or its parent frame whenever it is dragged as near to such an edge as the number of pixels specified by this parameter.
top-visible​
If this parameter is a number, the top edge of the frame never appears above the top edge of its display or parent frame. Moreover, as many pixels of the frame as specified by that number will remain visible when the frame is moved against any of the remaining edges of its display or parent frame. Setting this parameter is useful to guard against dragging a child frame with a non-nil drag-with-header-line parameter completely out of the area of its parent frame.
bottom-visible​
If this parameter is a number, the bottom edge of the frame never appears below the bottom edge of its display or parent frame. Moreover, as many pixels of the frame as specified by that number will remain visible when the frame is moved against any of the remaining edges of its display or parent frame. Setting this parameter is useful to guard against dragging a child frame with a non-nil drag-with-mode-line parameter completely out of the area of its parent frame.
29.4.3.8 Window Management Parameters​
The following frame parameters control various aspects of the frame’s interaction with the window manager or window system. They have no effect on text terminals.
visibility​
The state of visibility of the frame. There are three possibilities: nil for invisible, t for visible, and icon for iconified. See Visibility of Frames.
auto-raise​
If non-nil, Emacs automatically raises the frame when it is selected. Some window managers do not allow this.
auto-lower​
If non-nil, Emacs automatically lowers the frame when it is deselected. Some window managers do not allow this.
icon-type​
The type of icon to use for this frame. If the value is a string, that specifies a file containing a bitmap to use; nil specifies no icon (in which case the window manager decides what to show); any other non-nil value specifies the default Emacs 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.
window-id​
The ID number which the graphical display uses for this frame. Emacs assigns this parameter when the frame is created; changing the parameter has no effect on the actual ID number.
outer-window-id​
The ID number of the outermost window-system window in which the frame exists. As with window-id, changing this parameter has no actual effect.
wait-for-wm​
If non-nil, tell Xt to wait for the window manager to confirm geometry changes. Some window managers, including versions of Fvwm2 and KDE, fail to confirm, so Xt hangs. Set this to nil to prevent hanging with those window managers.
sticky​
If non-nil, the frame is visible on all virtual desktops on systems with virtual desktops.
inhibit-double-buffering​
If non-nil, the frame is drawn to the screen without double buffering. Emacs normally attempts to use double buffering, where available, to reduce flicker. Set this property if you experience display bugs or pine for that retro, flicker-y feeling.
skip-taskbar​
If non-nil, this tells the window manager to remove the frame’s icon from the taskbar associated with the frame’s display and inhibit switching to the frame’s window via the combination Alt-TAB. On MS-Windows, iconifying such a frame will "roll in" its window-system window at the bottom of the desktop. Some window managers may not honor this parameter.
no-focus-on-map​
If non-nil, this means that the frame does not want to receive input focus when it is mapped (see Visibility of Frames). Some window managers may not honor this parameter.
no-accept-focus​
If non-nil, this means that the frame does not want to receive input focus via explicit mouse clicks or when moving the mouse into it either via focus-follows-mouse (see Input Focus) or mouse-autoselect-window (see Mouse Window Auto-selection). This may have the unwanted side-effect that a user cannot scroll a non-selected frame with the mouse. Some window managers may not honor this parameter.
undecorated​
If non-nil, this frame’s window-system window is drawn without decorations, like the title, minimize/maximize boxes and external borders. This usually means that the window cannot be dragged, resized, iconified, maximized or deleted with the mouse. If nil, the frame’s window is usually drawn with all the elements listed above unless their display has been suspended via window manager settings.
Under X, Emacs uses the Motif window manager hints to turn off decorations. Some window managers may not honor these hints.
NS builds consider the tool bar to be a decoration, and therefore hide it on an undecorated frame.
override-redirect​
If non-nil, this means that this is an override redirect frame—a frame not handled by window managers under X. Override redirect frames have no window manager decorations, can be positioned and resized only via Emacs’ positioning and resizing functions and are usually drawn on top of all other frames. Setting this parameter has no effect on MS-Windows.
ns-appearance​
Only available on macOS, if set to dark draw this frame’s window-system window using the “vibrant dark" theme, otherwise use the system default. The “vibrant dark" theme can be used to set the toolbar and scrollbars to a dark appearance when using an Emacs theme with a dark background.
ns-transparent-titlebar​
Only available on macOS, if non-nil, set the titlebar and toolbar to be transparent. This effectively sets the background color of both to match the Emacs background color.
29.4.3.9 Cursor Parameters​
This frame parameter controls the way the cursor looks.
cursor-type​
How to display the cursor. Legitimate values are:
box​
Display a filled box. (This is the default.)
hollow​
Display a hollow box.
nil​
Don’t display a cursor.
bar​
Display a vertical bar between characters.
(bar . width)​
Display a vertical bar width pixels wide between characters.
hbar​
Display a horizontal bar.
(hbar . height)​
Display a horizontal bar height pixels high.
The cursor-type frame parameter may be overridden by the variables cursor-type and cursor-in-non-selected-windows:
user option cursor-type​
This buffer-local variable controls how the cursor looks in a selected window showing the buffer. If its value is t, that means to use the cursor specified by the cursor-type frame parameter. Otherwise, the value should be one of the cursor types listed above, and it overrides the cursor-type frame parameter.
user option cursor-in-non-selected-windows​
This buffer-local variable controls how the cursor looks in a window that is not selected. It supports the same values as the cursor-type frame parameter; also, nil means don’t display a cursor in nonselected windows, and t (the default) means use a standard modification of the usual cursor type (solid box becomes hollow box, and bar becomes a narrower bar).
user option x-stretch-cursor​
This variable controls the width of the block cursor displayed on extra-wide glyphs such as a tab or a stretch of white space. By default, the block cursor is only as wide as the font’s default character, and will not cover all of the width of the glyph under it if that glyph is extra-wide. A non-nil value of this variable means draw the block cursor as wide as the glyph under it. The default value is nil.
This variable has no effect on text-mode frames, since the text-mode cursor is drawn by the terminal out of Emacs’s control.
user option blink-cursor-alist​
This variable specifies how to blink the cursor. Each element has the form (on-state . off-state). Whenever the cursor type equals on-state (comparing using equal), the corresponding off-state specifies what the cursor looks like when it blinks off. Both on-state and off-state should be suitable values for the cursor-type frame parameter.
There are various defaults for how to blink each type of cursor, if the type is not mentioned as an on-state here. Changes in this variable do not take effect immediately, only when you specify the cursor-type frame parameter.
29.4.3.10 Font and Color Parameters​
These frame parameters control the use of fonts and colors.
font-backend​
A list of symbols, specifying the font backends to use for drawing characters on the frame, in order of priority. In Emacs built without Cairo drawing on X, there are currently three potentially available font backends: x (the X core font driver), xft (the Xft font driver), and xfthb (the Xft font driver with HarfBuzz text shaping). If built with Cairo drawing, there are also three potentially available font backends on X: x, ftcr (the FreeType font driver on Cairo), and ftcrhb (the FreeType font driver on Cairo with HarfBuzz text shaping). When Emacs is built with HarfBuzz, the default font driver is ftcrhb, although use of the ftcr driver is still possible, but not recommended. On MS-Windows, there are currently three available font backends: gdi (the core MS-Windows font driver), uniscribe (font driver for OTF and TTF fonts with text shaping by the Uniscribe engine), and harfbuzz (font driver for OTF and TTF fonts with HarfBuzz text shaping) (see Windows Fonts in The GNU Emacs Manual). The harfbuzz driver is similarly recommended. On other systems, there is only one available font backend, so it does not make sense to modify this frame parameter.
background-mode​
This parameter is either dark or light, according to whether the background color is a light one or a dark one.
tty-color-mode​
This parameter overrides the terminal’s color support as given by the system’s terminal capabilities database in that this parameter’s value specifies the color mode to use on a text terminal. The value can be either a symbol or a number. A number specifies the number of colors to use (and, indirectly, what commands to issue to produce each color). For example, (tty-color-mode . 8) specifies use of the ANSI escape sequences for 8 standard text colors. A value of -1 turns off color support.
If the parameter’s value is a symbol, it specifies a number through the value of tty-color-mode-alist, and the associated number is used instead.
screen-gamma​
If this is a number, Emacs performs gamma correction which adjusts the brightness of all colors. The value should be the screen gamma of your display.
Usual PC monitors have a screen gamma of 2.2, so color values in Emacs, and in X windows generally, are calibrated to display properly on a monitor with that gamma value. If you specify 2.2 for screen-gamma, that means no correction is needed. Other values request correction, designed to make the corrected colors appear on your screen the way they would have appeared without correction on an ordinary monitor with a gamma value of 2.2.
If your monitor displays colors too light, you should specify a screen-gamma value smaller than 2.2. This requests correction that makes colors darker. A screen gamma value of 1.5 may give good results for LCD color displays.
alpha​
This parameter specifies the opacity of the frame, on graphical displays that support variable opacity. It should be an integer between 0 and 100, where 0 means completely transparent and 100 means completely opaque. It can also have a nil value, which tells Emacs not to set the frame opacity (leaving it to the window manager).
To prevent the frame from disappearing completely from view, the variable frame-alpha-lower-limit defines a lower opacity limit. If the value of the frame parameter is less than the value of this variable, Emacs uses the latter. By default, frame-alpha-lower-limit is 20.
The alpha frame parameter can also be a cons cell (active . inactive), where active is the opacity of the frame when it is selected, and inactive is the opacity when it is not selected.
Some window systems do not support the alpha parameter for child frames (see Child Frames).
The following frame parameters are semi-obsolete in that they are automatically equivalent to particular face attributes of particular faces (see Standard Faces in The Emacs Manual):
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 (see Fontsets). It is equivalent to the font attribute of the default face.
foreground-color​
The color to use for the image of a character. It is equivalent to the :foreground attribute of the default face.
background-color​
The color to use for the background of characters. It is equivalent to the :background attribute of the default face.
mouse-color​
The color for the mouse pointer. It is equivalent to the :background attribute of the mouse face.
cursor-color​
The color for the cursor that shows point. It is equivalent to the :background attribute of the cursor face.
border-color​
The color for the border of the frame. It is equivalent to the :background attribute of the border face.
scroll-bar-foreground​
If non-nil, the color for the foreground of scroll bars. It is equivalent to the :foreground attribute of the scroll-bar face.
scroll-bar-background​
If non-nil, the color for the background of scroll bars. It is equivalent to the :background attribute of the scroll-bar face.