frames.texi 130 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
Paul Eggert's avatar
Paul Eggert committed
3
@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
4
@c Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@node Frames
Glenn Morris's avatar
Glenn Morris committed
7 8 9
@chapter Frames
@cindex frame

10 11 12 13 14 15
  A @dfn{frame} is a screen object that contains one or more Emacs
windows (@pxref{Windows}).  It is the kind of object called a
``window'' in the terminology of graphical environments; but we can't
call it a ``window'' here, because Emacs uses that word in a different
way.  In Emacs Lisp, a @dfn{frame object} is a Lisp object that
represents a frame on the screen.  @xref{Frame Type}.
Glenn Morris's avatar
Glenn Morris committed
16 17 18

  A frame initially contains a single main window and/or a minibuffer
window; you can subdivide the main window vertically or horizontally
19
into smaller windows.  @xref{Splitting Windows}.
Glenn Morris's avatar
Glenn Morris committed
20

21
@cindex terminal
22
  A @dfn{terminal} is a display device capable of displaying one or
23 24
more Emacs frames.  In Emacs Lisp, a @dfn{terminal object} is a Lisp
object that represents a terminal.  @xref{Terminal Type}.
25

26 27 28 29 30 31 32 33 34 35 36 37
@cindex text terminal
@cindex graphical terminal
@cindex graphical display
  There are two classes of terminals: @dfn{text terminals} and
@dfn{graphical terminals}.  Text terminals are non-graphics-capable
displays, including @command{xterm} and other terminal emulators.  On
a text terminal, each Emacs frame occupies the terminal's entire
screen; although you can create additional frames and switch between
them, the terminal only shows one frame at a time.  Graphical
terminals, on the other hand, are managed by graphical display systems
such as the X Window System, which allow Emacs to show multiple frames
simultaneously on the same display.
38 39 40

  On GNU and Unix systems, you can create additional frames on any
available terminal, within a single Emacs session, regardless of
41 42 43 44
whether Emacs was started on a text or graphical terminal.  Emacs can
display on both graphical and text terminals simultaneously.  This
comes in handy, for instance, when you connect to the same session
from several remote locations.  @xref{Multiple Terminals}.
Glenn Morris's avatar
Glenn Morris committed
45 46 47 48 49 50 51 52

@defun framep object
This predicate returns a non-@code{nil} value if @var{object} is a
frame, and @code{nil} otherwise.  For a frame, the value indicates which
kind of display the frame uses:

@table @code
@item t
53 54 55
The frame is displayed on a text terminal.
@item x
The frame is displayed on an X graphical terminal.
Glenn Morris's avatar
Glenn Morris committed
56
@item w32
57
The frame is displayed on a MS-Windows graphical terminal.
58
@item ns
59 60
The frame is displayed on a GNUstep or Macintosh Cocoa graphical
terminal.
Glenn Morris's avatar
Glenn Morris committed
61 62 63 64 65
@item pc
The frame is displayed on an MS-DOS terminal.
@end table
@end defun

66
@defun frame-terminal &optional frame
67 68 69
This function returns the terminal object that displays @var{frame}.
If @var{frame} is @code{nil} or unspecified, it defaults to the
selected frame.
70 71 72 73
@end defun

@defun terminal-live-p object
This predicate returns a non-@code{nil} value if @var{object} is a
74
terminal that is live (i.e., not deleted), and @code{nil} otherwise.
75 76 77
For live terminals, the return value indicates what kind of frames are
displayed on that terminal; the list of possible values is the same as
for @code{framep} above.
78 79
@end defun

Glenn Morris's avatar
Glenn Morris committed
80
@menu
81
* Creating Frames::             Creating additional frames.
82
* Multiple Terminals::          Displaying on several different devices.
83
* Frame Geometry::              Geometric properties of frames.
84
* Frame Parameters::            Controlling frame size, position, font, etc.
85
* Terminal Parameters::         Parameters common for all frames on terminal.
Glenn Morris's avatar
Glenn Morris committed
86
* Frame Titles::                Automatic updating of frame titles.
Glenn Morris's avatar
Glenn Morris committed
87 88 89 90 91 92 93 94 95 96 97
* Deleting Frames::             Frames last until explicitly deleted.
* Finding All Frames::          How to examine all existing frames.
* 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 it.
* 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.
Glenn Morris's avatar
Glenn Morris committed
98 99 100 101
* Dialog Boxes::                Displaying a box to ask yes or no.
* Pointer Shape::               Specifying the shape of the mouse pointer.
* Window System Selections::    Transferring text to and from other X clients.
* Drag and Drop::               Internals of Drag-and-Drop implementation.
Glenn Morris's avatar
Glenn Morris committed
102
* Color Names::                 Getting the definitions of color names.
103
* Text Terminal Colors::        Defining colors for text terminals.
Glenn Morris's avatar
Glenn Morris committed
104
* Resources::                   Getting resource values from the server.
Glenn Morris's avatar
Glenn Morris committed
105 106 107 108 109
* Display Feature Testing::     Determining the features of a terminal.
@end menu

@node Creating Frames
@section Creating Frames
110
@cindex frame creation
Glenn Morris's avatar
Glenn Morris committed
111 112 113

To create a new frame, call the function @code{make-frame}.

114
@deffn Command make-frame &optional alist
Glenn Morris's avatar
Glenn Morris committed
115
This function creates and returns a new frame, displaying the current
116 117 118 119 120 121 122
buffer.

The @var{alist} argument is an alist that specifies frame parameters
for the new frame.  @xref{Frame Parameters}.  If you specify the
@code{terminal} parameter in @var{alist}, the new frame is created on
that terminal.  Otherwise, if you specify the @code{window-system}
frame parameter in @var{alist}, that determines whether the frame
123
should be displayed on a text terminal or a graphical terminal.
124 125 126 127 128 129 130 131 132 133 134
@xref{Window Systems}.  If neither is specified, the new frame is
created in the same terminal as the selected frame.

Any parameters not mentioned in @var{alist} default to the values in
the alist @code{default-frame-alist} (@pxref{Initial Parameters});
parameters not specified there default from the X resources or its
equivalent on your operating system (@pxref{X Resources,, X Resources,
emacs, The GNU Emacs Manual}).  After the frame is created, Emacs
applies any parameters listed in @code{frame-inherited-parameters}
(see below) and not present in the argument, taking the values from
the frame that was selected when @code{make-frame} was called.
Glenn Morris's avatar
Glenn Morris committed
135

