0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @node Frames
0006: @chapter Frames and Graphical Displays
0007: @cindex frames
0008: 
0009:   When Emacs is started on a graphical display, e.g., on the X Window
0010: System, it occupies a graphical system-level display region.  In this
0011: manual, we call this a @dfn{frame}, reserving the word ``window'' for
0012: the part of the frame used for displaying a buffer.  A frame initially
0013: contains one window, but it can be subdivided into multiple windows
0014: (@pxref{Windows}).  A frame normally also contains a menu bar, tool
0015: bar, and echo area.
0016: 
0017:   You can also create additional frames (@pxref{Creating Frames}).
0018: All frames created in the same Emacs session have access to the same
0019: underlying buffers and other data.  For instance, if a buffer is being
0020: shown in more than one frame, any changes made to it in one frame show
0021: up immediately in the other frames too.
0022: 
0023:   Typing @kbd{C-x C-c} closes all the frames on the current display,
0024: and ends the Emacs session if it has no frames open on any other
0025: displays (@pxref{Exiting}).  To close just the selected frame, type
0026: @kbd{C-x 5 0} (that is zero, not @kbd{o}).
0027: 
0028:   This chapter describes Emacs features specific to graphical displays
0029: (particularly mouse commands), and features for managing multiple
0030: frames.  On text terminals, many of these features are unavailable.
0031: However, it is still possible to create multiple frames on text
0032: terminals; such frames are displayed one at a time, filling the entire
0033: terminal screen (@pxref{Non-Window Terminals}).  It is also possible
0034: to use the mouse on some text terminals (@pxref{Text-Only Mouse}, for
0035: doing so on GNU and Unix systems; and
0036: @iftex
0037: @pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features},
0038: @end iftex
0039: @ifnottex
0040: @pxref{MS-DOS Mouse},
0041: @end ifnottex
0042: for doing so on MS-DOS).  Menus are supported on all text terminals.
0043: 
0044: @menu
0045: * Mouse Commands::      Moving, cutting, and pasting, with the mouse.
0046: * Word and Line Mouse:: Mouse commands for selecting whole words or lines.
0047: * Mouse References::    Using the mouse to select an item from a list.
0048: * Menu Mouse Clicks::   Mouse clicks that bring up menus.
0049: * Mode Line Mouse::     Mouse clicks on the mode line.
0050: * Creating Frames::     Creating additional Emacs frames with various contents.
0051: * Frame Commands::      Iconifying, deleting, and switching frames.
0052: * Fonts::               Changing the frame font.
0053: * Speedbar::            How to make and use a speedbar frame.
0054: * Multiple Displays::   How one Emacs instance can talk to several displays.
0055: * Frame Parameters::    Changing the colors and other modes of frames.
0056: * Scroll Bars::         How to enable and disable scroll bars; how to use them.
0057: * Window Dividers::     Window separators that can be dragged with the mouse.
0058: * Drag and Drop::       Using drag and drop to open files and insert text.
0059: * Menu Bars::           Enabling and disabling the menu bar.
0060: * Tool Bars::           Enabling and disabling the tool bar.
0061: * Dialog Boxes::        Controlling use of dialog boxes.
0062: * Tooltips::            Displaying information at the current mouse position.
0063: * Mouse Avoidance::     Preventing the mouse pointer from obscuring text.
0064: * Non-Window Terminals::  Multiple frames on terminals that show only one.
0065: * Text-Only Mouse::     Using the mouse in text terminals.
0066: @end menu
0067: 
0068: @node Mouse Commands
0069: @section Mouse Commands for Editing
0070: @cindex mouse buttons (what they do)
0071: @cindex mouse, selecting text using
0072: 
0073: @kindex mouse-1
0074: @kindex mouse-2
0075: @kindex mouse-3
0076: @table @kbd
0077: @item mouse-1
0078: Move point to where you click (@code{mouse-set-point}).
0079: 
0080: @item Drag-mouse-1
0081: Activate the region around the text selected by dragging, and put the
0082: text in the primary selection (@code{mouse-set-region}).
0083: 
0084: @item mouse-2
0085: Move point to where you click, and insert the contents of the primary
0086: selection there (@code{mouse-yank-primary}).
0087: 
0088: @item mouse-3
0089: If the region is active, move the nearer end of the region to the
0090: click position; otherwise, set mark at the current value of point and
0091: point at the click position.  Save the resulting region in the kill
0092: ring; on a second click, kill it (@code{mouse-save-then-kill}).
0093: @end table
0094: 
0095: @findex mouse-set-point
0096:   The most basic mouse command is @code{mouse-set-point}, which is
0097: invoked by clicking with the left mouse button, @kbd{mouse-1}, in the
0098: text area of a window.  This moves point to the position where you
0099: clicked.  If that window was not the selected window, it becomes the
0100: selected window.  You can also activate a region by double-clicking
0101: @kbd{mouse-1} (@pxref{Word and Line Mouse}).
0102: 
0103: @vindex x-mouse-click-focus-ignore-position
0104:   Normally, if the frame you clicked in was not the selected frame, it
0105: is made the selected frame, in addition to selecting the window and
0106: setting the cursor.  On the X Window System, you can change this by
0107: setting the variable @code{x-mouse-click-focus-ignore-position} to
0108: @code{t}.  In that case, the initial click on an unselected frame just
0109: selects the frame, without doing anything else; clicking again selects
0110: the window and sets the cursor position.
0111: 
0112: @cindex mouse, dragging
0113: @findex mouse-set-region
0114:   Holding down @kbd{mouse-1} and dragging the mouse over a stretch
0115: of text activates the region around that text
0116: (@code{mouse-set-region}), placing the mark where you started holding
0117: down the mouse button, and point where you release it (@pxref{Mark}).
0118: In addition, the text in the region becomes the primary selection
0119: (@pxref{Primary Selection}).
0120: 
0121: @vindex mouse-drag-copy-region
0122:   If you change the variable @code{mouse-drag-copy-region} to a
0123: non-@code{nil} value, dragging the mouse over a stretch of text also
0124: adds the text to the kill ring.  The default is @code{nil}.
0125: 
0126: @vindex mouse-scroll-min-lines
0127:   If you move the mouse off the top or bottom of the window while
0128: dragging, the window scrolls at a steady rate until you move the mouse
0129: back into the window.  This way, you can select regions that don't fit
0130: entirely on the screen.  The number of lines scrolled per step depends
0131: on how far away from the window edge the mouse has gone; the variable
0132: @code{mouse-scroll-min-lines} specifies a minimum step size.
0133: 
0134: @findex mouse-yank-primary
0135: @findex mouse-yank-at-click
0136:   Clicking with the middle mouse button, @kbd{mouse-2}, moves point to
0137: the position where you clicked and inserts the contents of the primary
0138: selection (@code{mouse-yank-primary}).  @xref{Primary Selection}.
0139: This behavior is consistent with other X applications.  Alternatively,
0140: you can rebind @kbd{mouse-2} to @code{mouse-yank-at-click}, which
0141: performs a yank at the position you click.
0142: 
0143: @vindex mouse-yank-at-point
0144:   If you change the variable @code{mouse-yank-at-point} to a
0145: non-@code{nil} value, @kbd{mouse-2} does not move point; it inserts
0146: the text at point, regardless of where you clicked or even which of
0147: the frame's windows you clicked on.  This variable affects both
0148: @code{mouse-yank-primary} and @code{mouse-yank-at-click}.
0149: 
0150: @findex mouse-save-then-kill
0151:   Clicking with the right mouse button, @kbd{mouse-3}, runs the
0152: command @code{mouse-save-then-kill}.  This performs several actions
0153: depending on where you click and the status of the region:
0154: 
0155: @itemize @bullet
0156: @item
0157: If no region is active, clicking @kbd{mouse-3} activates the region,
0158: placing the mark where point was and point at the clicked position.
0159: 
0160: @item
0161: If a region is active, clicking @kbd{mouse-3} adjusts the nearer end
0162: of the region by moving it to the clicked position.  The adjusted
0163: region's text is copied to the kill ring; if the text in the original
0164: region was already on the kill ring, it replaces it there.
0165: 
0166: @item
0167: If you originally specified the region using a double or triple
0168: @kbd{mouse-1}, so that the region is defined to consist of entire
0169: words or lines (@pxref{Word and Line Mouse}), then adjusting the
0170: region with @kbd{mouse-3} also proceeds by entire words or lines.
0171: 
0172: @item
0173: If you use @kbd{mouse-3} a second time consecutively, at the same
0174: place, that kills the region already selected.  Thus, the simplest way
0175: to kill text with the mouse is to click @kbd{mouse-1} at one end, then
0176: click @kbd{mouse-3} twice at the other end.  To copy the text into the
0177: kill ring without deleting it from the buffer, press @kbd{mouse-3}
0178: just once---or just drag across the text with @kbd{mouse-1}.  Then you
0179: can copy it elsewhere by yanking it.
0180: @end itemize
0181: 
0182:   The @code{mouse-save-then-kill} command also obeys the variable
0183: @code{mouse-drag-copy-region} (described above).  If the value is
0184: non-@code{nil}, then whenever the command sets or adjusts the active
0185: region, the text in the region is also added to the kill ring.  If the
0186: latest kill ring entry had been added the same way, that entry is
0187: replaced rather than making a new entry.
0188: 
0189:   Whenever you set the region using any of the mouse commands
0190: described above, the mark will be deactivated by any subsequent
0191: unshifted cursor motion command, in addition to the usual ways of
0192: deactivating the mark.  @xref{Shift Selection}.
0193: 
0194: @cindex mouse wheel
0195: @findex mouse-wheel-mode
0196: @cindex Mouse Wheel minor mode
0197: @cindex mode, Mouse Wheel
0198: @vindex mouse-wheel-follow-mouse
0199: @vindex mouse-wheel-scroll-amount
0200: @vindex mouse-wheel-progressive-speed
0201:   Some mice have a ``wheel'' which can be used for scrolling.  Emacs
0202: supports scrolling windows with the mouse wheel, by default, on most
0203: graphical displays.  To toggle this feature, use @kbd{M-x
0204: mouse-wheel-mode}.  The variables @code{mouse-wheel-follow-mouse} and
0205: @code{mouse-wheel-scroll-amount} determine where and by how much
0206: buffers are scrolled.  The variable
0207: @code{mouse-wheel-progressive-speed} determines whether the scroll
0208: speed is linked to how fast you move the wheel.
0209: 
0210: @vindex mouse-wheel-tilt-scroll
0211: @vindex mouse-wheel-flip-direction
0212: Emacs can also support horizontal scrolling if your mouse's wheel can
0213: be tilted.  This feature is off by default; the variable
0214: @code{mouse-wheel-tilt-scroll} turns it on.  If you'd like to reverse
0215: the direction of horizontal scrolling, customize the variable
0216: @code{mouse-wheel-flip-direction} to a non-@code{nil} value.
0217: 
0218: 
0219: @node Word and Line Mouse
0220: @section Mouse Commands for Words and Lines
0221: 
0222:   These variants of @kbd{mouse-1} select entire words or lines at a
0223: time.  Emacs activates the region around the selected text, which is
0224: also copied to the kill ring.
0225: 
0226: @table @kbd
0227: @item Double-mouse-1
0228: Select the text around the word or character which you click on.
0229: 
0230: Double-clicking on a character with symbol syntax (such as
0231: underscore, in C mode) selects the symbol surrounding that character.
0232: Double-clicking on a character with open- or close-parenthesis syntax
0233: selects the parenthetical grouping which that character starts or
0234: ends.  Double-clicking on a character with string-delimiter syntax
0235: (such as a single-quote or double-quote in C) selects the string
0236: constant (Emacs uses heuristics to figure out whether that character
0237: is the beginning or the end of it).
0238: 
0239: Double-clicking on the beginning of a parenthetical grouping or
0240: beginning string-delimiter moves point to the end of the region,
0241: scrolling the buffer display forward if necessary to show the new
0242: location of point.  Double-clicking on the end of a parenthetical
0243: grouping or end string-delimiter keeps point at the end of the region
0244: by default, so the beginning of the region will not be visible if it
0245: is above the top of the window; setting the user option
0246: @code{mouse-select-region-move-to-beginning} to non-@code{nil} changes
0247: this to move point to the beginning of the region, scrolling the
0248: display backward if necessary.
0249: 
0250: @item Double-Drag-mouse-1
0251: Select the text you drag across, in units of whole words.
0252: 
0253: @item Triple-mouse-1
0254: Select the line you click on.
0255: 
0256: @item Triple-Drag-mouse-1
0257: Select the text you drag across, in units of whole lines.
0258: @end table
0259: 
0260: @node Mouse References
0261: @section Following References with the Mouse
0262: @kindex mouse-1 @r{(on buttons)}
0263: @kindex mouse-2 @r{(on buttons)}
0264: @cindex hyperlinks
0265: @cindex links
0266: @cindex text buttons
0267: @cindex buttons
0268: 
0269: @vindex mouse-highlight
0270:   Some Emacs buffers include @dfn{buttons}, or @dfn{hyperlinks}:
0271: pieces of text that perform some action (e.g., following a reference)
0272: when activated (e.g., by clicking on them).  Usually, a button's text
0273: is visually highlighted: it is underlined, or a box is drawn around
0274: it.  If you move the mouse over a button, the shape of the mouse
0275: cursor changes and the button lights up.  If you change the variable
0276: @code{mouse-highlight} to @code{nil}, Emacs disables this
0277: highlighting.
0278: 
0279:   You can activate a button by moving point to it and typing
0280: @key{RET}, or by clicking either @kbd{mouse-1} or @kbd{mouse-2} on the
0281: button.  For example, in a Dired buffer, each file name is a button;
0282: activating it causes Emacs to visit that file (@pxref{Dired}).  In a
0283: @file{*Compilation*} buffer, each error message is a button, and
0284: activating it visits the source code for that error
0285: (@pxref{Compilation}).
0286: 
0287:   Although clicking @kbd{mouse-1} on a button usually activates the
0288: button, if you hold the mouse button down for a period of time before
0289: releasing it (specifically, for more than 450 milliseconds), then
0290: Emacs moves point where you clicked, without activating the button.
0291: In this way, you can use the mouse to move point over a button without
0292: activating it.  Dragging the mouse over or onto a button has its usual
0293: behavior of setting the region, and does not activate the button.
0294: 
0295:   You can change how @kbd{mouse-1} applies to buttons by customizing
0296: the variable @code{mouse-1-click-follows-link}.  If the value is a
0297: positive integer, that determines how long you need to hold the mouse
0298: button down for, in milliseconds, to cancel button activation; the
0299: default is 450, as described in the previous paragraph.  If the value
0300: is @code{nil}, @kbd{mouse-1} just sets point where you clicked, and
0301: does not activate buttons.  If the value is @code{double}, double
0302: clicks activate buttons but single clicks just set point.
0303: 
0304: @vindex mouse-1-click-in-non-selected-windows
0305:   Normally, @kbd{mouse-1} on a button activates the button even if it
0306: is in a non-selected window.  If you change the variable
0307: @code{mouse-1-click-in-non-selected-windows} to @code{nil},
0308: @kbd{mouse-1} on a button in an unselected window moves point to the
0309: clicked position and selects that window, without activating the
0310: button.
0311: 
0312: @node Menu Mouse Clicks
0313: @section Mouse Clicks for Menus
0314: 
0315:   Several mouse clicks with the @key{Ctrl} and @key{SHIFT} modifiers
0316: bring up menus.
0317: 
0318: @table @kbd
0319: @item C-mouse-1
0320: @kindex C-mouse-1
0321: This menu is for selecting a buffer.
0322: 
0323: The MSB (``mouse select buffer'') global minor mode makes this
0324: menu smarter and more customizable.  @xref{Buffer Menus}.
0325: 
0326: @item C-mouse-2
0327: @kindex C-mouse-2
0328: This menu contains entries for examining faces and other text
0329: properties, and well as for setting them (the latter is mainly useful
0330: when editing enriched text; @pxref{Enriched Text}).
0331: 
0332: @item C-mouse-3
0333: @kindex C-mouse-3
0334: This menu is mode-specific.  For most modes if Menu-bar mode is on,
0335: this menu has the same items as all the mode-specific menu-bar menus
0336: put together.  Some modes may specify a different menu for this
0337: button.  If Menu Bar mode is off, this menu contains all the items
0338: which would be present in the menu bar---not just the mode-specific
0339: ones---so that you can access them without having to display the menu
0340: bar.
0341: 
0342: @item S-mouse-1
0343: This menu is for changing the default face within the window's buffer.
0344: @xref{Text Scale}.
0345: @end table
0346: 
0347:   Some graphical applications use @kbd{mouse-3} for a mode-specific
0348: menu.  If you prefer @kbd{mouse-3} in Emacs to bring up such a menu
0349: instead of running the @code{mouse-save-then-kill} command, rebind
0350: @kbd{mouse-3} by adding the following line to your init file
0351: (@pxref{Init Rebinding}):
0352: 
0353: @c FIXME: `mouse-popup-menubar-stuff' is obsolete since 23.1.
0354: @smallexample
0355: (global-set-key [mouse-3] 'mouse-popup-menubar-stuff)
0356: @end smallexample
0357: 
0358: @node Mode Line Mouse
0359: @section Mode Line Mouse Commands
0360: @cindex mode line, mouse
0361: @cindex mouse on mode line
0362: 
0363:   You can use mouse clicks on window mode lines to select and manipulate
0364: windows.
0365: 
0366:   Some areas of the mode line, such as the buffer name, and major and minor
0367: mode names, have their own special mouse bindings.  These areas are
0368: highlighted when you hold the mouse over them, and information about
0369: the special bindings will be displayed (@pxref{Tooltips}).  This
0370: section's commands do not apply in those areas.
0371: 
0372: @table @kbd
0373: @item mouse-1
0374: @kindex mouse-1 @r{(mode line)}
0375: @kbd{mouse-1} on a mode line selects the window it belongs to.  By
0376: dragging @kbd{mouse-1} on the mode line, you can move it, thus
0377: changing the height of the windows above and below.  Changing heights
0378: with the mouse in this way never deletes windows, it just refuses to
0379: make any window smaller than the minimum height.
0380: 
0381: @item mouse-2
0382: @kindex mouse-2 @r{(mode line)}
0383: @kbd{mouse-2} on a mode line expands that window to fill its frame.
0384: 
0385: @item mouse-3
0386: @kindex mouse-3 @r{(mode line)}
0387: @kbd{mouse-3} on a mode line deletes the window it belongs to.  If the
0388: frame has only one window, it does nothing.
0389: 
0390: @item C-mouse-2
0391: @kbd{C-mouse-2} on a mode line splits that window, producing two
0392: side-by-side windows with the boundary running through the click
0393: position (@pxref{Split Window}).
0394: @end table
0395: 
0396: @kindex mouse-1 @r{(scroll bar)}
0397:   Furthermore, by clicking and dragging @kbd{mouse-1} on the divider
0398: between two side-by-side mode lines, you can move the vertical
0399: boundary to the left or right.
0400: 
0401:   Note that resizing windows is affected by the value of
0402: @code{window-resize-pixelwise}, see @ref{Split Window}.
0403: 
0404: @node Creating Frames
0405: @section Creating Frames
0406: @cindex creating frames
0407: 
0408: @kindex C-x 5
0409:   The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}.  Whereas
0410: each @kbd{C-x 4} command pops up a buffer in a different window in the
0411: selected frame (@pxref{Pop Up Window}), the @kbd{C-x 5} commands use a
0412: different frame.  If an existing visible or iconified (a.k.a.@:
0413: ``minimized'', @pxref{Visibility of Frames,,, elisp, The Emacs Lisp
0414: Reference Manual}) frame already displays the requested buffer, that
0415: frame is raised and deiconified (``un-minimized''); otherwise, a new
0416: frame is created on the current display terminal.
0417: 
0418:   The various @kbd{C-x 5} commands differ in how they find or create the
0419: buffer to select:
0420: 
0421: @table @kbd
0422: @item C-x 5 2
0423: @kindex C-x 5 2
0424: @findex make-frame-command
0425: Create a new frame (@code{make-frame-command}).
0426: @item C-x 5 b @var{bufname} @key{RET}
0427: Select buffer @var{bufname} in another frame.  This runs
0428: @code{switch-to-buffer-other-frame}.
0429: @item C-x 5 f @var{filename} @key{RET}
0430: Visit file @var{filename} and select its buffer in another frame.  This
0431: runs @code{find-file-other-frame}.  @xref{Visiting}.
0432: @item C-x 5 d @var{directory} @key{RET}
0433: Select a Dired buffer for directory @var{directory} in another frame.
0434: This runs @code{dired-other-frame}.  @xref{Dired}.
0435: @item C-x 5 m
0436: Start composing a mail message in another frame.  This runs
0437: @code{compose-mail-other-frame}.  It is the other-frame variant of
0438: @kbd{C-x m}.  @xref{Sending Mail}.
0439: @item C-x 5 .
0440: Find the definition of an identifier in another frame.  This runs
0441: @code{xref-find-definitions-other-frame}, the multiple-frame variant
0442: of @kbd{M-.}.  @xref{Xref}.
0443: @item C-x 5 r @var{filename} @key{RET}
0444: @kindex C-x 5 r
0445: @findex find-file-read-only-other-frame
0446: Visit file @var{filename} read-only, and select its buffer in another
0447: frame.  This runs @code{find-file-read-only-other-frame}.
0448: @xref{Visiting}.
0449: @end table
0450: 
0451:   You can control the appearance and behavior of the newly-created
0452: frames by specifying @dfn{frame parameters}.  @xref{Frame Parameters}.
0453: 
0454: @node Frame Commands
0455: @section Frame Commands
0456: 
0457:   The following commands are used to delete and operate on frames:
0458: 
0459: @table @kbd
0460: @item C-x 5 0
0461: @kindex C-x 5 0
0462: @findex delete-frame
0463: Delete the selected frame (@code{delete-frame}).  This signals an
0464: error if there is only one frame.
0465: 
0466: @item C-z
0467: @kindex C-z @r{(X windows)}
0468: Minimize (or iconify) the selected Emacs frame
0469: (@code{suspend-frame}).  @xref{Exiting}.
0470: 
0471: @item C-x 5 o
0472: @kindex C-x 5 o
0473: @findex other-frame
0474: Select another frame, and raise it.  If you repeat this command, it
0475: cycles through all the frames on your terminal.
0476: 
0477: @item C-x 5 1
0478: @kindex C-x 5 1
0479: @findex delete-other-frames
0480: Delete all frames on the current terminal, except the selected one.
0481: 
0482: @item M-@key{F10}
0483: @kindex M-F10
0484: @findex toggle-frame-maximized
0485: Toggle the maximization state of the current frame.  When a frame is
0486: maximized, it fills the screen.
0487: 
0488: @item @key{F11}
0489: @kindex F11
0490: @findex toggle-frame-fullscreen
0491: Toggle full-screen mode for the current frame.  (The difference
0492: between full-screen and maximized is normally that the former
0493: hides window manager decorations, giving slightly more screen space to
0494: Emacs itself.)
0495: @end table
0496: 
0497: @vindex frame-resize-pixelwise
0498:   Note that with some window managers you may have to customize the
0499: variable @code{frame-resize-pixelwise} to a non-@code{nil} value in
0500: order to make a frame truly maximized or full-screen.  This
0501: variable, when set to a non-@code{nil} value, in general allows
0502: resizing frames at pixel resolution, rather than in integral multiples
0503: of lines and columns.
0504: 
0505:   The @kbd{C-x 5 0} (@code{delete-frame}) command deletes the selected
0506: frame.  However, it will refuse to delete the last frame in an Emacs
0507: session, to prevent you from losing the ability to interact with the
0508: Emacs session.  Note that when Emacs is run as a daemon (@pxref{Emacs
0509: Server}), there is always a virtual frame that remains after all
0510: the ordinary, interactive frames are deleted.  In this case, @kbd{C-x
0511: 5 0} can delete the last interactive frame; you can use
0512: @command{emacsclient} to reconnect to the Emacs session.
0513: 
0514:   The @kbd{C-x 5 1} (@code{delete-other-frames}) command deletes all
0515: other frames on the current terminal (this terminal refers to either a
0516: graphical display, or a text terminal; @pxref{Non-Window Terminals}).
0517: If the Emacs session has frames open on other graphical displays or
0518: text terminals, those are not deleted.
0519: 
0520: @vindex focus-follows-mouse
0521:   The @kbd{C-x 5 o} (@code{other-frame}) command selects the next
0522: frame on the current terminal.  If you are using Emacs on the X Window
0523: System with a window manager that selects (or @dfn{gives focus to})
0524: whatever frame the mouse cursor is over, you have to change the
0525: variable @code{focus-follows-mouse} to @code{t} in order for this
0526: command to work properly.  Then invoking @kbd{C-x 5 o} will also warp
0527: the mouse cursor to the chosen frame.
0528: 
0529: @node Fonts
0530: @section Fonts
0531: @cindex fonts
0532: 
0533:   By default, Emacs displays text on graphical displays using a
0534: 10-point monospace font.  There are several different ways to specify
0535: a different font:
0536: 
0537: @itemize
0538: @item
0539: Click on @samp{Set Default Font} in the @samp{Options} menu.  This
0540: makes the selected font the default on all existing graphical frames.
0541: To save this for future sessions, click on @samp{Save Options} in the
0542: @samp{Options} menu.
0543: 
0544: @item
0545: Add a line to your init file, modifying the variable
0546: @code{default-frame-alist} to specify the @code{font} parameter
0547: (@pxref{Frame Parameters}), like this:
0548: 
0549: @example
0550: (add-to-list 'default-frame-alist
0551:              '(font . "DejaVu Sans Mono-10"))
0552: @end example
0553: 
0554: @noindent
0555: This makes the font the default on all graphical frames created after
0556: restarting Emacs with that init file.
0557: 
0558: @cindex X defaults file
0559: @cindex X resources file
0560: @item
0561: Add an @samp{emacs.font} X resource setting to your X resource file,
0562: like this:
0563: 
0564: @example
0565: emacs.font: DejaVu Sans Mono-12
0566: @end example
0567: 
0568: @noindent
0569: You must restart X, or use the @command{xrdb} command, for the X
0570: resources file to take effect.  @xref{Resources}.  Do not quote
0571: font names in X resource files.
0572: 
0573: @item
0574: If you are running Emacs on the GNOME desktop, you can tell Emacs to
0575: use the default system font by setting the variable
0576: @code{font-use-system-font} to @code{t} (the default is @code{nil}).
0577: For this to work, Emacs must have been compiled with support for
0578: Gsettings (or the older Gconf).
0579: 
0580: @item
0581: Use the command line option @samp{-fn} (or @samp{--font}).  @xref{Font
0582: X}.
0583: @end itemize
0584: 
0585:   To check what font you're currently using, the @kbd{C-u C-x =}
0586: command can be helpful.  It describes the character at point, and
0587: names the font that it's rendered in.
0588: 
0589: @cindex fontconfig
0590:   On X, there are four different ways to express a font name.  The
0591: first is to use a @dfn{Fontconfig pattern}.  Fontconfig patterns have
0592: the following form:
0593: 
0594: @example
0595: @var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]...
0596: @end example
0597: 
0598: @noindent
0599: Within this format, any of the elements in brackets may be omitted.
0600: Here, @var{fontname} is the @dfn{family name} of the font, such as
0601: @samp{Monospace} or @samp{DejaVu Sans Mono}; @var{fontsize} is the
0602: @dfn{point size} of the font (one @dfn{printer's point} is about 1/72
0603: of an inch); and the @samp{@var{name}=@var{values}} entries specify
0604: settings such as the slant and weight of the font.  Each @var{values}
0605: may be a single value, or a list of values separated by commas.  In
0606: addition, some property values are valid with only one kind of
0607: property name, in which case the @samp{@var{name}=} part may be
0608: omitted.
0609: 
0610: Here is a list of common font properties:
0611: 
0612: @table @samp
0613: @item slant
0614: One of @samp{italic}, @samp{oblique}, or @samp{roman}.
0615: 
0616: @item weight
0617: One of @samp{light}, @samp{medium}, @samp{demibold}, @samp{bold} or
0618: @samp{black}.
0619: 
0620: @item style
0621: Some fonts define special styles which are a combination of slant and
0622: weight.  For instance, @samp{Dejavu Sans} defines the @samp{book}
0623: style, which overrides the slant and weight properties.
0624: 
0625: @item width
0626: One of @samp{condensed}, @samp{normal}, or @samp{expanded}.
0627: 
0628: @item spacing
0629: One of @samp{monospace}, @samp{proportional}, @samp{dual-width}, or
0630: @samp{charcell}.
0631: @end table
0632: 
0633: @noindent
0634: Here are some examples of Fontconfig patterns:
0635: 
0636: @example
0637: Monospace
0638: Monospace-12
0639: Monospace-12:bold
0640: DejaVu Sans Mono:bold:italic
0641: Monospace-12:weight=bold:slant=italic
0642: @end example
0643: 
0644: For a more detailed description of Fontconfig patterns, see the
0645: Fontconfig manual, which is distributed with Fontconfig and available
0646: online at @url{https://fontconfig.org/fontconfig-user.html}.
0647: 
0648: @cindex GTK font pattern
0649:   The second way to specify a font is to use a @dfn{GTK font pattern}.
0650: These have the syntax
0651: 
0652: @example
0653: @var{fontname} [@var{properties}] [@var{fontsize}]
0654: @end example
0655: 
0656: @noindent
0657: where @var{fontname} is the family name, @var{properties} is a list of
0658: property values separated by spaces, and @var{fontsize} is the point
0659: size.  The properties that you may specify for GTK font patterns are
0660: as follows:
0661: 
0662: @itemize
0663: @item
0664: Slant properties: @samp{Italic} or @samp{Oblique}.  If omitted, the
0665: default (roman) slant is implied.
0666: @item
0667: Weight properties: @samp{Bold}, @samp{Book}, @samp{Light},
0668: @samp{Medium}, @samp{Semi-bold}, or @samp{Ultra-light}.  If omitted,
0669: @samp{Medium} weight is implied.
0670: @item
0671: Width properties: @samp{Semi-Condensed} or @samp{Condensed}.  If
0672: omitted, a default width is used.
0673: @end itemize
0674: 
0675: @noindent
0676: Here are some examples of GTK font patterns:
0677: 
0678: @example
0679: Monospace 12
0680: Monospace Bold Italic 12
0681: @end example
0682: 
0683: @cindex XLFD
0684: @cindex X Logical Font Description
0685:   The third way to specify a font is to use an @dfn{XLFD} (@dfn{X
0686: Logical Font Description}).  This is the traditional method for
0687: specifying fonts under X@.  Each XLFD consists of fourteen words or
0688: numbers, separated by dashes, like this:
0689: 
0690: @example
0691: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
0692: @end example
0693: 
0694: @noindent
0695: A wildcard character (@samp{*}) in an XLFD matches any sequence of
0696: characters (including none), and @samp{?} matches any single
0697: character.  However, matching is implementation-dependent, and can be
0698: inaccurate when wildcards match dashes in a long name.  For reliable
0699: results, supply all 14 dashes and use wildcards only within a field.
0700: Case is insignificant in an XLFD@.  The syntax for an XLFD is as
0701: follows:
0702: 
0703: @example
0704: -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
0705: @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding}
0706: @end example
0707: 
0708: @noindent
0709: The entries have the following meanings:
0710: 
0711: @table @var
0712: @item maker
0713: The name of the font manufacturer.
0714: @item family
0715: The name of the font family (e.g., @samp{courier}).
0716: @item weight
0717: The font weight---normally either @samp{bold}, @samp{medium} or
0718: @samp{light}.  Some font names support other values.
0719: @item slant
0720: The font slant---normally @samp{r} (roman), @samp{i} (italic),
0721: @samp{o} (oblique), @samp{ri} (reverse italic), or @samp{ot} (other).
0722: Some font names support other values.
0723: @item widthtype
0724: The font width---normally @samp{normal}, @samp{condensed},
0725: @samp{semicondensed}, or @samp{extended}.  Some font names support
0726: other values.
0727: @item style
0728: An optional additional style name.  Usually it is empty---most XLFDs
0729: have two hyphens in a row at this point.  The style name can also
0730: specify a two-letter ISO-639 language name, like @samp{ja} or
0731: @samp{ko}; some fonts that support CJK scripts have that spelled out
0732: in the style name part.
0733: @item pixels
0734: The font height, in pixels.
0735: @item height
0736: The font height on the screen, measured in tenths of a printer's
0737: point.  This is the point size of the font, times ten.  For a given
0738: vertical resolution, @var{height} and @var{pixels} are proportional;
0739: therefore, it is common to specify just one of them and use @samp{*}
0740: for the other.
0741: @item horiz
0742: The horizontal resolution, in pixels per inch, of the screen for which
0743: the font is intended.
0744: @item vert
0745: The vertical resolution, in pixels per inch, of the screen for which
0746: the font is intended.  Normally the resolution of the fonts on your
0747: system is the right value for your screen; therefore, you normally
0748: specify @samp{*} for this and @var{horiz}.
0749: @item spacing
0750: This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c}
0751: (character cell).
0752: @item width
0753: The average character width, in pixels, multiplied by ten.
0754: @item registry
0755: @itemx encoding
0756: The X font character set that the font depicts.  (X font character
0757: sets are not the same as Emacs character sets, but they are similar.)
0758: You can use the @command{xfontsel} program to check which choices you
0759: have.  Normally you should use @samp{iso8859} for @var{registry} and
0760: @samp{1} for @var{encoding}.
0761: @end table
0762: 
0763:   The fourth and final method of specifying a font is to use a font
0764: nickname.  Certain fonts have shorter nicknames, which you can use
0765: instead of a normal font specification.  For instance, @samp{6x13} is
0766: equivalent to
0767: 
0768: @example
0769: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
0770: @end example
0771: 
0772: @cindex client-side fonts
0773: @cindex server-side fonts
0774:   On X, Emacs recognizes two types of fonts: @dfn{client-side} fonts,
0775: which are provided by the Xft and Fontconfig libraries, and
0776: @dfn{server-side} fonts, which are provided by the X server itself.
0777: Most client-side fonts support advanced font features such as
0778: antialiasing and subpixel hinting, while server-side fonts do not.
0779: Fontconfig and GTK patterns match only client-side fonts.
0780: 
0781: @cindex listing system fonts
0782:   You will probably want to use a fixed-width default font---that is,
0783: a font in which all characters have the same width.  For Xft and
0784: Fontconfig fonts, you can use the @command{fc-list} command to list
0785: the available fixed-width fonts, like this:
0786: 
0787: @example
0788: fc-list :spacing=mono
0789: fc-list :spacing=charcell
0790: @end example
0791: 
0792: @noindent
0793: For server-side X fonts, you can use the @command{xlsfonts} program to
0794: list the available fixed-width fonts, like this:
0795: 
0796: @example
0797: xlsfonts -fn '*x*' | grep -E '^[0-9]+x[0-9]+'
0798: xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
0799: xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
0800: @end example
0801: 
0802: @noindent
0803: Any font with @samp{m} or @samp{c} in the @var{spacing} field of the
0804: XLFD is a fixed-width font.  To see what a particular font looks like,
0805: use the @command{xfd} command.  For example:
0806: 
0807: @example
0808: xfd -fn 6x13
0809: @end example
0810: 
0811: @noindent
0812: displays the entire font @samp{6x13}.
0813: 
0814:   While running Emacs, you can also set the font of a specific kind of
0815: text (@pxref{Faces}), or a particular frame (@pxref{Frame
0816: Parameters}).
0817: 
0818: @node Speedbar
0819: @section Speedbar Frames
0820: @cindex speedbar
0821: 
0822: @cindex attached frame (of speedbar)
0823:   The @dfn{speedbar} is a special frame for conveniently navigating in
0824: or operating on another frame.  The speedbar, when it exists, is
0825: always associated with a specific frame, called its @dfn{attached
0826: frame}; all speedbar operations act on that frame.
0827: 
0828:   Type @kbd{M-x speedbar} to create the speedbar and associate it with
0829: the current frame.  To dismiss the speedbar, type @kbd{M-x speedbar}
0830: again, or select the speedbar and type @kbd{q}.  (You can also delete
0831: the speedbar frame like any other Emacs frame.)  If you wish to
0832: associate the speedbar with a different frame, dismiss it and call
0833: @kbd{M-x speedbar} from that frame.
0834: 
0835:   The speedbar can operate in various modes.  Its default mode is
0836: @dfn{File Display} mode, which shows the files in the current
0837: directory of the selected window of the attached frame, one file per
0838: line.  Clicking on a non-directory visits that file in the selected window
0839: of the attached frame, and clicking on a directory shows that
0840: directory in the speedbar (@pxref{Mouse References}).  Each line also
0841: has a box, @samp{[+]} or @samp{<+>}, that you can click on to
0842: @dfn{expand} the contents of that item.  Expanding a directory adds
0843: the contents of that directory to the speedbar display, underneath the
0844: directory's own line.  Expanding an ordinary file adds a list of the
0845: tags in that file to the speedbar display; you can click on a tag name
0846: to jump to that tag in the selected window of the attached frame.
0847: When a file or directory is expanded, the @samp{[+]} changes to
0848: @samp{[-]}; you can click on that box to @dfn{contract} the item,
0849: hiding its contents.
0850: 
0851:   You navigate through the speedbar using the keyboard, too.  Typing
0852: @key{RET} while point is on a line in the speedbar is equivalent to
0853: clicking the item on the current line, and @key{SPC} expands or
0854: contracts the item.  @kbd{U} displays the parent directory of the
0855: current directory.  To copy, delete, or rename the file on the current
0856: line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively.  To create a
0857: new directory, type @kbd{M}.
0858: 
0859:   Another general-purpose speedbar mode is @dfn{Buffer Display} mode;
0860: in this mode, the speedbar displays a list of Emacs buffers.  To
0861: switch to this mode, type @kbd{b} in the speedbar.  To return to File
0862: Display mode, type @kbd{f}.  You can also change the display mode by
0863: clicking @kbd{mouse-3} anywhere in the speedbar window (or
0864: @kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the
0865: pop-up menu.
0866: 
0867:   Some major modes, including Rmail mode, Info, and GUD, have
0868: specialized ways of putting useful items into the speedbar for you to
0869: select.  For example, in Rmail mode, the speedbar shows a list of Rmail
0870: files, and lets you move the current message to another Rmail file by
0871: clicking on its @samp{<M>} box.
0872: 
0873:   For more details on using and programming the speedbar, @xref{Top,
0874: Speedbar,,speedbar, Speedbar Manual}.
0875: 
0876: @node Multiple Displays
0877: @section Multiple Displays
0878: @cindex multiple displays
0879: 
0880:   A single Emacs can talk to more than one X display.  Initially, Emacs
0881: uses just one display---the one specified with the @env{DISPLAY}
0882: environment variable or with the @samp{--display} option (@pxref{Initial
0883: Options}).  To connect to another display, use the command
0884: @code{make-frame-on-display}:
0885: 
0886: @findex make-frame-on-display
0887: @table @kbd
0888: @item M-x make-frame-on-display @key{RET} @var{display} @key{RET}
0889: Create a new frame on display @var{display}.
0890: @end table
0891: 
0892:   A single X server can handle more than one screen.  When you open
0893: frames on two screens belonging to one server, Emacs knows they share a
0894: single keyboard, and it treats all the commands arriving from these
0895: screens as a single stream of input.
0896: 
0897:   When you open frames on different X servers, Emacs makes a separate
0898: input stream for each server.  Each server also has its own selected
0899: frame.  The commands you enter with a particular X server apply to
0900: that server's selected frame.
0901: 
0902:   On multi-monitor displays it is possible to use the command
0903: @code{make-frame-on-monitor}:
0904: 
0905: @findex make-frame-on-monitor
0906: @table @kbd
0907: @item M-x make-frame-on-monitor @key{RET} @var{monitor} @key{RET}
0908: Create a new frame on monitor @var{monitor} whose screen area is
0909: a part of the current display.
0910: @end table
0911: 
0912: @node Frame Parameters
0913: @section Frame Parameters
0914: @vindex default-frame-alist
0915: 
0916:   You can control the default appearance and behavior of all frames by
0917: specifying a default list of @dfn{frame parameters} in the variable
0918: @code{default-frame-alist}.  Its value should be a list of entries,
0919: each specifying a parameter name and a value for that parameter.
0920: These entries take effect whenever Emacs creates a new frame,
0921: including the initial frame.
0922: 
0923: @cindex frame size, specifying default
0924:   For example, you can add the following lines to your init file
0925: (@pxref{Init File}) to set the default frame width to 90 character
0926: columns, the default frame height to 40 character rows, and the
0927: default font to @samp{Monospace-10}:
0928: 
0929: @example
0930: (add-to-list 'default-frame-alist '(width  . 90))
0931: (add-to-list 'default-frame-alist '(height . 40))
0932: (add-to-list 'default-frame-alist '(font . "Monospace-10"))
0933: @end example
0934: 
0935:   For a list of frame parameters and their effects, see @ref{Frame
0936: Parameters,,, elisp, The Emacs Lisp Reference Manual}.
0937: 
0938: @vindex initial-frame-alist
0939:   You can also specify a list of frame parameters which apply to just
0940: the initial frame, by customizing the variable
0941: @code{initial-frame-alist}.
0942: 
0943:   If Emacs is compiled to use an X toolkit, frame parameters that
0944: specify colors and fonts don't affect menus and the menu bar, since
0945: those are drawn by the toolkit and not directly by Emacs.
0946: 
0947:   Frame appearance and behavior can also be customized through X
0948: resources (@pxref{X Resources}); these override the parameters of the
0949: initial frame specified in your init file.
0950: 
0951:   Note that if you are using the desktop library to save and restore
0952: your sessions, the frames to be restored are recorded in the desktop
0953: file, together with their parameters.  When these frames are restored,
0954: the recorded parameters take precedence over the frame parameters
0955: specified by @code{default-frame-alist} and @code{initial-frame-alist}
0956: in your init file.  @xref{Saving Emacs Sessions}, for how to avoid
0957: that.
0958: 
0959: @node Scroll Bars
0960: @section Scroll Bars
0961: @cindex Scroll Bar mode
0962: @cindex mode, Scroll Bar
0963: @cindex Vertical Scroll Bar
0964: 
0965:   On graphical displays, there is a @dfn{vertical scroll bar} on the
0966: side of each Emacs window.  Clicking @kbd{mouse-1} on the scroll bar's
0967: up and down buttons scrolls the window by one line at a time (but some
0968: toolkits allow you to customize the scroll bars to not have those
0969: buttons).  Clicking @kbd{mouse-1} above or below the scroll bar's
0970: inner box scrolls the window by nearly the entire height of the
0971: window, like @kbd{M-v} and @kbd{C-v} respectively (@pxref{Moving
0972: Point}).  (This, too, can behave differently with some toolkits.)
0973: Dragging the inner box scrolls continuously.
0974: 
0975:   If Emacs is compiled on the X Window System without X toolkit
0976: support, the scroll bar behaves differently.  Clicking @kbd{mouse-1}
0977: anywhere on the scroll bar scrolls forward like @kbd{C-v}, while
0978: @kbd{mouse-3} scrolls backward like @kbd{M-v}.  Clicking @kbd{mouse-2}
0979: in the scroll bar lets you drag the inner box up and down.
0980: 
0981: @findex scroll-bar-mode
0982: @findex toggle-scroll-bar
0983:   To toggle the use of vertical scroll bars, type @kbd{M-x
0984: scroll-bar-mode}.  This command applies to all frames, including frames
0985: yet to be created.  To toggle vertical scroll bars for just the selected
0986: frame, use the command @kbd{M-x toggle-scroll-bar}.
0987: 
0988: @vindex scroll-bar-mode
0989:   To control the use of vertical scroll bars at startup, customize the
0990: variable @code{scroll-bar-mode}.  Its value should be either
0991: @code{right} (put scroll bars on the right side of windows), @code{left}
0992: (put them on the left), or @code{nil} (disable vertical scroll bars).
0993: By default, Emacs puts scroll bars on the right if it was compiled with
0994: GTK+ support on the X Window System, and on MS-Windows or macOS; Emacs
0995: puts scroll bars on the left if compiled on the X Window System without
0996: GTK+ support (following the old convention for X applications).
0997: 
0998: @vindex scroll-bar-width
0999: @cindex width of the vertical scroll bar
1000:   You can also use the X resource @samp{verticalScrollBars} to enable
1001: or disable the scroll bars (@pxref{Resources}).  To control the scroll
1002: bar width, change the @code{scroll-bar-width} frame parameter
1003: (@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}).
1004: 
1005: @vindex scroll-bar-adjust-thumb-portion
1006: @cindex overscrolling
1007: If you're using Emacs on X (with GTK+ or Motif), you can customize the
1008: variable @code{scroll-bar-adjust-thumb-portion} to control
1009: @dfn{overscrolling} of the scroll bar, i.e., dragging the thumb down even
1010: when the end of the buffer is visible.  If its value is
1011: non-@code{nil}, the scroll bar can be dragged downwards even if the
1012: end of the buffer is shown; if @code{nil}, the thumb will be at the
1013: bottom when the end of the buffer is shown.  You cannot over-scroll
1014: when the entire buffer is visible.
1015: 
1016: @cindex @code{scroll-bar} face
1017:   The visual appearance of the scroll bars is controlled by the
1018: @code{scroll-bar} face.  (Some toolkits, such as GTK+ and MS-Windows,
1019: ignore this face; the scroll-bar appearance there can only be
1020: customized system-wide, for GTK+ @pxref{GTK resources}).
1021: 
1022: @cindex vertical border
1023:   On graphical frames, vertical scroll bars implicitly serve to separate
1024: side-by-side windows visually.  When vertical scroll bars are disabled,
1025: Emacs by default separates such windows with the help of a one-pixel
1026: wide @dfn{vertical border}.  That border occupies the first pixel column
1027: of the window on the right and may thus overdraw the leftmost pixels of
1028: any glyph displayed there.  If these pixels convey important
1029: information, you can make them visible by enabling window dividers, see
1030: @ref{Window Dividers}.  To replicate the look of vertical borders, set
1031: the @code{right-divider-width} parameter of frames to one and have the
1032: @code{window-divider} face inherit from that of @code{vertical-border},
1033: @ref{Window Dividers,, Window Dividers, elisp, The Emacs Lisp Reference
1034: Manual}.
1035: 
1036: @cindex Horizontal Scroll Bar
1037: @cindex Horizontal Scroll Bar mode
1038:   On graphical displays with toolkit support, Emacs may also supply a
1039: @dfn{horizontal scroll bar} on the bottom of each window.  Clicking
1040: @kbd{mouse-1} on that scroll bar's left and right buttons scrolls the
1041: window horizontally by one column at a time.  (Note that some toolkits
1042: allow customizations of the scroll bar that cause these buttons not to
1043: be shown.)  Clicking @kbd{mouse-1} on the left or right of the scroll
1044: bar's inner box scrolls the window by four columns.  Dragging the
1045: inner box scrolls the window continuously.
1046: 
1047:   Note that such horizontal scrolling can make the window's position of
1048: point disappear on the left or the right.  Typing a character to insert
1049: text or moving point with a keyboard command will usually bring it back
1050: into view.
1051: 
1052: @findex horizontal-scroll-bar-mode
1053:   To toggle the use of horizontal scroll bars, type @kbd{M-x
1054: horizontal-scroll-bar-mode}.  This command applies to all frames,
1055: including frames yet to be created.  To toggle horizontal scroll bars
1056: for just the selected frame, use the command @kbd{M-x
1057: toggle-horizontal-scroll-bar}.
1058: 
1059: @vindex horizontal-scroll-bar-mode
1060:   To control the use of horizontal scroll bars at startup, customize the
1061: variable @code{horizontal-scroll-bar-mode}.
1062: 
1063: @vindex scroll-bar-height
1064: @cindex height of the horizontal scroll bar
1065:   You can also use the X resource @samp{horizontalScrollBars} to enable
1066: or disable horizontal scroll bars (@pxref{Resources}).  To control the
1067: scroll bar height, change the @code{scroll-bar-height} frame parameter
1068: (@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}).
1069: 
1070: @node Window Dividers
1071: @section Window Dividers
1072: @cindex Window Divider mode
1073: @cindex mode, Window Divider
1074: 
1075:   On graphical displays, you can use @dfn{window dividers} in order to
1076: separate windows visually.  Window dividers are bars that can be dragged
1077: with the mouse, thus allowing you to easily resize adjacent windows.
1078: 
1079: @findex window-divider-mode
1080:   To toggle the display of window dividers, use the command @kbd{M-x
1081: window-divider-mode}.
1082: 
1083: @vindex window-divider-default-places
1084:   To customize where dividers should appear, use the option
1085: @code{window-divider-default-places}.  Its value should be either
1086: @code{bottom-only} (to show dividers only on the bottom of windows),
1087: @code{right-only} (to show dividers only on the right of windows), or
1088: @code{t} (to show them on the bottom and on the right).
1089: 
1090: @vindex window-divider-default-bottom-width
1091: @vindex window-divider-default-right-width
1092:   To adjust the width of window dividers displayed by this mode
1093: customize the options @code{window-divider-default-bottom-width} and
1094: @code{window-divider-default-right-width}.
1095: 
1096:   When vertical scroll bars are disabled, dividers can be also useful to
1097: make the first pixel column of a window visible, which would be otherwise
1098: covered by the vertical border used to separate side-by-side windows
1099: (@pxref{Scroll Bars}).
1100: 
1101: For more details about window dividers see @ref{Window Dividers,,
1102: Window Dividers, elisp, The Emacs Lisp Reference Manual}.
1103: 
1104: @node Drag and Drop
1105: @section Drag and Drop
1106: @cindex drag and drop
1107: 
1108:   In most graphical desktop environments, Emacs has basic support for
1109: @dfn{drag and drop} operations.  For instance, dropping text onto an
1110: Emacs frame inserts the text where it is dropped.  Dropping a file
1111: onto an Emacs frame visits that file.  As a special case, dropping the
1112: file on a Dired buffer moves or copies the file (according to the
1113: conventions of the application it came from) into the directory
1114: displayed in that buffer.
1115: 
1116: @vindex dnd-open-file-other-window
1117:   Dropping a file normally visits it in the window you drop it on.  If
1118: you prefer to visit the file in a new window in such cases, customize
1119: the variable @code{dnd-open-file-other-window}.
1120: 
1121:   The XDND and Motif drag and drop protocols, and the old KDE 1.x
1122: protocol, are currently supported.
1123: 
1124: @vindex mouse-drag-and-drop-region
1125:   Emacs can also optionally drag the region with the mouse into
1126: another portion of this or another buffer.  To enable that, customize
1127: the variable @code{mouse-drag-and-drop-region} to a non-@code{nil}
1128: value.  Normally, the text is moved, i.e. cut and pasted, when the
1129: destination is the same buffer as the origin; dropping the region on
1130: another buffer copies the text instead.  If the value of this variable
1131: names a modifier key, such as @samp{shift}, @samp{control} or
1132: @samp{alt}, then pressing that modifier key when dropping the text
1133: will copy it instead of cutting it, even if you drop on the same
1134: buffer as the one from which the text came.
1135: 
1136: @vindex mouse-drag-and-drop-region-cut-when-buffers-differ
1137: @vindex mouse-drag-and-drop-region-show-tooltip
1138: @vindex mouse-drag-and-drop-region-show-cursor
1139: In order to cut text even when source and destination buffers differ,
1140: set the option
1141: @code{mouse-drag-and-drop-region-cut-when-buffers-differ} to a
1142: non-@code{nil} value.  By default, on a graphic display the selected
1143: text is shown in a tooltip and point moves together with the mouse
1144: cursor during dragging.  To suppress such behavior, set the options
1145: @code{mouse-drag-and-drop-region-show-tooltip} and/or
1146: @code{mouse-drag-and-drop-region-show-cursor} to @code{nil}.
1147: 
1148: 
1149: @node Menu Bars
1150: @section Menu Bars
1151: @cindex Menu Bar mode
1152: @cindex mode, Menu Bar
1153: @findex menu-bar-mode
1154: @vindex menu-bar-mode
1155: 
1156:   You can toggle the use of menu bars with @kbd{M-x menu-bar-mode}.
1157: With no argument, this command toggles Menu Bar mode, a global minor
1158: mode.  With an argument, the command turns Menu Bar mode on if the
1159: argument is positive, off if the argument is not positive.  To control
1160: the use of menu bars at startup, customize the variable
1161: @code{menu-bar-mode}.
1162: 
1163: @kindex C-mouse-3 @r{(when menu bar is disabled)}
1164:   Expert users often turn off the menu bar, especially on text
1165: terminals, where this makes one additional line available for text.
1166: If the menu bar is off, you can still pop up a menu of its contents
1167: with @kbd{C-mouse-3} on a display which supports pop-up menus.
1168: @xref{Menu Mouse Clicks}.
1169: 
1170:   @xref{Menu Bar}, for information on how to invoke commands with the
1171: menu bar.  @xref{X Resources}, for how to customize the menu bar
1172: menus' visual appearance.
1173: 
1174: @node Tool Bars
1175: @section Tool Bars
1176: @cindex Tool Bar mode
1177: @cindex mode, Tool Bar
1178: @cindex icons, toolbar
1179: 
1180:   On graphical displays, Emacs puts a @dfn{tool bar} at the top of
1181: each frame, just below the menu bar.  This is a row of icons which you
1182: can click on with the mouse to invoke various commands.
1183: 
1184:   The global (default) tool bar contains general commands.  Some major
1185: modes define their own tool bars; whenever a buffer with such a major
1186: mode is current, the mode's tool bar replaces the global tool bar.
1187: 
1188: @findex tool-bar-mode
1189: @vindex tool-bar-mode
1190:   To toggle the use of tool bars, type @kbd{M-x tool-bar-mode}.  This
1191: command applies to all frames, including frames yet to be created.  To
1192: control the use of tool bars at startup, customize the variable
1193: @code{tool-bar-mode}.
1194: 
1195: @vindex tool-bar-style
1196: @cindex Tool Bar style
1197:   When Emacs is compiled with GTK+ support, each tool bar item can
1198: consist of an image, or a text label, or both.  By default, Emacs
1199: follows the Gnome desktop's tool bar style setting; if none is
1200: defined, it displays tool bar items as just images.  To impose a
1201: specific tool bar style, customize the variable @code{tool-bar-style}.
1202: 
1203: @cindex Tool Bar position
1204:   You can also control the placement of the tool bar for the GTK+ tool
1205: bar with the frame parameter @code{tool-bar-position}.  @xref{Frame
1206: Parameters,,, elisp, The Emacs Lisp Reference Manual}.
1207: 
1208:   NS builds consider the tool bar to be a window decoration, and
1209: therefore do not display it when a window is undecorated.  @xref{Frame
1210: Parameters,,, elisp, The Emacs Lisp Reference Manual}.  On macOS the
1211: tool bar is hidden when the frame is put into fullscreen, but can be
1212: displayed by moving the mouse pointer to the top of the screen.
1213: 
1214: @node Dialog Boxes
1215: @section Using Dialog Boxes
1216: @cindex dialog boxes
1217: 
1218: @vindex use-dialog-box
1219:   A dialog box is a special kind of menu for asking you a yes-or-no
1220: question or some other special question.  Many Emacs commands use a
1221: dialog box to ask a yes-or-no question, if you used the mouse to
1222: invoke the command that led to the question.
1223: 
1224:   To disable the use of dialog boxes, change the variable
1225: @code{use-dialog-box} to @code{nil}.  In that case, Emacs always
1226: performs yes-or-no prompts using the echo area and keyboard input.
1227: This variable also controls whether to use file selection windows (but
1228: those are not supported on all platforms).
1229: 
1230: @vindex use-file-dialog
1231: @cindex file selection dialog, how to disable
1232:   A file selection window is a special kind of dialog box for asking
1233: for file names.  You can customize the variable @code{use-file-dialog}
1234: to suppress the use of file selection windows, even if you still want
1235: other kinds of dialogs.  This variable has no effect if you have
1236: suppressed all dialog boxes with the variable @code{use-dialog-box}.
1237: 
1238: @vindex x-gtk-show-hidden-files
1239: @vindex x-gtk-file-dialog-help-text
1240: @cindex hidden files, in GTK+ file chooser
1241: @cindex help text, in GTK+ file chooser
1242:   When Emacs is compiled with GTK+ support, it uses the GTK+ file
1243: chooser dialog.  Emacs adds an additional toggle button to this
1244: dialog, which you can use to enable or disable the display of hidden
1245: files (files starting with a dot) in that dialog.  If you want this
1246: toggle to be activated by default, change the variable
1247: @code{x-gtk-show-hidden-files} to @code{t}.  In addition, Emacs adds
1248: help text to the GTK+ file chooser dialog; to disable this help text,
1249: change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}.
1250: 
1251: @node Tooltips
1252: @section Tooltips
1253: @cindex tooltips
1254: 
1255:   @dfn{Tooltips} are small special frames that display text
1256: information at the current mouse position.  They activate when there
1257: is a pause in mouse movement over some significant piece of text in a
1258: window, or the mode line, or some other part of the Emacs frame such
1259: as a tool bar button or menu item.
1260: 
1261: @findex tooltip-mode
1262:   You can toggle the use of tooltips with the command @kbd{M-x
1263: tooltip-mode}.  When Tooltip mode is disabled, the help text is
1264: displayed in the echo area instead.  To control the use of tooltips at
1265: startup, customize the variable @code{tooltip-mode}.
1266: 
1267: The following variables provide customization options for tooltip
1268: display:
1269: 
1270: @vtable @code
1271: @item tooltip-delay
1272: This variable specifies how long Emacs should wait before displaying
1273: the first tooltip.  The value is in seconds.
1274: 
1275: @item tooltip-short-delay
1276: This variable specifies how long Emacs should wait before displaying
1277: subsequent tooltips on different items, having already displayed the
1278: first tooltip.  The value is in seconds.
1279: 
1280: @item tooltip-hide-delay
1281: The number of seconds since displaying a tooltip to hide it, if the
1282: mouse doesn't move.
1283: 
1284: @item tooltip-x-offset
1285: @itemx tooltip-y-offset
1286: The X and Y offsets, in pixels, of the left top corner of the tooltip
1287: from the mouse pointer position.  Note that these are ignored if
1288: @code{tooltip-frame-parameters} was customized to include,
1289: respectively, the @code{left} and @code{top} parameters.  The values
1290: of the offsets should be chosen so that the tooltip doesn't cover the
1291: mouse pointer's hot spot, or it might interfere with clicking the
1292: mouse.
1293: 
1294: @item tooltip-frame-parameters
1295: The frame parameters used for displaying tooltips.  @xref{Frame
1296: Parameters,,, elisp, The Emacs Lisp Reference Manual}, and also
1297: @ref{Tooltips,,, elisp, The Emacs Lisp Reference Manual}.
1298: @end vtable
1299: 
1300: For additional customization options for displaying tooltips, use
1301: @kbd{M-x customize-group @key{RET} tooltip @key{RET}}.
1302: 
1303: @vindex x-gtk-use-system-tooltips
1304:   If Emacs is built with GTK+ support, it displays tooltips via GTK+,
1305: using the default appearance of GTK+ tooltips.  To disable this,
1306: change the variable @code{x-gtk-use-system-tooltips} to @code{nil}.
1307: If you do this, or if Emacs is built without GTK+ support, most
1308: attributes of the tooltip text are specified by the @code{tooltip}
1309: face, and by X resources (@pxref{X Resources}).
1310: 
1311:   @dfn{GUD tooltips} are special tooltips that show the values of
1312: variables when debugging a program with GUD@.  @xref{Debugger
1313: Operation}.
1314: 
1315: @node Mouse Avoidance
1316: @section Mouse Avoidance
1317: @cindex avoiding mouse in the way of your typing
1318: @cindex mouse avoidance
1319: 
1320:   On graphical terminals, the mouse pointer may obscure the text in
1321: the Emacs frame.  Emacs provides two methods to avoid this problem.
1322: 
1323:   Firstly, Emacs hides the mouse pointer each time you type a
1324: self-inserting character, if the pointer lies inside an Emacs frame;
1325: moving the mouse pointer makes it visible again.  To disable this
1326: feature, set the variable @code{make-pointer-invisible} to @code{nil}.
1327: @xref{Display Custom}.
1328: 
1329: @vindex mouse-avoidance-mode
1330:   Secondly, you can use Mouse Avoidance mode, a minor mode, to keep
1331: the mouse pointer away from point.  To use Mouse Avoidance mode,
1332: customize the variable @code{mouse-avoidance-mode}.  You can set this
1333: to various values to move the mouse in several ways:
1334: 
1335: @table @code
1336: @item banish
1337: Move the pointer to a corner of the frame on any key-press.  You can
1338: customize the variable @code{mouse-avoidance-banish-position} to
1339: specify where the pointer goes when it is banished.
1340: @item exile
1341: Banish the pointer only if the cursor gets too close, and allow it to
1342: return once the cursor is out of the way.
1343: @item jump
1344: If the cursor gets too close to the pointer, displace the pointer by a
1345: random distance and direction.
1346: @item animate
1347: As @code{jump}, but shows steps along the way for illusion of motion.
1348: @item cat-and-mouse
1349: The same as @code{animate}.
1350: @item proteus
1351: As @code{animate}, but changes the shape of the mouse pointer too.
1352: @end table
1353: 
1354: @findex mouse-avoidance-mode
1355: You can also use the command @kbd{M-x mouse-avoidance-mode} to enable
1356: the mode.  Whenever Mouse Avoidance mode moves the mouse, it also
1357: raises the frame.
1358: 
1359: @node Non-Window Terminals
1360: @section Non-Window Terminals
1361: @cindex text terminal
1362: 
1363:   On a text terminal, Emacs can display only one Emacs frame at a
1364: time.  However, you can still create multiple Emacs frames, and switch
1365: between them.  Switching frames on these terminals is much like
1366: switching between different window configurations.
1367: 
1368:   Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x
1369: 5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete
1370: the current frame.
1371: 
1372:   Each frame has a number to distinguish it.  If your terminal can
1373: display only one frame at a time, the selected frame's number @var{n}
1374: appears near the beginning of the mode line, in the form
1375: @samp{F@var{n}}.
1376: 
1377: @findex set-frame-name
1378: @findex select-frame-by-name
1379:   @samp{F@var{n}} is in fact the frame's initial name.  You can give
1380: frames more meaningful names if you wish, and you can select a frame
1381: by its name.  Use the command @kbd{M-x set-frame-name @key{RET}
1382: @var{name} @key{RET}} to specify a new name for the selected frame,
1383: and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}}
1384: to select a frame according to its name.  The name you specify appears
1385: in the mode line when the frame is selected.
1386: 
1387: @node Text-Only Mouse
1388: @section Using a Mouse in Text Terminals
1389: @cindex mouse support
1390: @cindex terminal emulators, mouse support
1391: 
1392: Some text terminals support mouse clicks in the terminal window.
1393: 
1394: @cindex xterm
1395:   In a terminal emulator which is compatible with @command{xterm}, you
1396: can use @kbd{M-x xterm-mouse-mode} to give Emacs control over simple
1397: uses of the mouse---basically, only non-modified single clicks are
1398: supported.  Newer versions of @command{xterm} also support
1399: mouse-tracking.  The normal @command{xterm} mouse functionality for
1400: such clicks is still available by holding down the @key{SHIFT} key
1401: when you press the mouse button.  Xterm Mouse mode is a global minor
1402: mode (@pxref{Minor Modes}).  Repeating the command turns the mode off
1403: again.
1404: 
1405: @findex gpm-mouse-mode
1406:   In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to
1407: enable mouse support.  You must have the gpm server installed and
1408: running on your system in order for this to work.  Note that when
1409: this mode is enabled, you cannot use the mouse to transfer text
1410: between Emacs and other programs which use GPM.  This is due to
1411: limitations in GPM and the Linux kernel.
1412: 
1413: @iftex
1414: @xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features},
1415: @end iftex
1416: @ifnottex
1417: @xref{MS-DOS Mouse},
1418: @end ifnottex
1419: for information about mouse support on MS-DOS.
1420: