X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/d279e6680842b872ae3aab1fb429b1879db50f7f..d7a89815b6d69c3b1793d34bcad8bf0aa21d48c8:/doc/lispref/frames.texi diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 3c27ab1556..a6f4081532 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -712,13 +712,13 @@ pixel sizes of these character units (@pxref{Face Attributes}). @table @code @vindex height, a frame parameter @item height -The height of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) +The height of the frame's text area (@pxref{Size and Position}), in +characters. @vindex width, a frame parameter @item width -The width of the frame contents, in characters. (To get the width in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) +The width of the frame's text area (@pxref{Size and Position}), in +characters. @vindex user-size, a frame parameter @item user-size @@ -742,9 +742,9 @@ with the mouse, while the latter really covers the whole screen and does not allow resizing by mouse dragging. With some window managers you may have to customize the variable -@code{frame-resize-pixelwise} to a non-@code{nil} value in order to make -a frame appear ``maximized'' or ``fullscreen''. - +@code{frame-resize-pixelwise} (@pxref{Size and Position}) to a +non-@code{nil} value in order to make a frame appear ``maximized'' or +``fullscreen''. @end table @node Layout Parameters @@ -770,19 +770,21 @@ Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are @code{left}, @code{right}, and @code{nil} for no scroll bars. -@ignore @vindex horizontal-scroll-bars, a frame parameter @item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). Horizontal scroll bars are not currently -implemented. -@end ignore +Whether the frame has scroll bars for horizontal scrolling (@code{t} and +@code{bottom} mean yes, @code{nil} means no). @vindex scroll-bar-width, a frame parameter @item scroll-bar-width The width of vertical scroll bars, in pixels, or @code{nil} meaning to use the default width. +@vindex scroll-bar-height, a frame parameter +@item scroll-bar-height +The height of horizontal scroll bars, in pixels, or @code{nil} meaning +to use the default height. + @vindex left-fringe, a frame parameter @vindex right-fringe, a frame parameter @item left-fringe @@ -796,14 +798,6 @@ these two frame parameters, the return value is always an integer. When using @code{set-frame-parameter}, passing a @code{nil} value imposes an actual default value of 8 pixels. -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame, as -reported by @code{frame-parameter}, may be larger than what you -specify. Any extra width is distributed evenly between the left and -right fringe. However, you can force one fringe or the other to a -precise width by specifying that width as a negative integer. If both -widths are negative, only the left fringe gets the specified width. - @vindex right-divider-width, a frame parameter @item right-divider-width The width (thickness) reserved for the right divider (@pxref{Window @@ -1147,65 +1141,137 @@ equivalent to the @code{:background} attribute of the @code{scroll-bar} face. @end table + @node Size and Position -@subsection Frame Size And Position +@subsection Frame Size and Position @cindex size of frame @cindex screen size @cindex frame size @cindex resize frame - You can read or change the size and position of a frame using the -frame parameters @code{left}, @code{top}, @code{height}, and -@code{width}. Whatever geometry parameters you don't specify are chosen -by the window manager in its usual fashion. +You can read or change the size and position of a frame using the frame +parameters @code{left}, @code{top}, @code{height}, and @code{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. -(For the precise meaning of ``selected frame'' used by these functions, -see @ref{Input Focus}.) +Most of the functions described below use a @var{frame} argument which +has to specify a live frame. If omitted or @code{nil}, it specifies the +selected frame, see @ref{Input Focus}. @defun set-frame-position frame left top This function sets the position of the top left corner of @var{frame} to @var{left} and @var{top}. These arguments are measured in pixels, and -normally count from the top left corner of the screen. +normally count from the top left corner of the screen to the top left +corner of the rectangle allotted to the frame by the window manager. -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. +Negative parameter values position the bottom edge of that rectangle up +from the bottom edge of the screen, or the right rectangle 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. @end defun -@defun frame-height &optional frame -@defunx frame-width &optional frame -These functions return the height and width of @var{frame}, measured in -lines and columns. If you don't supply @var{frame}, they use the -selected frame. -@end defun +@cindex frame default font +@cindex default font of a frame +Each frame has a @dfn{default font} which specifies the canonical height +and width of a character on that frame. The default font is used when +retrieving or changing the size of a frame in terms of columns or lines. +It is also used when resizing (@pxref{Window Sizes}) or splitting +(@pxref{Splitting Windows}) windows. + +@defun frame-char-height &optional frame +@defunx frame-char-width &optional frame +These functions return the canonical height and width of a character in +@var{frame}, measured in pixels. Together, these values establish the +size of the default font on @var{frame}. The values depend on the +choice of font for @var{frame}, see @ref{Font and Color Parameters}. +@end defun + +The default font can be also set directly with the following function: + +@deffn Command set-frame-font font &optional keep-size frames +This sets the default font to @var{font}. When called interactively, it +prompts for the name of a font, and uses that font on the selected +frame. When called from Lisp, @var{font} should be a font name (a +string), a font object, font entity, or a font spec. + +If the optional argument @var{keep-size} is @code{nil}, this keeps the +number of frame lines and columns fixed. (If non-@code{nil}, the option +@code{frame-inhibit-implied-resize} described below will override this.) +If @var{keep-size} is non-@code{nil} (or with a prefix argument), it +tries to keep the size of the display area of the current frame fixed by +adjusting the number of lines and columns. + +If the optional argument @var{frames} is @code{nil}, this applies the +font to the selected frame only. If @var{frames} is non-@code{nil}, it +should be a list of frames to act upon, or @code{t} meaning all existing +graphical frames. +@end deffn + +@cindex frame display area +@cindex display area of a frame +The @dfn{display area} of a frame is a rectangular area within the area +allotted to the frame by the window manager. The display area neither +includes the title bar (@pxref{Frame Titles}) nor any other decorations +provided by the window manager (like an external border used for +resizing frames via mouse dragging). + + The actual height of the display area depends on the window-system +and toolkit in use. With GTK+, the display area does not include any +tool bar or menu bar. With the Motif or Lucid toolkits and with +Windows, the display area includes the tool bar but not the menu bar. +In a graphical version with no toolkit, it includes both the tool bar +and menu bar. On a text terminal, the display area includes the menu +bar. @defun frame-pixel-height &optional frame @defunx frame-pixel-width &optional frame -These functions return the height and width of the main display area -of @var{frame}, measured in pixels. If you don't supply @var{frame}, -they use the selected frame. For a text terminal, the results are in -characters rather than pixels. - -These values include the internal borders, and windows' scroll bars -and fringes (which belong to individual windows, not to the frame -itself). The exact value of the heights depends on the window-system -and toolkit in use. With GTK+, the height does not include any tool -bar or menu bar. With the Motif or Lucid toolkits, it includes the -tool bar but not the menu bar. In a graphical version with no -toolkit, it includes both the tool bar and menu bar. For a text -terminal, the result includes the menu bar. + These functions return the height and width of the display area of +@var{frame}, measured in pixels. For a text terminal, the results are +in characters rather than pixels. +@end defun + +@cindex frame text area +@cindex text area of a frame + The @dfn{text area} of a frame is a concept implicitly used by all +functions that change a frame's height or width. It is a rectangle +located within the display area. Its size is obtained from that of the +display area by subtracting the sizes of any tool or menu bars that are +part of the display area, any internal borders, one vertical and one +horizontal scroll bar, and one left and one right fringe as specified +for this frame, see @ref{Layout Parameters}. + +@defun frame-text-height &optional frame +@defunx frame-text-width &optional frame +These functions return the height and width of the text area of +@var{frame}, measured in pixels. For a text terminal, the results are +in characters rather than pixels. + +The value returned by @code{frame-text-height} differs from that +returned by @code{frame-pixel-height} by not including the heights of +any tool bar or menu bar, the height of one horizontal scroll bar and +the widths of the internal border. + +The value returned by @code{frame-text-width} differs from that returned +by @code{frame-pixel-width} by not including the width of one vertical +scroll bar, the widths of one left and one right fringe and the widths +of the internal border. @end defun -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the height and width of a character in -@var{frame}, measured in pixels. The values depend on the choice of -font. If you don't supply @var{frame}, these functions use the selected -frame. +@defun frame-height &optional frame +@defunx frame-width &optional frame +These functions return the height and width of the text area of +@var{frame}, measured in units of the default font height and width of +@var{frame}. These functions are plain shorthands for writing +@code{(frame-parameter frame 'height)} and @code{(frame-parameter frame +'width)}. + +If the text area of @var{frame} measured in pixles is not a multiple of +its default font size, the values returned by this functions are rounded +down to the number of characters of the default font that fully fit into +the text area. @end defun @defopt frame-resize-pixelwise @@ -1231,9 +1297,9 @@ order to make a frame appear truly ``maximized'' or ``fullscreen''. @end defopt @defun set-frame-size frame width height pixelwise -This function sets the size of @var{frame}, measured in characters; -@var{width} and @var{height} specify the new width in columns and the -new height in lines. +This function sets the size of the text area of @var{frame}, measured in +characters; @var{width} and @var{height} specify the new width in +columns and the new height in lines. The optional argument @var{pixelwise} non-@code{nil} means to measure the new width and height in units of pixels instead. Note that if @@ -1243,9 +1309,9 @@ to a multiple of its character size. @end defun @defun set-frame-height frame height &optional pretend pixelwise -This function resizes @var{frame} to a height of @var{height} lines. The -sizes of existing windows in @var{frame} are altered proportionally to -fit. +This function resizes the text area of @var{frame} to a height of +@var{height} lines. The sizes of existing windows in @var{frame} are +altered proportionally to fit. If @var{pretend} is non-@code{nil}, then Emacs displays @var{height} lines of output in @var{frame}, but does not change its value for the @@ -1265,8 +1331,8 @@ height to a multiple of its character height. @end defun @defun set-frame-width frame width &optional pretend pixelwise -This function sets the width of @var{frame}, measured in characters. -The argument @var{pretend} has the same meaning as in +This function sets the width of the text area of @var{frame}, measured +in characters. The argument @var{pretend} has the same meaning as in @code{set-frame-height}. The optional fourth argument @var{pixelwise} non-@code{nil} means that @@ -1276,6 +1342,65 @@ fully honor the request if it does not increase/decrease the frame width to a multiple of its character width. @end defun +None of these three functions will make a frame smaller than needed to +display all of its windows together with their scroll bars, fringes, +margins, dividers, mode and header lines. This contrasts with requests +by the window manager triggered, for example, by dragging the external +border of a frame with the mouse. Such requests are always honored by +clipping, if necessary, portions that cannot be displayed at the right, +bottom corner of the frame. + + By default, Emacs tries to keep the number of lines and columns of a +frame's text area unaltered when, for example, adding or removing a menu +bar, changing the default font or setting the width of the frame's +scroll bars. This means, however, that in such case Emacs must ask the +window manager to resize the display area of the frame in order to +accommodate the size change. Note that wrapping a menu or tool bar +usually does not resize the frame's display area, hence this will alter +the number of displayed lines. + + Occasionally, such implied resizing of the display area may be +unwanted, for example, when the frame is maximized or made fullscreen +where it's turned off by default. In other cases you can disable +implied resizing with the following option: + +@defopt frame-inhibit-implied-resize +If this option is @code{nil}, changing font, menu bar, tool bar, +internal borders, fringes or scroll bars of a specific frame may +implicitly resize the frame's display area in order to preserve the +number of columns or lines the frame displays. If this option is +non-@code{nil}, no implied resizing is done. + +The value of this option can be also be a list of frame parameters. In +that case, implied resizing is inhibited when changing a parameter that +appears in this list. The frame parameters currently handled by this +option are: @code{font}, @code{font-backend}, +@code{internal-border-width}, @code{menu-bar-lines} and +@code{tool-bar-lines}. + +Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height}, +@code{vertical-scroll-bars}, @code{horizontal-scroll-bars}, +@code{left-fringe} and @code{right-fringe} frame parameters is handled +as if the frame contained just one live window. This means, for +example, that removing vertical scroll bars on a frame containing +several side by side windows will shrink the frame width by the width of +one scroll bar provided this option is @code{nil} and keep it unchanged +if this option is either @code{t} or a list containing +@code{vertical-scroll-bars}. + +The default value is @code{'(tool-bar-lines)} for Lucid, Motif and +Windows (which means that adding/removing a tool bar there does not +change the frame height), @code{nil} on all other window systems +including GTK+ (which means that changing any of the parameters listed +above may change the size of the frame), and @code{t} otherwise (which +means the frame size never changes implicitly when there's no window +system support). + +Note that when a frame is not large enough to accommodate a change of +any of the parameters listed above, Emacs may try to enlarge the frame +even if this option is non-@code{nil}. +@end defopt + @c FIXME? Belongs more in Emacs manual than here? @c But, e.g., fit-window-to-buffer is in this manual. If you have a frame that displays only one window, you can fit that @@ -1398,6 +1523,18 @@ terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}. @item terminal-initted After the terminal is initialized, this is set to the terminal-specific initialization function. +@item tty-mode-set-strings +When present, a list of strings containing escape sequences that Emacs +will output while configuring a tty for rendering. Emacs emits these +strings only when configuring a terminal: if you want to enable a mode +on a terminal that is already active (for example, while in +@code{tty-setup-hook}), explicitly output the necessary escape +sequence using @code{send-string-to-terminal} in addition to adding +the sequence to @code{tty-mode-set-strings}. +@item tty-mode-reset-strings +When present, a list of strings that undo the effects of the strings +in @code{tty-mode-set-strings}. Emacs emits these strings when +exiting, deleting a terminal, or suspending itself. @end table @node Frame Titles