136 137 138 139 140 141 142
Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
window manager might position the frame differently than specified by
the positional parameters in @var{alist} (@pxref{Position
Parameters}).  For example, some window managers have a policy of
displaying the frame on the monitor that contains the largest part of
the window (a.k.a.@: the @dfn{dominating} monitor).

Glenn Morris's avatar
Glenn Morris committed
143 144
This function itself does not make the new frame the selected frame.
@xref{Input Focus}.  The previously selected frame remains selected.
145 146
On graphical terminals, however, the windowing system may select the
new frame for its own reasons.
147
@end deffn
Glenn Morris's avatar
Glenn Morris committed
148 149

@defvar before-make-frame-hook
150
A normal hook run by @code{make-frame} before it creates the frame.
Glenn Morris's avatar
Glenn Morris committed
151 152 153 154 155 156 157 158
@end defvar

@defvar after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame.
Each function in @code{after-make-frame-functions} receives one argument, the
frame just created.
@end defvar

159 160 161 162 163 164 165 166 167
@defvar frame-inherited-parameters
This variable specifies the list of frame parameters that a newly
created frame inherits from the currently selected frame.  For each
parameter (a symbol) that is an element in the list and is not present
in the argument to @code{make-frame}, the function sets the value of
that parameter in the created frame to its value in the selected
frame.
@end defvar

168 169 170 171
@node Multiple Terminals
@section Multiple Terminals
@cindex multiple terminals
@cindex multi-tty
Glenn Morris's avatar
Glenn Morris committed
172 173 174
@cindex multiple X displays
@cindex displays, multiple

175 176 177 178 179
  Emacs represents each terminal as a @dfn{terminal object} data type
(@pxref{Terminal Type}).  On GNU and Unix systems, Emacs can use
multiple terminals simultaneously in each session.  On other systems,
it can only use a single terminal.  Each terminal object has the
following attributes:
180 181 182

@itemize @bullet
@item
183
The name of the device used by the terminal (e.g., @samp{:0.0} or
184 185 186 187 188
@file{/dev/tty}).

@item
The terminal and keyboard coding systems used on the terminal.
@xref{Terminal I/O Encoding}.
Glenn Morris's avatar
Glenn Morris committed
189

190 191
@item
The kind of display associated with the terminal.  This is the symbol
192
returned by the function @code{terminal-live-p} (i.e., @code{x},
193
@code{t}, @code{w32}, @code{ns}, or @code{pc}).  @xref{Frames}.
Glenn Morris's avatar
Glenn Morris committed
194

195 196 197 198 199 200
@item
A list of terminal parameters.  @xref{Terminal Parameters}.
@end itemize

  There is no primitive for creating terminal objects.  Emacs creates
them as needed, such as when you call @code{make-frame-on-display}
201
(described below).
202 203 204 205 206 207 208 209 210

@defun terminal-name &optional terminal
This function returns the file name of the device used by
@var{terminal}.  If @var{terminal} is omitted or @code{nil}, it
defaults to the selected frame's terminal.  @var{terminal} can also be
a frame, meaning that frame's terminal.
@end defun

@defun terminal-list
211
This function returns a list of all live terminal objects.
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
@end defun

@defun get-device-terminal device
This function returns a terminal whose device name is given by
@var{device}.  If @var{device} is a string, it can be either the file
name of a terminal device, or the name of an X display of the form
@samp{@var{host}:@var{server}.@var{screen}}.  If @var{device} is a
frame, this function returns that frame's terminal; @code{nil} means
the selected frame.  Finally, if @var{device} is a terminal object
that represents a live terminal, that terminal is returned.  The
function signals an error if its argument is none of the above.
@end defun

@defun delete-terminal &optional terminal force
This function deletes all frames on @var{terminal} and frees the
resources used by it.  It runs the abnormal hook
@code{delete-terminal-functions}, passing @var{terminal} as the
argument to each function.

If @var{terminal} is omitted or @code{nil}, it defaults to the
selected frame's terminal.  @var{terminal} can also be a frame,
meaning that frame's terminal.

Normally, this function signals an error if you attempt to delete the
sole active terminal, but if @var{force} is non-@code{nil}, you are
allowed to do so.  Emacs automatically calls this function when the
last frame on a terminal is deleted (@pxref{Deleting Frames}).
@end defun

@defvar delete-terminal-functions
An abnormal hook run by @code{delete-terminal}.  Each function
receives one argument, the @var{terminal} argument passed to
@code{delete-terminal}.  Due to technical details, the functions may
be called either just before the terminal is deleted, or just
afterwards.
@end defvar

@cindex terminal-local variables
Glenn Morris's avatar
Glenn Morris committed
250 251 252 253 254
  A few Lisp variables are @dfn{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 @code{default-minibuffer-frame},
@code{defining-kbd-macro}, @code{last-kbd-macro}, and
255 256 257 258 259
@code{system-key-alist}.  They are always terminal-local, and can
never be buffer-local (@pxref{Buffer-Local Variables}).

  On GNU and Unix systems, each X display is a separate graphical
terminal.  When Emacs is started from within the X window system, it
260 261 262 263 264
uses the X display specified by the @env{DISPLAY} environment
variable, or by the @samp{--display} option (@pxref{Initial Options,,,
emacs, The GNU Emacs Manual}).  Emacs can connect to other X displays
via the command @code{make-frame-on-display}.  Each X display has its
own selected frame and its own minibuffer windows; however, only one
Paul Eggert's avatar
Paul Eggert committed
265
of those frames is @emph{the} selected frame at any given moment
266 267 268
(@pxref{Input Focus}).  Emacs can even connect to other text
terminals, by interacting with the @command{emacsclient} program.
@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
269

270 271
@cindex X display names
@cindex display name on X
272
  A single X server can handle more than one display.  Each X display
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290
has a three-part name,
@samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}.  The
first part, @var{hostname}, specifies the name of the machine to which
the display is physically connected.  The second part,
@var{displaynumber}, is a zero-based number that identifies one or
more monitors connected to that machine that share a common keyboard
and pointing device (mouse, tablet, etc.).  The third part,
@var{screennumber}, identifies a zero-based screen number (a separate
monitor) that is part of a single monitor collection on that X server.
When you use two or more screens belonging to one server, Emacs knows
by the similarity in their names that they share a single keyboard.

  Systems that don't use the X window system, such as MS-Windows,
