@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Frames, International, Windows, Top
+@node Frames
@chapter Frames and Graphical Displays
@cindex frames
- When Emacs is started on a graphical display, e.g.@: on the X Window
+ When Emacs is started on a graphical display, e.g., on the X Window
System, it occupies a graphical system-level ``window''. In this
manual, we call this a @dfn{frame}, reserving the word ``window'' for
the part of the frame used for displaying a buffer. A frame initially
This chapter describes Emacs features specific to graphical displays
(particularly mouse commands), and features for managing multiple
-frames. On text-only terminals, many of these features are
-unavailable. However, it is still possible to create multiple
-``frames'' on text-only terminals; such frames are displayed one at a
-time, filling the entire terminal screen (@pxref{Non-Window
-Terminals}). It is also possible to use the mouse on some text-only
-terminals (@pxref{Text-Only Mouse}, for doing so on GNU and Unix
-systems; and
+frames. On text terminals, many of these features are unavailable.
+However, it is still possible to create multiple ``frames'' on text
+terminals; such frames are displayed one at a time, filling the entire
+terminal screen (@pxref{Non-Window Terminals}). It is also possible
+to use the mouse on some text terminals (@pxref{Text-Only Mouse}, for
+doing so on GNU and Unix systems; and
@iftex
@pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features},
@end iftex
@ifnottex
@pxref{MS-DOS Mouse},
@end ifnottex
-for doing so on MS-DOS).
+for doing so on MS-DOS). Menus are supported on all text terminals.
@menu
* Mouse Commands:: Moving, cutting, and pasting, with the mouse.
* Tooltips:: Displaying information at the current mouse position.
* Mouse Avoidance:: Preventing the mouse pointer from obscuring text.
* Non-Window Terminals:: Multiple frames on terminals that show only one.
-* Text-Only Mouse:: Using the mouse in text-only terminals.
+* Text-Only Mouse:: Using the mouse in text terminals.
@end menu
@node Mouse Commands
@section Mouse Commands for Editing
@cindex mouse buttons (what they do)
+@cindex mouse, selecting text using
@kindex Mouse-1
@kindex Mouse-2
Move point to where you click (@code{mouse-set-point}).
@item Drag-Mouse-1
-Activate the region around the text selected by dragging, and copy it
-to the kill ring (@code{mouse-set-region}).
+Activate the region around the text selected by dragging, and put the
+text in the primary selection (@code{mouse-set-region}).
@item Mouse-2
-Yank the last killed text at the click position
-(@code{mouse-yank-at-click}).
+Move point to where you click, and insert the contents of the primary
+selection there (@code{mouse-yank-primary}).
@item Mouse-3
If the region is active, move the nearer end of the region to the
selects the frame, without doing anything else; clicking again selects
the window and sets the cursor position.
+@cindex mouse, dragging
@findex mouse-set-region
Holding down @kbd{Mouse-1} and ``dragging'' the mouse over a stretch
of text activates the region around that text
selection (@code{mouse-yank-primary}). @xref{Primary Selection}.
This behavior is consistent with other X applications. Alternatively,
you can rebind @kbd{Mouse-2} to @code{mouse-yank-at-click}, which
-performs a yank at point.
+performs a yank at the position you click.
@vindex mouse-yank-at-point
If you change the variable @code{mouse-yank-at-point} to a
@node Mouse References
@section Following References with the Mouse
-@kindex Mouse-1 @r{(selection)}
-@kindex Mouse-2 @r{(selection)}
+@kindex Mouse-1 @r{(on buttons)}
+@kindex Mouse-2 @r{(on buttons)}
@cindex hyperlinks
@cindex links
@cindex text buttons
@vindex mouse-highlight
Some Emacs buffers include @dfn{buttons}, or @dfn{hyperlinks}:
-pieces of text that perform some action (e.g.@: following a reference)
-when activated (e.g.@: by clicking on them). Usually, a button's text
+pieces of text that perform some action (e.g., following a reference)
+when activated (e.g., by clicking on them). Usually, a button's text
is visually highlighted: it is underlined, or a box is drawn around
it. If you move the mouse over a button, the shape of the mouse
cursor changes and the button lights up. If you change the variable
@key{RET}, or by clicking either @kbd{Mouse-1} or @kbd{Mouse-2} on the
button. For example, in a Dired buffer, each file name is a button;
activating it causes Emacs to visit that file (@pxref{Dired}). In a
-@samp{*Compilation*} buffer, each error message is a button, and
+@file{*Compilation*} buffer, each error message is a button, and
activating it visits the source code for that error
(@pxref{Compilation}).
@kindex C-x 5 1
@findex delete-other-frames
Delete all frames on the current terminal, except the selected one.
+
+@item M-<F10>
+@kindex M-<F10>
+@findex toggle-frame-maximized
+Toggle the maximization state of the current frame. When a frame is
+maximized, it fills the screen.
+
+@item <F11>
+@kindex <F11>
+@findex toggle-frame-fullscreen
+Toggle fullscreen mode for the current frame. (The difference
+between ``fullscreen'' and ``maximized'' is normally that the former
+hides window manager decorations, giving slightly more screen space to
+Emacs itself.)
@end table
+ Note that 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 truly ``maximized'' or ``fullscreen''.
+
The @kbd{C-x 5 0} (@code{delete-frame}) command deletes the selected
frame. However, it will refuse to delete the last frame in an Emacs
session, to prevent you from losing the ability to interact with the
The @kbd{C-x 5 1} (@code{delete-other-frames}) command deletes all
other frames on the current terminal (this terminal refers to either a
-graphical display, or a text-only terminal; @pxref{Non-Window
-Terminals}). If the Emacs session has frames open on other graphical
-displays or text terminals, those are not deleted.
+graphical display, or a text terminal; @pxref{Non-Window Terminals}).
+If the Emacs session has frames open on other graphical displays or
+text terminals, those are not deleted.
@vindex focus-follows-mouse
The @kbd{C-x 5 o} (@code{other-frame}) command selects the next
@cindex fonts
By default, Emacs displays text on graphical displays using a
-12-point monospace font. There are several different ways to specify
+10-point monospace font. There are several different ways to specify
a different font:
@itemize
@item
-Click on @samp{Set Default Font} in the @samp{Options} menu. To save
-this for future sessions, click on @samp{Save Options} in the
+Click on @samp{Set Default Font} in the @samp{Options} menu. This
+makes the selected font the default on all existing graphical frames.
+To save this for future sessions, click on @samp{Save Options} in the
@samp{Options} menu.
@item
-Add a line to your init file (@pxref{Init File}), modifying the
-variable @code{default-frame-alist} to specify the @code{font}
-parameter (@pxref{Creating Frames}), like this:
+Add a line to your init file, modifying the variable
+@code{default-frame-alist} to specify the @code{font} parameter
+(@pxref{Frame Parameters}), like this:
-@smallexample
-(add-to-list 'default-frame-alist '(font . "DejaVu Sans Mono-10"))
-@end smallexample
+@example
+(add-to-list 'default-frame-alist
+ '(font . "DejaVu Sans Mono-10"))
+@end example
+
+@noindent
+This makes the font the default on all graphical frames created after
+restarting Emacs with that init file.
@cindex X defaults file
@cindex X resources file
Add an @samp{emacs.font} X resource setting to your X resource file,
like this:
-@smallexample
+@example
emacs.font: DejaVu Sans Mono-12
-@end smallexample
+@end example
@noindent
You must restart X, or use the @command{xrdb} command, for the X
-resources file to take effect. @xref{Resources}. When specifying a
-font in your X resources file, you should not quote it.
+resources file to take effect. @xref{Resources}. Do not quote
+font names in X resource files.
@item
If you are running Emacs on the GNOME desktop, you can tell Emacs to
first is to use a @dfn{Fontconfig pattern}. Fontconfig patterns have
the following form:
-@smallexample
+@example
@var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]...
-@end smallexample
+@end example
@noindent
Within this format, any of the elements in braces may be omitted.
@noindent
Here are some examples of Fontconfig patterns:
-@smallexample
+@example
Monospace
Monospace-12
Monospace-12:bold
DejaVu Sans Mono:bold:italic
Monospace-12:weight=bold:slant=italic
-@end smallexample
+@end example
For a more detailed description of Fontconfig patterns, see the
Fontconfig manual, which is distributed with Fontconfig and available
The second way to specify a font is to use a @dfn{GTK font pattern}.
These have the syntax
-@smallexample
+@example
@var{fontname} [@var{properties}] [@var{fontsize}]
-@end smallexample
+@end example
@noindent
where @var{fontname} is the family name, @var{properties} is a list of
@noindent
Here are some examples of GTK font patterns:
-@smallexample
+@example
Monospace 12
Monospace Bold Italic 12
-@end smallexample
+@end example
@cindex XLFD
@cindex X Logical Font Description
The third way to specify a font is to use an @dfn{XLFD} (@dfn{X
Logical Font Description}). This is the traditional method for
-specifying fonts under X. Each XLFD consists of fourteen words or
+specifying fonts under X@. Each XLFD consists of fourteen words or
numbers, separated by dashes, like this:
-@smallexample
+@example
-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
-@end smallexample
+@end example
@noindent
A wildcard character (@samp{*}) in an XLFD matches any sequence of
character. However, matching is implementation-dependent, and can be
inaccurate when wildcards match dashes in a long name. For reliable
results, supply all 14 dashes and use wildcards only within a field.
-Case is insignificant in an XLFD. The syntax for an XLFD is as
+Case is insignificant in an XLFD@. The syntax for an XLFD is as
follows:
-@smallexample
+@example
-@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding}
-@end smallexample
+@end example
@noindent
The entries have the following meanings:
@item maker
The name of the font manufacturer.
@item family
-The name of the font family (e.g.@: @samp{courier}).
+The name of the font family (e.g., @samp{courier}).
@item weight
The font weight---normally either @samp{bold}, @samp{medium} or
@samp{light}. Some font names support other values.
Some font names support other values.
@item widthtype
The font width---normally @samp{normal}, @samp{condensed},
-@samp{extended}, or @samp{semicondensed} (some font names support
-other values).
+@samp{semicondensed}, or @samp{extended}. Some font names support
+other values.
@item style
An optional additional style name. Usually it is empty---most XLFDs
have two hyphens in a row at this point.
instead of a normal font specification. For instance, @samp{6x13} is
equivalent to
-@smallexample
+@example
-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
-@end smallexample
+@end example
@cindex client-side fonts
@cindex server-side fonts
hiding its contents.
You navigate through the speedbar using the keyboard, too. Typing
-@kbd{RET} while point is on a line in the speedbar is equivalent to
-clicking the item on the current line, and @kbd{SPC} expands or
+@key{RET} while point is on a line in the speedbar is equivalent to
+clicking the item on the current line, and @key{SPC} expands or
contracts the item. @kbd{U} displays the parent directory of the
current directory. To copy, delete, or rename the file on the current
line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a
@section Scroll Bars
@cindex Scroll Bar mode
@cindex mode, Scroll Bar
+@cindex Vertical Scroll Bar
- On graphical displays, there is a @dfn{scroll bar} on the side of
-each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's up and
-down buttons scrolls the window by one line at a time. Clicking
+ On graphical displays, there is a @dfn{vertical scroll bar} on the
+side of each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's
+up and down buttons scrolls the window by one line at a time. Clicking
@kbd{Mouse-1} above or below the scroll bar's inner box scrolls the
window by nearly the entire height of the window, like @kbd{M-v} and
@kbd{C-v} respectively (@pxref{Moving Point}). Dragging the inner box
@findex scroll-bar-mode
@findex toggle-scroll-bar
- To toggle the use of scroll bars, type @kbd{M-x scroll-bar-mode}.
-This command applies to all frames, including frames yet to be
-created. To toggle scroll bars for just the selected frame, use the
-command @kbd{M-x toggle-scroll-bar}.
+ To toggle the use of vertical scroll bars, type @kbd{M-x
+scroll-bar-mode}. This command applies to all frames, including frames
+yet to be created. To toggle vertical scroll bars for just the selected
+frame, use the command @kbd{M-x toggle-scroll-bar}.
@vindex scroll-bar-mode
- To control the use of scroll bars at startup, customize the variable
-@code{scroll-bar-mode}. Its value should be either @code{right} (put
-scroll bars on the right side of windows), @code{left} (put them on
-the left), or @code{nil} (disable scroll bars). By default, Emacs
-puts scroll bars on the right if it was compiled with GTK+ support on
-the X Window System, and on MS-Windows or Mac OS; Emacs puts scroll
-bars on the left if compiled on the X Window system without GTK+
-support (following the old convention for X applications).
+ To control the use of vertical scroll bars at startup, customize the
+variable @code{scroll-bar-mode}. Its value should be either
+@code{right} (put scroll bars on the right side of windows), @code{left}
+(put them on the left), or @code{nil} (disable vertical scroll bars).
+By default, Emacs puts scroll bars on the right if it was compiled with
+GTK+ support on the X Window System, and on MS-Windows or Mac OS; Emacs
+puts scroll bars on the left if compiled on the X Window System without
+GTK+ support (following the old convention for X applications).
@vindex scroll-bar-width
-@cindex width of the scroll bar
+@cindex width of the vertical scroll bar
You can also use the X resource @samp{verticalScrollBars} to enable
or disable the scroll bars (@pxref{Resources}). To control the scroll
bar width, change the @code{scroll-bar-width} frame parameter
(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}).
+@vindex scroll-bar-adjust-thumb-portion
+@cindex overscrolling
+If you're using Emacs on X (with GTK+ or Motif), you can customize the
+variable @code{scroll-bar-adjust-thumb-portion} to control
+@dfn{overscrolling} of the scroll bar, i.e. dragging the thumb down even
+when the end of the buffer is visible. If its value is
+non-@code{nil}, the scroll bar can be dragged downwards even if the
+end of the buffer is shown; if @code{nil}, the thumb will be at the
+bottom when the end of the buffer is shown. You can not over-scroll
+when the entire buffer is visible.
+
+@cindex Horizontal Scroll Bar
+@cindex Horizontal Scroll Bar mode
+ On graphical displays with toolkit support, Emacs may also supply a
+@dfn{horizontal scroll bar} on the bottom of each window. Clicking
+@kbd{Mouse-1} on the that scroll bar's left and right buttons scrolls
+the window horizontally by one column at a time. Clicking @kbd{Mouse-1}
+on the left or right of the scroll bar's inner box scrolls the window by
+four columns. Dragging the inner box scrolls the window continuously.
+
+ Note that such horizontal scrolling can make the window's position of
+point disappear on the left or the right. Typing a character to insert
+text or moving point with a keyboard command will usually bring it back
+into view.
+
+@findex horizontal-scroll-bar-mode
+ To toggle the use of horizontal scroll bars, type @kbd{M-x
+horizontal-scroll-bar-mode}. This command applies to all frames,
+including frames yet to be created. To toggle horizontal scroll bars
+for just the selected frame, use the command @kbd{M-x
+toggle-horizontal-scroll-bar}.
+
+@vindex horizontal-scroll-bar-mode
+ To control the use of horizontal scroll bars at startup, customize the
+variable @code{horizontal-scroll-bar-mode}.
+
+@vindex scroll-bar-height
+@cindex height of the horizontal scroll bar
+ You can also use the X resource @samp{horizontalScrollBars} to enable
+or disable horizontal scroll bars (@pxref{Resources}). To control the
+scroll bar height, change the @code{scroll-bar-height} frame parameter
+(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}).
+
+
@node Drag and Drop
@section Drag and Drop
@cindex drag and drop
@code{menu-bar-mode}.
@kindex C-Mouse-3 @r{(when menu bar is disabled)}
- Expert users often turn off the menu bar, especially on text-only
+ Expert users often turn off the menu bar, especially on text
terminals, where this makes one additional line available for text.
If the menu bar is off, you can still pop up a menu of its contents
with @kbd{C-Mouse-3} on a display which supports pop-up menus.
face, and by X resources (@pxref{X Resources}).
@dfn{GUD tooltips} are special tooltips that show the values of
-variables when debugging a program with GUD. @xref{Debugger
+variables when debugging a program with GUD@. @xref{Debugger
Operation}.
@node Mouse Avoidance
@table @code
@item banish
-Move the mouse to the upper-right corner on any key-press;
+Move the pointer to a corner of the frame on any key-press. You can
+customize the variable @code{mouse-avoidance-banish-position} to
+specify where the pointer goes when it is banished.
@item exile
-Move the mouse to the corner only if the cursor gets too close,
-and allow it to return once the cursor is out of the way;
+Banish the pointer only if the cursor gets too close, and allow it to
+return once the cursor is out of the way.
@item jump
-If the cursor gets too close to the mouse, displace the mouse
-a random distance & direction;
+If the cursor gets too close to the pointer, displace the pointer by a
+random distance and direction.
@item animate
-As @code{jump}, but shows steps along the way for illusion of motion;
+As @code{jump}, but shows steps along the way for illusion of motion.
@item cat-and-mouse
-The same as @code{animate};
+The same as @code{animate}.
@item proteus
As @code{animate}, but changes the shape of the mouse pointer too.
@end table
@node Non-Window Terminals
@section Non-Window Terminals
-@cindex text-only terminal
+@cindex text terminal
- On a text-only terminal, Emacs can display only one Emacs frame at a
+ On a text terminal, Emacs can display only one Emacs frame at a
time. However, you can still create multiple Emacs frames, and switch
between them. Switching frames on these terminals is much like
switching between different window configurations.
in the mode line when the frame is selected.
@node Text-Only Mouse
-@section Using a Mouse in Text-only Terminals
+@section Using a Mouse in Text Terminals
@cindex mouse support
@cindex terminal emulators, mouse support
-Some text-only terminals support mouse clicks in the terminal window.
+Some text terminals support mouse clicks in the terminal window.
@cindex xterm
In a terminal emulator which is compatible with @command{xterm}, you
running on your system in order for this to work.
@iftex
-@pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features},
+@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features},
@end iftex
@ifnottex
-@pxref{MS-DOS Mouse},
+@xref{MS-DOS Mouse},
@end ifnottex
for information about mouse support on MS-DOS.