don't support the notion of X displays, and have only one display on
each host.  The display name on these systems doesn't follow the above
3-part format; for example, the display name on MS-Windows systems is
a constant string @samp{w32}, and exists for compatibility, so that
you could pass it to functions that expect a display name.
291

Glenn Morris's avatar
Glenn Morris committed
292
@deffn Command make-frame-on-display display &optional parameters
293 294 295 296
This function creates and returns a new frame on @var{display}, taking
the other frame parameters from the alist @var{parameters}.
@var{display} should be the name of an X display (a string).

Paul Eggert's avatar
Paul Eggert committed
297 298
Before creating the frame, this function ensures that Emacs is set
up to display graphics.  For instance, if Emacs has not processed X
299
resources (e.g., if it was started on a text terminal), it does so at
300
this time.  In all other respects, this function behaves like
301
@code{make-frame} (@pxref{Creating Frames}).
Glenn Morris's avatar
Glenn Morris committed
302 303 304
@end deffn

@defun x-display-list
305 306 307
This function 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.
Glenn Morris's avatar
Glenn Morris committed
308 309 310
@end defun

@defun x-open-connection display &optional xrm-string must-succeed
311 312 313 314 315 316 317 318 319 320 321 322
This function opens a connection to the X display @var{display},
without creating a frame on that display.  Normally, Emacs Lisp
programs need not call this function, as @code{make-frame-on-display}
calls it automatically.  The only reason for calling it is to check
whether communication can be established with a given X display.

The optional argument @var{xrm-string}, if not @code{nil}, is a string
of resource names and values, in the same format used in the
@file{.Xresources} file.  @xref{X Resources,, X Resources, emacs, The
GNU Emacs Manual}.  These values apply to all Emacs frames created on
this display, overriding the resource values recorded in the X server.
Here's an example of what this string might look like:
Glenn Morris's avatar
Glenn Morris committed
323 324 325 326 327 328 329 330 331 332 333

@example
"*BorderWidth: 3\n*InternalBorder: 2\n"
@end example

If @var{must-succeed} is non-@code{nil}, failure to open the connection
terminates Emacs.  Otherwise, it is an ordinary Lisp error.
@end defun

@defun x-close-connection display
This function closes the connection to display @var{display}.  Before
334 335
you can do this, you must first delete all the frames that were open
on that display (@pxref{Deleting Frames}).
336 337
@end defun

338
@cindex multi-monitor
Paul Eggert's avatar
Paul Eggert committed
339
  On some multi-monitor setups, a single X display outputs to more
Glenn Morris's avatar
Glenn Morris committed
340 341 342
than one physical monitor.  You can use the functions
@code{display-monitor-attributes-list} and @code{frame-monitor-attributes}
to obtain information about such setups.
343 344 345

@defun display-monitor-attributes-list &optional display
This function returns a list of physical monitor attributes on
346 347 348 349 350 351
@var{display}, which can be a display name (a string), a terminal, or
a frame; if omitted or @code{nil}, it defaults to the selected frame's
display.  Each element of the list is an association list,
representing the attributes of a physical monitor.  The first element
corresponds to the primary monitor.  The attribute keys and values
are:
352 353 354

@table @samp
@item geometry
355 356 357 358
Position of the top-left corner of the monitor's screen and its size,
in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}.  Note
that, if the monitor is not the primary monitor, some of the
coordinates might be negative.
359 360

@item workarea
Paul Eggert's avatar
Paul Eggert committed
361
Position of the top-left corner and size of the work area (usable
Glenn Morris's avatar
Glenn Morris committed
362 363
space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}.
This may be different from @samp{geometry} in that space occupied by
Paul Eggert's avatar
Paul Eggert committed
364
various window manager features (docks, taskbars, etc.)@: may be
Glenn Morris's avatar
Glenn Morris committed
365 366 367 368
excluded from the work area.  Whether or not such features actually
subtract from the work area depends on the platform and environment.
Again, if the monitor is not the primary monitor, some of the
coordinates might be negative.
369 370

@item mm-size
Glenn Morris's avatar
Glenn Morris committed
371
Width and height in millimeters as @samp{(@var{width} @var{height})}
372 373

@item frames
Glenn Morris's avatar
Glenn Morris committed
374
List of frames that this physical monitor dominates (see below).
375 376

@item name
Glenn Morris's avatar
Glenn Morris committed
377
Name of the physical monitor as @var{string}.
Glenn Morris's avatar
Glenn Morris committed
378 379 380 381

@item source
Source of the multi-monitor information as @var{string};
e.g., @samp{XRandr} or @samp{Xinerama}.
382 383
@end table

Glenn Morris's avatar
Glenn Morris committed
384
@var{x}, @var{y}, @var{width}, and @var{height} are integers.
Glenn Morris's avatar
Glenn Morris committed
385
@samp{name} and @samp{source} may be absent.
386

Glenn Morris's avatar
Glenn Morris committed
387 388 389 390 391 392
A frame is @dfn{dominated} by a physical monitor when either the
largest area of the frame resides in that monitor, or (if the frame
does not intersect any physical monitors) that monitor is the closest
to the frame.  Every (non-tooltip) frame (whether visible or not) in a
graphical display is dominated by exactly one physical monitor at a
time, though the frame can span multiple (or no) physical monitors.
393 394 395 396

Here's an example of the data produced by this function on a 2-monitor
display:

397
@lisp
398 399
  (display-monitor-attributes-list)
  @result{}
Glenn Morris's avatar
Glenn Morris committed
400 401
  (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor}
    (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height}
402
    (mm-size 677 381)
403 404 405
    (name . "DISPLAY1")
    (frames #<frame emacs@@host *Messages* 0x11578c0>
            #<frame emacs@@host *scratch* 0x114b838>))
Glenn Morris's avatar
Glenn Morris committed
406 407
   ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor}
    (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used}
408
    (mm-size 593 370)
409
    (name . "DISPLAY2")
410
    (frames)))
411
@end lisp
412

413 414 415 416
@end defun

@defun frame-monitor-attributes &optional frame
This function returns the attributes of the physical monitor
Glenn Morris's avatar
Glenn Morris committed
417
dominating (see above) @var{frame}, which defaults to the selected frame.
418 419
@end defun

420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491

@node Frame Geometry
@section Frame Geometry
@cindex frame geometry
@cindex frame position
@cindex position of frame
@cindex frame size
@cindex size of frame

The geometry of a frame depends on the toolkit that was used to build
this instance of Emacs and the terminal that displays the frame.  This
chapter describes these dependencies and some of the functions to deal
with them.  Note that the @var{frame} argument of all of these functions
has to specify a live frame (@pxref{Deleting Frames}).  If omitted or
@code{nil}, it specifies the selected frame (@pxref{Input Focus}).

@menu
* Frame Layout::            Basic layout of frames.
* Frame Font::              The default font of a frame and how to set it.
* Size and Position::       Changing the size and position of a frame.
* Implied Frame Resizing::  Implied resizing of frames and how to prevent it.
@end menu


@node Frame Layout
@subsection Frame Layout
@cindex frame layout
@cindex layout of frame

The drawing below sketches the layout of a frame on a graphical
terminal:
@smallexample
@group

        <------------ Outer Frame Width ----------->
        ___________________________________________
     ^(0)  ___________ External Border __________   |
     | |  |_____________ Title Bar ______________|  |
     | | (1)_____________ Menu Bar ______________|  | ^
     | | (2)_____________ Tool Bar ______________|  | ^
     | | (3) _________ Internal Border ________  |  | ^
     | |  | |   ^                              | |  | |
     | |  | |   |                              | |  | |
Outer  |  | | Inner                            | |  | Native
Frame  |  | | Frame                            | |  | Frame
Height |  | | Height                           | |  | Height
     | |  | |   |                              | |  | |
     | |  | |<--+--- Inner Frame Width ------->| |  | |
     | |  | |   |                              | |  | |
     | |  | |___v______________________________| |  | |
     | |  |___________ Internal Border __________|  | v
     v |______________ External Border _____________|
           <-------- Native Frame Width -------->

@end group
@end smallexample

In practice not all of the areas shown in the drawing will or may be
present.  The meaning of these areas is:

@table @samp
@item Outer Frame
@cindex outer frame
@cindex outer edges
@cindex outer width
@cindex outer height
The @dfn{outer frame} is a rectangle comprising all areas shown in the
drawing.  The edges of that rectangle are called the @dfn{outer edges}
of the frame.  The @dfn{outer width} and @dfn{outer height} of the frame
specify the size of that rectangle.

@cindex outer position
Paul Eggert's avatar
Paul Eggert committed
492
The upper left corner of the outer frame (indicated by @samp{(0)} in the
493 494 495 496 497 498 499 500 501 502
drawing above) is the @dfn{outer position} or the frame.  It is
specified by and settable via the @code{left} and @code{top} frame
parameters (@pxref{Position Parameters}) as well as the functions
@code{frame-position} and @code{set-frame-position} (@pxref{Size and
Position}).

@item External Border
@cindex external border
The @dfn{external border} is part of the decorations supplied by the
window manager.  It's typically used for resizing the frame with the
503
mouse.  The external border is normally not shown on ``fullboth'' and
504 505 506 507 508 509 510 511 512 513 514 515 516
maximized frames (@pxref{Size Parameters}) and doesn't exist for text
terminal frames.

   The external border should not be confused with the @dfn{outer
border} specified by the @code{border-width} frame parameter
(@pxref{Layout Parameters}).  Since the outer border is usually ignored
on most platforms it is not covered here.

@item Title Bar
@cindex title bar
The @dfn{title bar} is also part of the window manager's decorations and
typically displays the title of the frame (@pxref{Frame Titles}) as well
as buttons for minimizing, maximizing and deleting the frame.  The title
Paul Eggert's avatar
Paul Eggert committed
517
bar is usually not displayed on fullboth (@pxref{Size Parameters})
518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559
or tooltip frames.  Title bars don't exist for text terminal frames.

@item Menu Bar
@cindex internal menu bar
@cindex external menu bar
The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs
itself) or external (drawn by a toolkit).  Most builds (GTK+, Lucid,
Motif and Windows) rely on an external menu bar.  NS also uses an
external menu bar which, however, is not part of the outer frame.
Non-toolkit builds can provide an internal menu bar.  On text terminal
frames, the menu bar is part of the frame's root window (@pxref{Windows
and Frames}).

@item Tool Bar
@cindex internal tool bar
@cindex external tool bar
Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either
internal (drawn by Emacs itself) or external (drawn by a toolkit).  The
GTK+ and NS builds have the tool bar drawn by the toolkit.  The
remaining builds use internal tool bars.  With GTK+ the tool bar can be
located on either side of the frame, immediately outside the internal
border, see below.

@item Native Frame
@cindex native frame
@cindex native edges
@cindex native width
@cindex native height
@cindex display area
The @dfn{native frame} is a rectangle located entirely within the outer
frame.  It excludes the areas occupied by the external border, the title
bar and any external menu or external tool bar.  The area enclosed by
the native frame is sometimes also referred to as the @dfn{display area}
of the frame.  The edges of the native frame are called the @dfn{native
edges} of the frame.  The @dfn{native width} and @dfn{native height} of
the frame specify the size of the rectangle.

@cindex native position
The top left corner of the native frame specifies the @dfn{native
position} of the frame.  (1)--(3) in the drawing above indicate that
position for the various builds:

560
@itemize @w{}
561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592
@item (1) non-toolkit and terminal frames

@item (2) Lucid, Motif and Windows frames

@item (3) GTK+ and NS frames
@end itemize

Accordingly, the native height of a frame includes the height of the
tool bar but not that of the menu bar (Lucid, Motif, Windows) or those
of the menu bar and the tool bar (non-toolkit and text terminal frames).

The native position of a frame is the reference position of functions
that set or return the current position of the mouse (@pxref{Mouse
Position}) and for functions dealing with the position of windows like
@code{window-edges}, @code{window-at} or @code{coordinates-in-window-p}
(@pxref{Coordinates and Windows}).

@item Internal Border
The internal border (@pxref{Layout Parameters}) is a border drawn by
Emacs around the inner frame (see below).

@item Inner Frame
@cindex inner frame
@cindex inner edges
@cindex inner width
@cindex inner height
The @dfn{inner frame} is the rectangle reserved for the frame's windows.
It's enclosed by the internal border which, however, is not part of the
inner frame.  Its edges are called the @dfn{inner edges} of the frame.
The @dfn{inner width} and @dfn{inner height} specify the size of the
rectangle.

593
@cindex minibuffer-less frame
594 595 596 597
@cindex minibuffer-only frame
As a rule, the inner frame is subdivided into the frame's root window
(@pxref{Windows and Frames}) and the frame's minibuffer window
(@pxref{Minibuffer Windows}).  There are two notable exceptions to this
598
rule: A @dfn{minibuffer-less frame} contains a root window only and does
599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625
not contain a minibuffer window.  A @dfn{minibuffer-only frame} contains
only a minibuffer window which also serves as that frame's root window.
See @ref{Initial Parameters} for how to create such frame
configurations.

@item Text Area
@cindex text area
The @dfn{text area} of a frame is a somewhat fictitious area located
entirely within the native frame.  It can be obtained by removing from
the native frame 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}.
@end table

@cindex absolute position
The @dfn{absolute position} of a frame or its edges is usually given in
terms of pixels counted from an origin at position (0, 0) of the frame's
display.  Note that with multiple monitors the origin does not
necessarily coincide with the top left corner of the entire usable
display area.  Hence the absolute outer position of a frame or the
absolute positions of the edges of the outer, native or inner frame can
be negative in such an environment even when that frame is completely
visible.

  For a frame on a graphical terminal the following function returns the
sizes of the areas described above:

626
@defun frame-geometry &optional frame
627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691
This function returns geometric attributes of @var{frame}.  The return
value is an association list of the attributes listed below.  All
coordinate, height and width values are integers counting pixels.

@table @code
@item outer-position
A cons of the absolute X- and Y-coordinates of the outer position of
@var{frame}, relative to the origin at position (0, 0) of @var{frame}'s
display.

@item outer-size
A cons of the outer width and height of @var{frame}.

@item external-border-size
A cons of the horizontal and vertical width of @var{frame}'s external
borders as supplied by the window manager.  If the window manager
doesn't supply these values, Emacs will try to guess them from the
coordinates of the outer and inner frame.

@item title-bar-size
A cons of the width and height of the title bar of @var{frame} as
supplied by the window manager or operating system.  If both of them are
zero, the frame has no title bar.  If only the width is zero, Emacs was
not able to retrieve the width information.

@item menu-bar-external
If non-@code{nil}, this means the menu bar is external (not part of the
native frame of @var{frame}).

@item menu-bar-size
A cons of the width and height of the menu bar of @var{frame}.

@item tool-bar-external
If non-@code{nil}, this means the tool bar is external (not part of the
native frame of @var{frame}).

@item tool-bar-position
This tells on which side the tool bar on @var{frame} is and can be one
of @code{left}, @code{top}, @code{right} or @code{bottom}.  The only
toolkit that currently supports a value other than @code{top} is GTK+.

@item tool-bar-size
A cons of the width and height of the tool bar of @var{frame}.

@item internal-border-width
The width of the internal border of @var{frame}.
@end table
@end defun

The following function can be used to retrieve the edges of the outer,
native and inner frame.

@defun frame-edges &optional frame type
This function returns the edges of the outer, native or inner frame of
@var{frame}.  @var{frame} must be a live frame and defaults to the
selected one.  The list returned has the form (@var{left} @var{top}
@var{right} @var{bottom}) where all values are in pixels relative to the
position (0, 0) of @var{frame}'s display.  For terminal frames
@var{left} and @var{top} are both zero.

Optional argument @var{type} specifies the type of the edges to return:
@var{type} @code{outer-edges} means to return the outer edges of
@var{frame}, @code{native-edges} (or @code{nil}) means to return its
native edges and @code{inner-edges} means to return its inner edges.

Paul Eggert's avatar
Paul Eggert committed
692
Notice that the pixels at the positions @var{bottom} and @var{right}
693 694 695
lie immediately outside the corresponding frame.  This means that if you
have, for example, two side-by-side frames positioned such that the
right outer edge of the frame on the left equals the left outer edge of
Paul Eggert's avatar
Paul Eggert committed
696
the frame on the right, the pixels representing that edge are part
697 698 699 700 701 702 703 704 705 706 707 708 709 710
of the frame on the right.
@end defun


@node Frame Font
@subsection Frame Font
@cindex default font
@cindex default character size
@cindex default character width
@cindex default width of character
@cindex default character height
@cindex default height of character
Each frame has a @dfn{default font} which specifies the default
character size for that frame.  This size is meant when retrieving or
Paul Eggert's avatar
Paul Eggert committed
711
changing the size of a frame in terms of columns or lines
712 713 714 715 716
(@pxref{Size Parameters}).  It is also used when resizing (@pxref{Window
Sizes}) or splitting (@pxref{Splitting Windows}) windows.

@cindex line height
@cindex column width
Martin Rudalics's avatar
Martin Rudalics committed
717 718 719 720 721 722
@cindex canonical character height
@cindex canonical character width
The terms @dfn{line height} and @dfn{canonical character height} are
sometimes used instead of ``default character height''.  Similarly, the
terms @dfn{column width} and @dfn{canonical character width} are used
instead of ``default character width''.
723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749

@defun frame-char-height &optional frame
@defunx frame-char-width &optional frame
These functions return the default 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 in the next section 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
750
and all future graphical frames.
751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846
@end deffn


@node Size and Position
@subsection Size and Position
@cindex frame size
@cindex frame position
@cindex position of frame

You can read or change the position of a frame using the frame
parameters @code{left} and @code{top} (@pxref{Position Parameters}) and
its size using the @code{height} and @code{width} parameters
(@pxref{Size Parameters}).  Here are some special features for working
with sizes and positions.  For all of these functions the argument
@var{frame} must denote a live frame and defaults to the selected frame.

@defun frame-position &optional Lisp_Object &optional frame
This function returns the outer position (@pxref{Frame Layout}) of
@var{frame} in pixels.  The value is a cons giving the coordinates of
the top left corner of the outer frame of @var{frame} relative to an
origin at the position (0, 0) of the frame's display.  On a text
terminal frame both values are zero.
@end defun

@defun set-frame-position frame X Y
This function sets the outer frame position of @var{frame} to @var{X}
and @var{Y}.  The latter arguments specify pixels and normally count
from an origin at the position (0, 0) of @var{frame}'s display.

A negative parameter value positions the right edge of the outer frame
by @var{-x} pixels left from the right edge of the screen or the bottom
edge by @var{-y} pixels up from the bottom edge of the screen.

This function has no effect on text terminal frames.
@end defun

@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional frame
   These functions return the inner height and width (the height and
width of the display area, see @ref{Frame Layout}) of @var{frame} in
pixels.  For a text terminal, the results are in characters rather than
pixels.
@end defun

@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} (@pxref{Frame Layout}), 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 internal 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-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} (@pxref{Frame Font}).  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 pixels is not a multiple of
its default font size, the values returned by these 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
If this option is @code{nil}, a frame's size is usually rounded to a
multiple of the current values of that frame's @code{frame-char-height}
and @code{frame-char-width} whenever the frame is resized.  If this is
non-@code{nil}, no rounding occurs, hence frame sizes can
increase/decrease by one pixel.

Setting this variable usually causes the next resize operation to pass
the corresponding size hints to the window manager.  This means that
this variable should be set only in a user's initial file; applications
should never bind it temporarily.

The precise meaning of a value of @code{nil} for this option depends on
the toolkit used.  Dragging the external border with the mouse is done
character-wise provided the window manager is willing to process the
corresponding size hints.  Calling @code{set-frame-size} (see below)
with arguments that do not specify the frame size as an integer multiple
of its character size, however, may: be ignored, cause a rounding
(GTK+), or be accepted (Lucid, Motif, MS-Windows).

With some window managers you may have to set this to non-@code{nil} in
847
order to make a frame appear truly maximized or full-screen.
848 849
@end defopt

850
@defun set-frame-size frame width height &optional pixelwise
851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872
This function sets the size of the text area of @var{frame}, measured in
terms of the canonical height and width of a character on @var{frame}
(@pxref{Frame Font}).

The optional argument @var{pixelwise} non-@code{nil} means to measure
the new width and height in units of pixels instead.  Note that if
@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
fully honor the request if it does not increase/decrease the frame size
to a multiple of its character size.
@end defun

@defun set-frame-height frame height &optional pretend pixelwise
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
actual height of the frame.  This is only useful on text terminals.
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
Paul Eggert's avatar
Paul Eggert committed
873
height directly does not always work, because knowing the correct
874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919
actual size may be necessary for correct cursor positioning on
text terminals.

The optional fourth argument @var{pixelwise} non-@code{nil} means that
@var{frame} should be @var{height} pixels high.  Note that if
@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
fully honor the request if it does not increase/decrease the frame
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 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
@var{frame} should be @var{width} pixels wide.  Note that if
@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
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.


@node Implied Frame Resizing
@subsection Implied Frame Resizing
@cindex implied frame resizing
@cindex implied resizing of 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 the
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 outer frame in order to accommodate the
size change.  Note that wrapping a menu or tool bar usually does not
resize the frame's outer size, hence this will alter the number of
displayed lines.

   Occasionally, such @dfn{implied frame resizing} may be unwanted, for
920
example, when the frame is maximized or made full-screen (where it's
921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961
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 outer 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 outer 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 outer frame), and @code{t} otherwise
(which means the outer 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


Glenn Morris's avatar
Glenn Morris committed
962 963 964 965 966 967 968 969
@node Frame Parameters
@section Frame Parameters
@cindex 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.

970 971 972 973 974 975 976 977 978
  Frame parameters exist mostly for the sake of graphical displays.
Most frame parameters have no effect when applied to a frame on a text
terminal; only the @code{height}, @code{width}, @code{name},
@code{title}, @code{menu-bar-lines}, @code{buffer-list} and
@code{buffer-predicate} parameters do something special.  If the
terminal supports colors, the parameters @code{foreground-color},
@code{background-color}, @code{background-mode} and
@code{display-type} are also meaningful.  If the terminal supports
frame transparency, the parameter @code{alpha} is also meaningful.
Glenn Morris's avatar
Glenn Morris committed
979 980 981

@menu
* Parameter Access::       How to change a frame's parameters.
Glenn Morris's avatar
Glenn Morris committed
982
* Initial Parameters::     Specifying frame parameters when you make a frame.
Glenn Morris's avatar
Glenn Morris committed
983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006
* Window Frame Parameters:: List of frame parameters for window systems.
* Geometry::               Parsing geometry specifications.
@end menu

@node Parameter Access
@subsection Access to Frame Parameters

These functions let you read and change the parameter values of a
frame.

@defun frame-parameter frame parameter
This function returns the value of the parameter @var{parameter} (a
symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
selected frame's parameter.  If @var{frame} has no setting for
@var{parameter}, this function returns @code{nil}.
@end defun

@defun frame-parameters &optional frame
The function @code{frame-parameters} returns an alist listing all the
parameters of @var{frame} and their values.  If @var{frame} is
@code{nil} or omitted, this returns the selected frame's parameters
@end defun

@defun modify-frame-parameters frame alist
1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018
This function alters the frame @var{frame} based on the elements of
@var{alist}.  Each element of @var{alist} has the form
@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming
a parameter.  If you don't mention a parameter in @var{alist}, its
value doesn't change.  If @var{frame} is @code{nil}, it defaults to
the selected frame.

Some parameters are only meaningful for frames on certain kinds of
display (@pxref{Frames}).  If @var{alist} includes parameters that are
not meaningful for the @var{frame}'s display, this function will
change its value in the frame's parameter list, but will otherwise
ignore it.
1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034

When @var{alist} specifies more than one parameter whose value can
affect the new size of @var{frame}, the final size of the frame may
differ according to the toolkit used.  For example, specifying that a
frame should from now on have a menu and/or tool bar instead of none and
simultaneously specifying the new height of the frame will inevitably
lead to a recalculation of the frame's height.  Conceptually, in such
case, this function will try to have the explicit height specification
prevail.  It cannot be excluded, however, that the addition (or removal)
of the menu or tool bar, when eventually performed by the toolkit, will
defeat this intention.

Sometimes, binding @code{frame-inhibit-implied-resize} (@pxref{Implied
Frame Resizing}) to a non-@code{nil} value around calls to this function
may fix the problem sketched here.  Sometimes, however, exactly such
binding may be hit by the problem.
Glenn Morris's avatar
Glenn Morris committed
1035 1036
@end defun

1037
@defun set-frame-parameter frame parm value
1038
This function sets the frame parameter @var{parm} to the specified
1039 1040
@var{value}.  If @var{frame} is @code{nil}, it defaults to the selected
frame.
1041 1042
@end defun

Glenn Morris's avatar
Glenn Morris committed
1043 1044 1045 1046 1047 1048 1049 1050 1051
@defun modify-all-frames-parameters alist
This function alters the frame parameters of all existing frames
according to @var{alist}, then modifies @code{default-frame-alist}
(and, if necessary, @code{initial-frame-alist}) to apply the same
parameter values to frames that will be created henceforth.
@end defun

@node Initial Parameters
@subsection Initial Frame Parameters
1052
@cindex parameters of initial frame
Glenn Morris's avatar
Glenn Morris committed
1053

1054 1055 1056
You can specify the parameters for the initial startup frame by
setting @code{initial-frame-alist} in your init file (@pxref{Init
File}).
Glenn Morris's avatar
Glenn Morris committed
1057

1058
@defopt initial-frame-alist
1059 1060
This variable's value is an alist of parameter values used when
creating the initial frame.  You can set this variable to specify the
Glenn Morris's avatar
Glenn Morris committed
1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085
appearance of the initial frame without altering subsequent frames.
Each element has the form:

@example
(@var{parameter} . @var{value})
@end example

Emacs creates the initial frame before it reads your init
file.  After reading that file, Emacs checks @code{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 effect before the frame is
created.  @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.

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 @code{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
@code{initial-frame-alist} with values that match the X resources.
1086
@end defopt
Glenn Morris's avatar
Glenn Morris committed
1087

1088
@cindex minibuffer-only frame
1089 1090 1091 1092
If these parameters include @code{(minibuffer . nil)}, that indicates
that the initial frame should have no minibuffer.  In this case, Emacs
creates a separate @dfn{minibuffer-only frame} as well.

1093
@defopt minibuffer-frame-alist
1094
This variable's value is an alist of parameter values used when
1095
creating an initial minibuffer-only frame (i.e., the minibuffer-only
1096 1097
frame that Emacs creates if @code{initial-frame-alist} specifies a
frame with no minibuffer).
1098
@end defopt
Glenn Morris's avatar
Glenn Morris committed
1099

1100
@defopt default-frame-alist
Glenn Morris's avatar
Glenn Morris committed
1101 1102 1103 1104 1105
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.

1106 1107 1108
Setting this variable does not affect existing frames.  Furthermore,
functions that display a buffer in a separate frame may override the
default parameters by supplying their own parameters.
1109
@end defopt
Glenn Morris's avatar
Glenn Morris committed
1110

1111 1112 1113
If you invoke Emacs with command-line options that specify frame
appearance, those options take effect by adding elements to either
@code{initial-frame-alist} or @code{default-frame-alist}.  Options
1114
which affect just the initial frame, such as @samp{--geometry} and
1115 1116 1117
@samp{--maximized}, add to @code{initial-frame-alist}; the others add
to @code{default-frame-alist}.  @pxref{Emacs Invocation,, Command Line
Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
Glenn Morris's avatar
Glenn Morris committed
1118 1119 1120

@node Window Frame Parameters
@subsection Window Frame Parameters
1121
@cindex frame parameters for windowed displays
Glenn Morris's avatar
Glenn Morris committed
1122 1123 1124 1125 1126 1127

  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, @code{name},
@code{title}, @code{height}, @code{width}, @code{buffer-list} and
@code{buffer-predicate} provide meaningful information in terminal
1128 1129
frames, and @code{tty-color-mode} is meaningful only for frames on
text terminals.
Glenn Morris's avatar
Glenn Morris committed
1130 1131 1132 1133 1134 1135 1136 1137 1138 1139

@menu
* 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.
* Management Parameters::       Communicating with the window manager.
* Cursor Parameters::           Controlling the cursor appearance.
1140
* Font and Color Parameters::   Fonts and colors for the frame text.
Glenn Morris's avatar
Glenn Morris committed
1141 1142 1143 1144 1145 1146 1147 1148 1149
@end menu

@node Basic Parameters
@subsubsection Basic Parameters

  These frame parameters give the most basic information about the
frame.  @code{title} and @code{name} are meaningful on all terminals.

@table @code
1150
@vindex display, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1151 1152
@item display
The display on which to open this frame.  It should be a string of the
1153 1154 1155
form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the
@env{DISPLAY} environment variable.  @xref{Multiple Terminals}, for
more details about display names.
Glenn Morris's avatar
Glenn Morris committed
1156

1157
@vindex display-type, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1158 1159 1160 1161 1162
@item display-type
This parameter describes the range of possible colors that can be used
in this frame.  Its value is @code{color}, @code{grayscale} or
@code{mono}.

1163
@vindex title, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1164
@item title
1165 1166 1167 1168 1169 1170
If a frame has a non-@code{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 @code{mode-line-frame-identification} uses
@samp{%F} (@pxref{%-Constructs}).  This is normally the case when
Emacs is not using a window system, and can only display one frame at
a time.  @xref{Frame Titles}.
Glenn Morris's avatar
Glenn Morris committed
1171

1172
@vindex name, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1173 1174 1175 1176 1177 1178 1179 1180 1181
@item name
The name of the frame.  The frame name serves as a default for the frame
title, if the @code{title} parameter is unspecified or @code{nil}.  If
you don't specify a name, Emacs sets the frame name automatically
(@pxref{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.
1182 1183 1184 1185 1186

@item 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 @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
1187 1188 1189 1190
@end table

@node Position Parameters
@subsubsection Position Parameters
1191
@cindex window position on display
1192
@cindex frame position
Glenn Morris's avatar
Glenn Morris committed
1193

1194 1195
  Position parameters' values are measured in pixels.  (Note that none
of these parameters exist on TTY frames.)
Glenn Morris's avatar
Glenn Morris committed
1196 1197

@table @code
1198
@vindex left, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1199
@item left
Glenn Morris's avatar
Glenn Morris committed
1200 1201
The position, in pixels, of the left (or right) edge of the frame with
respect to the left (or right) edge of the screen.  The value may be:
1202 1203 1204 1205 1206 1207 1208 1209 1210 1211

@table @asis
@item an integer
A positive integer relates the left edge of the frame to the left edge
of the screen.  A negative integer relates the right frame edge to the
right screen edge.

@item @code{(+ @var{pos})}
This specifies the position of the left frame edge relative to the left
screen edge.  The integer @var{pos} may be positive or negative; a
1212 1213
negative value specifies a position outside the screen or on a monitor
other than the primary one (for multi-monitor displays).
1214 1215 1216 1217

@item @code{(- @var{pos})}
This specifies the position of the right frame edge relative to the right
screen edge.  The integer @var{pos} may be positive or negative; a
1218 1219
negative value specifies a position outside the screen or on a monitor
other than the primary one (for multi-monitor displays).
1220
@end table
Glenn Morris's avatar
Glenn Morris committed
1221 1222 1223 1224 1225

Some window managers ignore program-specified positions.  If you want to
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.

1226 1227 1228 1229 1230
If the window manager refuses to align a frame at the left or top screen
edge, combining position notation and @code{user-position} as in

@example
(modify-frame-parameters
Martin Rudalics's avatar
Martin Rudalics committed
1231
  nil '((user-position . t) (left . (+ -4))))
1232 1233 1234 1235
@end example

may help to override that.

1236
@vindex top, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1237
@item top
1238 1239 1240
The screen position of the top (or bottom) edge, in pixels, with respect
to the top (or bottom) edge of the screen.  It works just like
@code{left}, except vertically instead of horizontally.
Glenn Morris's avatar
Glenn Morris committed
1241

1242
@vindex icon-left, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1243
@item icon-left
1244 1245 1246 1247 1248
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 @code{icon-top} and vice versa.
Glenn Morris's avatar
Glenn Morris committed
1249

1250
@vindex icon-top, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1251
@item icon-top
1252 1253 1254
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.
Glenn Morris's avatar
Glenn Morris committed
1255

1256
@vindex user-position, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1257 1258 1259 1260 1261 1262 1263
@item user-position
When you create a frame and specify its screen position with the
@code{left} and @code{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-@code{nil} value says the position was user-specified.

1264
@cindex window positions and window managers
Glenn Morris's avatar
Glenn Morris committed
1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277
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 @code{twm},
let the user specify whether to obey program-specified positions or
ignore them.

When you call @code{make-frame}, you should specify a non-@code{nil}
value for this parameter if the values of the @code{left} and @code{top}
parameters represent the user's stated preference; otherwise, use
@code{nil}.
@end table

1278

Glenn Morris's avatar
Glenn Morris committed
1279 1280
@node Size Parameters
@subsubsection Size Parameters
1281
@cindex window size on display
Glenn Morris's avatar
Glenn Morris committed
1282

1283 1284 1285
  Frame parameters specify frame sizes in character units.  On
graphical displays, the @code{default} face determines the actual
pixel sizes of these character units (@pxref{Face Attributes}).
Glenn Morris's avatar
Glenn Morris committed
1286 1287

@table @code
1288
@vindex height, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1289
@item height
1290
The height of the frame's text area (@pxref{Frame Geometry}), in
1291
characters.
Glenn Morris's avatar
Glenn Morris committed
1292

1293
@vindex width, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1294
@item width
1295
The width of the frame's text area (@pxref{Frame Geometry}), in
1296
characters.
Glenn Morris's avatar
Glenn Morris committed
1297

1298
@vindex user-size, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1299 1300
@item user-size
This does for the size parameters @code{height} and @code{width} what
1301 1302 1303
the @code{user-position} parameter (@pxref{Position Parameters,
user-position}) does for the position parameters @code{top} and
@code{left}.
Glenn Morris's avatar
Glenn Morris committed
1304

1305 1306 1307 1308
@cindex fullboth frames
@cindex fullheight frames
@cindex fullwidth frames
@cindex maximized frames
1309
@vindex fullscreen, a frame parameter
Glenn Morris's avatar
Glenn Morris committed
1310
@item fullscreen
1311
This parameter specifies whether to maximize the frame's width, height
1312 1313
or both.  Its value can be @code{fullwidth}, @code{fullheight},
@code{fullboth}, or @code{maximized}.  A @dfn{fullwidth} frame is as
Paul Eggert's avatar
Paul Eggert committed
1314
wide as possible, a @dfn{fullheight} frame is as tall as possible, and
1315
a @dfn{fullboth} frame is both as wide and as tall as possible.  A
1316
@dfn{maximized} frame is like a ``fullboth'' frame, except that it usually
1317
keeps its title bar and the buttons for resizing
1318
and closing the frame.  Also, maximized frames typically avoid hiding
1319
any task bar or panels displayed on the desktop.  A ``fullboth'' frame,
Paul Eggert's avatar
Paul Eggert committed
1320
on the other hand, usually omits the title bar and occupies the entire
1321 1322
available screen space.

1323
Full-height and full-width frames are more similar to maximized
1324 1325
frames in this regard.  However, these typically display an external
border which might be absent with maximized frames.  Hence the heights
1326 1327
of maximized and full-height frames and the widths of maximized and
full-width frames often differ by a few pixels.
1328 1329

With some window managers you may have to customize the variable
1330
@code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to
1331
make a frame truly appear maximized or full-screen.  Moreover,
1332
some window managers might not support smooth transition between the
1333
various full-screen or maximization states.  Customizing the variable
1334
@code{x-frame-normalize-before-maximize} can help to overcome that.
1335 1336 1337

@vindex fullscreen-restore, a frame parameter
@item fullscreen-restore
Paul Eggert's avatar
Paul Eggert committed
1338
This parameter specifies the desired fullscreen state of the frame
1339
after invoking the @code{toggle-frame-fullscreen} command (@pxref{Frame
1340
Commands,,, emacs, The GNU Emacs Manual}) in the ``fullboth'' state.
1341 1342
Normally this parameter is installed automatically by that command when
toggling the state to fullboth.  If, however, you start Emacs in the
1343
``fullboth'' state, you have to specify the desired behavior in your initial
1344 1345 1346 1347 1348 1349 1350 1351 1352
file as, for example

@example
(setq default-frame-alist
    '((fullscreen . fullboth) (fullscreen-restore . fullheight)))
@end example

This will give a new frame full height after typing in it @key{F11} for
the first time.
Glenn Morris's avatar
Glenn Morris committed
1353 1354
@end table