1@c This is part of the Emacs manual. 2@c Copyright (C) 1985--1987, 1993--1995, 1997, 1999--2021 Free Software 3@c Foundation, Inc. 4@c See file emacs.texi for copying conditions. 5@node Frames 6@chapter Frames and Graphical Displays 7@cindex frames 8 9 When Emacs is started on a graphical display, e.g., on the X Window 10System, it occupies a graphical system-level display region. In this 11manual, we call this a @dfn{frame}, reserving the word ``window'' for 12the part of the frame used for displaying a buffer. A frame initially 13contains one window, but it can be subdivided into multiple windows 14(@pxref{Windows}). A frame normally also contains a menu bar, tool 15bar, and echo area. 16 17 You can also create additional frames (@pxref{Creating Frames}). 18All frames created in the same Emacs session have access to the same 19underlying buffers and other data. For instance, if a buffer is being 20shown in more than one frame, any changes made to it in one frame show 21up immediately in the other frames too. 22 23 Typing @kbd{C-x C-c} closes all the frames on the current display, 24and ends the Emacs session if it has no frames open on any other 25displays (@pxref{Exiting}). To close just the selected frame, type 26@kbd{C-x 5 0} (that is zero, not @kbd{o}). 27 28 This chapter describes Emacs features specific to graphical displays 29(particularly mouse commands), and features for managing multiple 30frames. On text terminals, many of these features are unavailable. 31However, it is still possible to create multiple frames on text 32terminals; such frames are displayed one at a time, filling the entire 33terminal screen (@pxref{Non-Window Terminals}). It is also possible 34to use the mouse on some text terminals (@pxref{Text-Only Mouse}, for 35doing so on GNU and Unix systems; and 36@iftex 37@pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}, 38@end iftex 39@ifnottex 40@pxref{MS-DOS Mouse}, 41@end ifnottex 42for doing so on MS-DOS). Menus are supported on all text terminals. 43 44@menu 45* Mouse Commands:: Moving, cutting, and pasting, with the mouse. 46* Word and Line Mouse:: Mouse commands for selecting whole words or lines. 47* Mouse References:: Using the mouse to select an item from a list. 48* Menu Mouse Clicks:: Mouse clicks that bring up menus. 49* Mode Line Mouse:: Mouse clicks on the mode line. 50* Creating Frames:: Creating additional Emacs frames with various contents. 51* Frame Commands:: Iconifying, deleting, and switching frames. 52* Fonts:: Changing the frame font. 53* Speedbar:: How to make and use a speedbar frame. 54* Multiple Displays:: How one Emacs instance can talk to several displays. 55* Frame Parameters:: Changing the colors and other modes of frames. 56* Scroll Bars:: How to enable and disable scroll bars; how to use them. 57* Window Dividers:: Window separators that can be dragged with the mouse. 58* Drag and Drop:: Using drag and drop to open files and insert text. 59* Menu Bars:: Enabling and disabling the menu bar. 60* Tool Bars:: Enabling and disabling the tool bar. 61* Tab Bars:: Enabling and disabling the tab bar. 62* Dialog Boxes:: Controlling use of dialog boxes. 63* Tooltips:: Displaying information at the current mouse position. 64* Mouse Avoidance:: Preventing the mouse pointer from obscuring text. 65* Non-Window Terminals:: Multiple frames on terminals that show only one. 66* Text-Only Mouse:: Using the mouse in text terminals. 67@end menu 68 69@node Mouse Commands 70@section Mouse Commands for Editing 71@cindex mouse buttons (what they do) 72@cindex mouse, selecting text using 73 74@kindex mouse-1 75@kindex mouse-2 76@kindex mouse-3 77@table @kbd 78@item mouse-1 79Move point to where you click (@code{mouse-set-point}). 80 81@item Drag-mouse-1 82Activate the region around the text selected by dragging, and put the 83text in the primary selection (@code{mouse-set-region}). 84 85@item mouse-2 86Move point to where you click, and insert the contents of the primary 87selection there (@code{mouse-yank-primary}). 88 89@item mouse-3 90If the region is active, move the nearer end of the region to the 91click position; otherwise, set mark at the current value of point and 92point at the click position. Save the resulting region in the kill 93ring; on a second click, kill it (@code{mouse-save-then-kill}). 94 95@item C-M-mouse-1 96Activate a rectangular region around the text selected by dragging. 97@xref{Rectangles}. 98@end table 99 100@findex mouse-set-point 101 The most basic mouse command is @code{mouse-set-point}, which is 102invoked by clicking with the left mouse button, @kbd{mouse-1}, in the 103text area of a window. This moves point to the position where you 104clicked. If that window was not the selected window, it becomes the 105selected window. You can also activate a region by double-clicking 106@kbd{mouse-1} (@pxref{Word and Line Mouse}). 107 108@vindex x-mouse-click-focus-ignore-position 109 Normally, if the frame you clicked in was not the selected frame, it 110is made the selected frame, in addition to selecting the window and 111setting the cursor. On the X Window System, you can change this by 112setting the variable @code{x-mouse-click-focus-ignore-position} to 113@code{t}. In that case, the initial click on an unselected frame just 114selects the frame, without doing anything else; clicking again selects 115the window and sets the cursor position. 116 117@cindex mouse, dragging 118@findex mouse-set-region 119 Holding down @kbd{mouse-1} and dragging the mouse over a stretch 120of text activates the region around that text 121(@code{mouse-set-region}), placing the mark where you started holding 122down the mouse button, and point where you release it (@pxref{Mark}). 123In addition, the text in the region becomes the primary selection 124(@pxref{Primary Selection}). 125 126@vindex mouse-drag-copy-region 127 If you change the variable @code{mouse-drag-copy-region} to a 128non-@code{nil} value, dragging the mouse over a stretch of text also 129adds the text to the kill ring. The default is @code{nil}. 130 131@vindex mouse-scroll-min-lines 132 If you move the mouse off the top or bottom of the window while 133dragging, the window scrolls at a steady rate until you move the mouse 134back into the window. This way, you can select regions that don't fit 135entirely on the screen. The number of lines scrolled per step depends 136on how far away from the window edge the mouse has gone; the variable 137@code{mouse-scroll-min-lines} specifies a minimum step size. 138 139@findex mouse-yank-primary 140@findex mouse-yank-at-click 141 Clicking with the middle mouse button, @kbd{mouse-2}, moves point to 142the position where you clicked and inserts the contents of the primary 143selection (@code{mouse-yank-primary}). @xref{Primary Selection}. 144This behavior is consistent with other X applications. Alternatively, 145you can rebind @kbd{mouse-2} to @code{mouse-yank-at-click}, which 146performs a yank at the position you click. 147 148@vindex mouse-yank-at-point 149 If you change the variable @code{mouse-yank-at-point} to a 150non-@code{nil} value, @kbd{mouse-2} does not move point; it inserts 151the text at point, regardless of where you clicked or even which of 152the frame's windows you clicked on. This variable affects both 153@code{mouse-yank-primary} and @code{mouse-yank-at-click}. 154 155@findex mouse-save-then-kill 156 Clicking with the right mouse button, @kbd{mouse-3}, runs the 157command @code{mouse-save-then-kill}. This performs several actions 158depending on where you click and the status of the region: 159 160@itemize @bullet 161@item 162If no region is active, clicking @kbd{mouse-3} activates the region, 163placing the mark where point was and point at the clicked position. 164 165@item 166If a region is active, clicking @kbd{mouse-3} adjusts the nearer end 167of the region by moving it to the clicked position. The adjusted 168region's text is copied to the kill ring; if the text in the original 169region was already on the kill ring, it replaces it there. 170 171@item 172If you originally specified the region using a double or triple 173@kbd{mouse-1}, so that the region is defined to consist of entire 174words or lines (@pxref{Word and Line Mouse}), then adjusting the 175region with @kbd{mouse-3} also proceeds by entire words or lines. 176 177@item 178If you use @kbd{mouse-3} a second time consecutively, at the same 179place, that kills the region already selected. Thus, the simplest way 180to kill text with the mouse is to click @kbd{mouse-1} at one end, then 181click @kbd{mouse-3} twice at the other end. To copy the text into the 182kill ring without deleting it from the buffer, press @kbd{mouse-3} 183just once---or just drag across the text with @kbd{mouse-1}. Then you 184can copy it elsewhere by yanking it. 185@end itemize 186 187 The @code{mouse-save-then-kill} command also obeys the variable 188@code{mouse-drag-copy-region} (described above). If the value is 189non-@code{nil}, then whenever the command sets or adjusts the active 190region, the text in the region is also added to the kill ring. If the 191latest kill ring entry had been added the same way, that entry is 192replaced rather than making a new entry. 193 194 Whenever you set the region using any of the mouse commands 195described above, the mark will be deactivated by any subsequent 196unshifted cursor motion command, in addition to the usual ways of 197deactivating the mark. @xref{Shift Selection}. 198 199@cindex mouse wheel 200@findex mouse-wheel-mode 201@cindex Mouse Wheel minor mode 202@cindex mode, Mouse Wheel 203@vindex mouse-wheel-follow-mouse 204@vindex mouse-wheel-scroll-amount 205@vindex mouse-wheel-progressive-speed 206 Some mice have a ``wheel'' which can be used for scrolling. Emacs 207supports scrolling windows with the mouse wheel, by default, on most 208graphical displays. To toggle this feature, use @kbd{M-x 209mouse-wheel-mode}. The variables @code{mouse-wheel-follow-mouse} and 210@code{mouse-wheel-scroll-amount} determine where and by how much 211buffers are scrolled. The variable 212@code{mouse-wheel-progressive-speed} determines whether the scroll 213speed is linked to how fast you move the wheel. This mode also 214supports increasing or decreasing the height of the default face, by 215default bound to scrolling with the @key{Ctrl} modifier. 216 217@vindex mouse-wheel-tilt-scroll 218@vindex mouse-wheel-flip-direction 219Emacs can also support horizontal scrolling if your mouse's wheel can 220be tilted, or if your touchpad supports it. This feature is off by 221default; the variable @code{mouse-wheel-tilt-scroll} turns it on, if 222you customize it to a non-@code{nil} value. By default, tilting the 223mouse wheel scrolls the window's view horizontally in the direction of 224the tilt: e.g., tilting to the right scrolls the window to the right, 225so that the text displayed in the window moves horizontally to the 226left. If you'd like to reverse the direction of horizontal scrolling, 227customize the variable @code{mouse-wheel-flip-direction} to a 228non-@code{nil} value. 229 230When the mouse pointer is over an image in Image mode, @pxref{Image Mode}, 231scrolling the mouse wheel with the @key{Ctrl} modifier scales the image 232under the mouse pointer. 233 234 235@node Word and Line Mouse 236@section Mouse Commands for Words and Lines 237 238 These variants of @kbd{mouse-1} select entire words or lines at a 239time. Emacs activates the region around the selected text, which is 240also copied to the kill ring. 241 242@table @kbd 243@item Double-mouse-1 244Select the text around the word or character which you click on. 245 246Double-clicking on a character with symbol syntax (such as 247underscore, in C mode) selects the symbol surrounding that character. 248Double-clicking on a character with open- or close-parenthesis syntax 249selects the parenthetical grouping which that character starts or 250ends. Double-clicking on a character with string-delimiter syntax 251(such as a single-quote or double-quote in C) selects the string 252constant (Emacs uses heuristics to figure out whether that character 253is the beginning or the end of it). 254 255Double-clicking on the beginning of a parenthetical grouping or 256beginning string-delimiter moves point to the end of the region, 257scrolling the buffer display forward if necessary to show the new 258location of point. Double-clicking on the end of a parenthetical 259grouping or end string-delimiter keeps point at the end of the region 260by default, so the beginning of the region will not be visible if it 261is above the top of the window; setting the user option 262@code{mouse-select-region-move-to-beginning} to non-@code{nil} changes 263this to move point to the beginning of the region, scrolling the 264display backward if necessary. 265 266@item Double-Drag-mouse-1 267Select the text you drag across, in units of whole words. 268 269@item Triple-mouse-1 270Select the line you click on. 271 272@item Triple-Drag-mouse-1 273Select the text you drag across, in units of whole lines. 274@end table 275 276@node Mouse References 277@section Following References with the Mouse 278@kindex mouse-1 @r{(on buttons)} 279@kindex mouse-2 @r{(on buttons)} 280@cindex hyperlinks 281@cindex links 282@cindex text buttons 283@cindex buttons 284 285@vindex mouse-highlight 286 Some Emacs buffers include @dfn{buttons}, or @dfn{hyperlinks}: 287pieces of text that perform some action (e.g., following a reference) 288when activated (e.g., by clicking on them). Usually, a button's text 289is visually highlighted: it is underlined, or a box is drawn around 290it. If you move the mouse over a button, the shape of the mouse 291cursor changes and the button lights up. If you change the variable 292@code{mouse-highlight} to @code{nil}, Emacs disables this 293highlighting. 294 295 You can activate a button by moving point to it and typing 296@key{RET}, or by clicking either @kbd{mouse-1} or @kbd{mouse-2} on the 297button. For example, in a Dired buffer, each file name is a button; 298activating it causes Emacs to visit that file (@pxref{Dired}). In a 299@file{*Compilation*} buffer, each error message is a button, and 300activating it visits the source code for that error 301(@pxref{Compilation}). 302 303 Although clicking @kbd{mouse-1} on a button usually activates the 304button, if you hold the mouse button down for a period of time before 305releasing it (specifically, for more than 450 milliseconds), then 306Emacs moves point where you clicked, without activating the button. 307In this way, you can use the mouse to move point over a button without 308activating it. Dragging the mouse over or onto a button has its usual 309behavior of setting the region, and does not activate the button. 310 311 You can change how @kbd{mouse-1} applies to buttons by customizing 312the variable @code{mouse-1-click-follows-link}. If the value is a 313positive integer, that determines how long you need to hold the mouse 314button down for, in milliseconds, to cancel button activation; the 315default is 450, as described in the previous paragraph. If the value 316is @code{nil}, @kbd{mouse-1} just sets point where you clicked, and 317does not activate buttons. If the value is @code{double}, double 318clicks activate buttons but single clicks just set point. 319 320@vindex mouse-1-click-in-non-selected-windows 321 Normally, @kbd{mouse-1} on a button activates the button even if it 322is in a non-selected window. If you change the variable 323@code{mouse-1-click-in-non-selected-windows} to @code{nil}, 324@kbd{mouse-1} on a button in an unselected window moves point to the 325clicked position and selects that window, without activating the 326button. 327 328@node Menu Mouse Clicks 329@section Mouse Clicks for Menus 330 331 Several mouse clicks with the @key{Ctrl} and @key{SHIFT} modifiers 332bring up menus. 333 334@table @kbd 335@item C-mouse-1 336@kindex C-mouse-1 337This menu is for selecting a buffer. 338 339The MSB (``mouse select buffer'') global minor mode makes this 340menu smarter and more customizable. @xref{Buffer Menus}. 341 342@item C-mouse-2 343@kindex C-mouse-2 344This menu contains entries for examining faces and other text 345properties, and well as for setting them (the latter is mainly useful 346when editing enriched text; @pxref{Enriched Text}). 347 348@item C-mouse-3 349@kindex C-mouse-3 350This menu is mode-specific. For most modes if Menu-bar mode is on, 351this menu has the same items as all the mode-specific menu-bar menus 352put together. Some modes may specify a different menu for this 353button. If Menu Bar mode is off, this menu contains all the items 354which would be present in the menu bar---not just the mode-specific 355ones---so that you can access them without having to display the menu 356bar. 357 358@item S-mouse-1 359This menu is for changing the default face within the window's buffer. 360@xref{Text Scale}. 361@end table 362 363 Some graphical applications use @kbd{mouse-3} for a mode-specific 364menu. If you prefer @kbd{mouse-3} in Emacs to bring up such a menu 365instead of running the @code{mouse-save-then-kill} command, rebind 366@kbd{mouse-3} by adding the following line to your init file 367(@pxref{Init Rebinding}): 368 369@c FIXME: `mouse-popup-menubar-stuff' is obsolete since 23.1. 370@smallexample 371(global-set-key [mouse-3] 'mouse-popup-menubar-stuff) 372@end smallexample 373 374@node Mode Line Mouse 375@section Mode Line Mouse Commands 376@cindex mode line, mouse 377@cindex mouse on mode line 378 379 You can use mouse clicks on window mode lines to select and manipulate 380windows. 381 382 Some areas of the mode line, such as the buffer name, and major and minor 383mode names, have their own special mouse bindings. These areas are 384highlighted when you hold the mouse over them, and information about 385the special bindings will be displayed (@pxref{Tooltips}). This 386section's commands do not apply in those areas. 387 388@table @kbd 389@item mouse-1 390@kindex mouse-1 @r{(mode line)} 391@kbd{mouse-1} on a mode line selects the window it belongs to. By 392dragging @kbd{mouse-1} on the mode line, you can move it, thus 393changing the height of the windows above and below. Changing heights 394with the mouse in this way never deletes windows, it just refuses to 395make any window smaller than the minimum height. 396 397@item mouse-2 398@kindex mouse-2 @r{(mode line)} 399@kbd{mouse-2} on a mode line expands that window to fill its frame. 400 401@item mouse-3 402@kindex mouse-3 @r{(mode line)} 403@kbd{mouse-3} on a mode line deletes the window it belongs to. If the 404frame has only one window, it does nothing. 405 406@item C-mouse-2 407@kbd{C-mouse-2} on a mode line splits that window, producing two 408side-by-side windows with the boundary running through the click 409position (@pxref{Split Window}). 410@end table 411 412@kindex mouse-1 @r{(scroll bar)} 413 Furthermore, by clicking and dragging @kbd{mouse-1} on the divider 414between two side-by-side mode lines, you can move the vertical 415boundary to the left or right. 416 417 Note that resizing windows is affected by the value of 418@code{window-resize-pixelwise}, see @ref{Split Window}. 419 420@node Creating Frames 421@section Creating Frames 422@cindex creating frames 423 424@kindex C-x 5 425 The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}. Whereas 426each @kbd{C-x 4} command pops up a buffer in a different window in the 427selected frame (@pxref{Pop Up Window}), the @kbd{C-x 5} commands use a 428different frame. If an existing visible or iconified (a.k.a.@: 429``minimized'', @pxref{Visibility of Frames,,, elisp, The Emacs Lisp 430Reference Manual}) frame already displays the requested buffer, that 431frame is raised and deiconified (``un-minimized''); otherwise, a new 432frame is created on the current display terminal. 433 434 The various @kbd{C-x 5} commands differ in how they find or create the 435buffer to select: 436 437@table @kbd 438@item C-x 5 2 439@kindex C-x 5 2 440@findex make-frame-command 441Create a new frame (@code{make-frame-command}). 442@item C-x 5 b @var{bufname} @key{RET} 443Select buffer @var{bufname} in another frame. This runs 444@code{switch-to-buffer-other-frame}. 445@item C-x 5 f @var{filename} @key{RET} 446Visit file @var{filename} and select its buffer in another frame. This 447runs @code{find-file-other-frame}. @xref{Visiting}. 448@item C-x 5 d @var{directory} @key{RET} 449Select a Dired buffer for directory @var{directory} in another frame. 450This runs @code{dired-other-frame}. @xref{Dired}. 451@item C-x 5 m 452Start composing a mail message in another frame. This runs 453@code{compose-mail-other-frame}. It is the other-frame variant of 454@kbd{C-x m}. @xref{Sending Mail}. 455@item C-x 5 . 456Find the definition of an identifier in another frame. This runs 457@code{xref-find-definitions-other-frame}, the multiple-frame variant 458of @kbd{M-.}. @xref{Xref}. 459@item C-x 5 r @var{filename} @key{RET} 460@kindex C-x 5 r 461@findex find-file-read-only-other-frame 462Visit file @var{filename} read-only, and select its buffer in another 463frame. This runs @code{find-file-read-only-other-frame}. 464@xref{Visiting}. 465@end table 466 467 You can control the appearance and behavior of the newly-created 468frames by specifying @dfn{frame parameters}. @xref{Frame Parameters}. 469 470@node Frame Commands 471@section Frame Commands 472 473 The following commands are used to delete and operate on frames: 474 475@table @kbd 476@item C-x 5 0 477@kindex C-x 5 0 478@findex delete-frame 479Delete the selected frame (@code{delete-frame}). This signals an 480error if there is only one frame. 481 482@item C-z 483@kindex C-z @r{(X windows)} 484Minimize (or iconify) the selected Emacs frame 485(@code{suspend-frame}). @xref{Exiting}. 486 487@item C-x 5 o 488@kindex C-x 5 o 489@findex other-frame 490Select another frame, and raise it. If you repeat this command, it 491cycles through all the frames on your terminal. 492 493@item C-x 5 1 494@kindex C-x 5 1 495@findex delete-other-frames 496Delete all frames on the current terminal, except the selected one. 497 498@item M-@key{F10} 499@kindex M-F10 500@findex toggle-frame-maximized 501Toggle the maximization state of the current frame. When a frame is 502maximized, it fills the screen. 503 504@item @key{F11} 505@kindex F11 506@findex toggle-frame-fullscreen 507Toggle full-screen mode for the current frame. (The difference 508between full-screen and maximized is normally that the former 509hides window manager decorations, giving slightly more screen space to 510Emacs itself.) 511@end table 512 513@vindex frame-resize-pixelwise 514 Note that with some window managers you may have to customize the 515variable @code{frame-resize-pixelwise} to a non-@code{nil} value in 516order to make a frame truly maximized or full-screen. This 517variable, when set to a non-@code{nil} value, in general allows 518resizing frames at pixel resolution, rather than in integral multiples 519of lines and columns. 520 521 The @kbd{C-x 5 0} (@code{delete-frame}) command deletes the selected 522frame. However, it will refuse to delete the last frame in an Emacs 523session, to prevent you from losing the ability to interact with the 524Emacs session. Note that when Emacs is run as a daemon (@pxref{Emacs 525Server}), there is always a virtual frame that remains after all 526the ordinary, interactive frames are deleted. In this case, @kbd{C-x 5275 0} can delete the last interactive frame; you can use 528@command{emacsclient} to reconnect to the Emacs session. 529 530 The @kbd{C-x 5 1} (@code{delete-other-frames}) command deletes all 531other frames on the current terminal (this terminal refers to either a 532graphical display, or a text terminal; @pxref{Non-Window Terminals}). 533If the Emacs session has frames open on other graphical displays or 534text terminals, those are not deleted. 535 536@vindex focus-follows-mouse 537 The @kbd{C-x 5 o} (@code{other-frame}) command selects the next 538frame on the current terminal. If you are using Emacs on the X Window 539System with a window manager that selects (or @dfn{gives focus to}) 540whatever frame the mouse cursor is over, you have to change the 541variable @code{focus-follows-mouse} to @code{t} in order for this 542command to work properly. Then invoking @kbd{C-x 5 o} will also warp 543the mouse cursor to the chosen frame. 544 545@node Fonts 546@section Fonts 547@cindex fonts 548 549 By default, Emacs displays text on graphical displays using a 55010-point monospace font, and the font size can be changed 551interactively (@pxref{Text Scale}). 552 553 There are several different ways to specify a different font: 554 555@itemize 556@item 557Click on @samp{Set Default Font} in the @samp{Options} menu. This 558makes the selected font the default on all existing graphical frames. 559To save this for future sessions, click on @samp{Save Options} in the 560@samp{Options} menu. 561 562@item 563Add a line to your init file, modifying the variable 564@code{default-frame-alist} to specify the @code{font} parameter 565(@pxref{Frame Parameters}), like this: 566 567@example 568(add-to-list 'default-frame-alist 569 '(font . "DejaVu Sans Mono-10")) 570@end example 571 572@noindent 573This makes the font the default on all graphical frames created after 574restarting Emacs with that init file. 575 576@cindex X defaults file 577@cindex X resources file 578@item 579Add an @samp{emacs.font} X resource setting to your X resource file, 580like this: 581 582@example 583emacs.font: DejaVu Sans Mono-12 584@end example 585 586@noindent 587You must restart X, or use the @command{xrdb} command, for the X 588resources file to take effect. @xref{Resources}. Do not quote 589font names in X resource files. 590 591@item 592If you are running Emacs on the GNOME desktop, you can tell Emacs to 593use the default system font by setting the variable 594@code{font-use-system-font} to @code{t} (the default is @code{nil}). 595For this to work, Emacs must have been compiled with support for 596Gsettings (or the older Gconf). 597 598@item 599Use the command line option @samp{-fn} (or @samp{--font}). @xref{Font 600X}. 601@end itemize 602 603 To check what font you're currently using, the @kbd{C-u C-x =} 604command can be helpful. It describes the character at point, and 605names the font that it's rendered in. 606 607@cindex fontconfig 608 There are four different ways to express a font name. The first is 609to use a @dfn{Fontconfig pattern}. Fontconfig patterns have the 610following form: 611 612@example 613@var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]... 614@end example 615 616@noindent 617Within this format, any of the elements in brackets may be omitted. 618Here, @var{fontname} is the @dfn{family name} of the font, such as 619@samp{Monospace} or @samp{DejaVu Sans Mono}; @var{fontsize} is the 620@dfn{point size} of the font (one @dfn{printer's point} is about 1/72 621of an inch); and the @samp{@var{name}=@var{values}} entries specify 622settings such as the slant and weight of the font. Each @var{values} 623may be a single value, or a list of values separated by commas. In 624addition, some property values are valid with only one kind of 625property name, in which case the @samp{@var{name}=} part may be 626omitted. 627 628Here is a list of common font properties: 629 630@table @samp 631@item slant 632One of @samp{italic}, @samp{oblique}, or @samp{roman}. 633 634@item weight 635One of @samp{light}, @samp{medium}, @samp{demibold}, @samp{bold} or 636@samp{black}. 637 638@item style 639Some fonts define special styles which are a combination of slant and 640weight. For instance, @samp{Dejavu Sans} defines the @samp{book} 641style, which overrides the slant and weight properties. 642 643@item width 644One of @samp{condensed}, @samp{normal}, or @samp{expanded}. 645 646@item spacing 647One of @samp{monospace}, @samp{proportional}, @samp{dual-width}, or 648@samp{charcell}. 649@end table 650 651@noindent 652Here are some examples of Fontconfig patterns: 653 654@example 655Monospace 656Monospace-12 657Monospace-12:bold 658DejaVu Sans Mono:bold:italic 659Monospace-12:weight=bold:slant=italic 660@end example 661 662For a more detailed description of Fontconfig patterns, see the 663Fontconfig manual, which is distributed with Fontconfig and available 664online at @url{https://fontconfig.org/fontconfig-user.html}. 665 666On MS-Windows, only the subset of the form 667@var{fontname}[-@var{fontsize}] is supported for all fonts; the full 668Fontconfig pattern might not work for all of them. 669 670@cindex GTK font pattern 671 The second way to specify a font is to use a @dfn{GTK font pattern}. 672These have the syntax 673 674@example 675@var{fontname} [@var{properties}] [@var{fontsize}] 676@end example 677 678@noindent 679where @var{fontname} is the family name, @var{properties} is a list of 680property values separated by spaces, and @var{fontsize} is the point 681size. The properties that you may specify for GTK font patterns are 682as follows: 683 684@itemize 685@item 686Slant properties: @samp{Italic} or @samp{Oblique}. If omitted, the 687default (roman) slant is implied. 688@item 689Weight properties: @samp{Bold}, @samp{Book}, @samp{Light}, 690@samp{Medium}, @samp{Semi-bold}, or @samp{Ultra-light}. If omitted, 691@samp{Medium} weight is implied. 692@item 693Width properties: @samp{Semi-Condensed} or @samp{Condensed}. If 694omitted, a default width is used. 695@end itemize 696 697@noindent 698Here are some examples of GTK font patterns: 699 700@example 701Monospace 12 702Monospace Bold Italic 12 703@end example 704 705On MS-Windows, only the subset @var{fontname} is supported. 706 707@cindex XLFD 708@cindex X Logical Font Description 709 The third way to specify a font is to use an @dfn{XLFD} (@dfn{X 710Logical Font Description}). This is the traditional method for 711specifying fonts under X, and is also supported on MS-Windows. Each 712XLFD consists of fourteen words or numbers, separated by dashes, like 713this: 714 715@example 716-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 717@end example 718 719@noindent 720A wildcard character (@samp{*}) in an XLFD matches any sequence of 721characters (including none), and @samp{?} matches any single 722character. However, matching is implementation-dependent, and can be 723inaccurate when wildcards match dashes in a long name. For reliable 724results, supply all 14 dashes and use wildcards only within a field. 725Case is insignificant in an XLFD@. The syntax for an XLFD is as 726follows: 727 728@example 729-@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} 730@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding} 731@end example 732 733@noindent 734The entries have the following meanings: 735 736@table @var 737@item maker 738The name of the font manufacturer. 739@item family 740The name of the font family (e.g., @samp{courier}). 741@item weight 742The font weight---normally either @samp{bold}, @samp{medium} or 743@samp{light}. Some font names support other values. 744@item slant 745The font slant---normally @samp{r} (roman), @samp{i} (italic), 746@samp{o} (oblique), @samp{ri} (reverse italic), or @samp{ot} (other). 747Some font names support other values. 748@item widthtype 749The font width---normally @samp{normal}, @samp{condensed}, 750@samp{semicondensed}, or @samp{extended}. Some font names support 751other values. 752@item style 753An optional additional style name. Usually it is empty---most XLFDs 754have two hyphens in a row at this point. The style name can also 755specify a two-letter ISO-639 language name, like @samp{ja} or 756@samp{ko}; some fonts that support CJK scripts have that spelled out 757in the style name part. 758@item pixels 759The font height, in pixels. 760@item height 761The font height on the screen, measured in tenths of a printer's 762point. This is the point size of the font, times ten. For a given 763vertical resolution, @var{height} and @var{pixels} are proportional; 764therefore, it is common to specify just one of them and use @samp{*} 765for the other. 766@item horiz 767The horizontal resolution, in pixels per inch, of the screen for which 768the font is intended. 769@item vert 770The vertical resolution, in pixels per inch, of the screen for which 771the font is intended. Normally the resolution of the fonts on your 772system is the right value for your screen; therefore, you normally 773specify @samp{*} for this and @var{horiz}. 774@item spacing 775This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} 776(character cell). 777@item width 778The average character width, in pixels, multiplied by ten. 779@item registry 780@itemx encoding 781The X font character set that the font depicts. (X font character 782sets are not the same as Emacs character sets, but they are similar.) 783You can use the @command{xfontsel} program to check which choices you 784have. Normally you should use @samp{iso8859} for @var{registry} and 785@samp{1} for @var{encoding}. 786@end table 787 788 The fourth and final method of specifying a font is to use a font 789nickname. Certain fonts have shorter nicknames, which you can use 790instead of a normal font specification. For instance, @samp{6x13} is 791equivalent to 792 793@example 794-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 795@end example 796 797This form is not supported on MS-Windows. 798 799@cindex client-side fonts 800@cindex server-side fonts 801 On X, Emacs recognizes two types of fonts: @dfn{client-side} fonts, 802which are provided by the Xft and Fontconfig libraries, and 803@dfn{server-side} fonts, which are provided by the X server itself. 804Most client-side fonts support advanced font features such as 805antialiasing and subpixel hinting, while server-side fonts do not. 806Fontconfig and GTK patterns match only client-side fonts. 807 808@cindex listing system fonts 809 You will probably want to use a fixed-width default font---that is, 810a font in which all characters have the same width. For Xft and 811Fontconfig fonts, you can use the @command{fc-list} command to list 812the available fixed-width fonts, like this: 813 814@example 815fc-list :spacing=mono 816fc-list :spacing=charcell 817@end example 818 819@noindent 820For server-side X fonts, you can use the @command{xlsfonts} program to 821list the available fixed-width fonts, like this: 822 823@example 824xlsfonts -fn '*x*' | grep -E '^[0-9]+x[0-9]+' 825xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' 826xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' 827@end example 828 829@noindent 830Any font with @samp{m} or @samp{c} in the @var{spacing} field of the 831XLFD is a fixed-width font. To see what a particular font looks like, 832use the @command{xfd} command. For example: 833 834@example 835xfd -fn 6x13 836@end example 837 838@noindent 839displays the entire font @samp{6x13}. 840 841 While running Emacs, you can also set the font of a specific kind of 842text (@pxref{Faces}), or a particular frame (@pxref{Frame 843Parameters}). 844 845@node Speedbar 846@section Speedbar Frames 847@cindex speedbar 848 849@cindex attached frame (of speedbar) 850 The @dfn{speedbar} is a special frame for conveniently navigating in 851or operating on another frame. The speedbar, when it exists, is 852always associated with a specific frame, called its @dfn{attached 853frame}; all speedbar operations act on that frame. 854 855 Type @kbd{M-x speedbar} to create the speedbar and associate it with 856the current frame. To dismiss the speedbar, type @kbd{M-x speedbar} 857again, or select the speedbar and type @kbd{q}. (You can also delete 858the speedbar frame like any other Emacs frame.) If you wish to 859associate the speedbar with a different frame, dismiss it and call 860@kbd{M-x speedbar} from that frame. 861 862 The speedbar can operate in various modes. Its default mode is 863@dfn{File Display} mode, which shows the files in the current 864directory of the selected window of the attached frame, one file per 865line. Clicking on a non-directory visits that file in the selected window 866of the attached frame, and clicking on a directory shows that 867directory in the speedbar (@pxref{Mouse References}). Each line also 868has a box, @samp{[+]} or @samp{<+>}, that you can click on to 869@dfn{expand} the contents of that item. Expanding a directory adds 870the contents of that directory to the speedbar display, underneath the 871directory's own line. Expanding an ordinary file adds a list of the 872tags in that file to the speedbar display; you can click on a tag name 873to jump to that tag in the selected window of the attached frame. 874When a file or directory is expanded, the @samp{[+]} changes to 875@samp{[-]}; you can click on that box to @dfn{contract} the item, 876hiding its contents. 877 878 You navigate through the speedbar using the keyboard, too. Typing 879@key{RET} while point is on a line in the speedbar is equivalent to 880clicking the item on the current line, and @key{SPC} expands or 881contracts the item. @kbd{U} displays the parent directory of the 882current directory. To copy, delete, or rename the file on the current 883line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a 884new directory, type @kbd{M}. 885 886 Another general-purpose speedbar mode is @dfn{Buffer Display} mode; 887in this mode, the speedbar displays a list of Emacs buffers. To 888switch to this mode, type @kbd{b} in the speedbar. To return to File 889Display mode, type @kbd{f}. You can also change the display mode by 890clicking @kbd{mouse-3} anywhere in the speedbar window (or 891@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the 892pop-up menu. 893 894 Some major modes, including Rmail mode, Info, and GUD, have 895specialized ways of putting useful items into the speedbar for you to 896select. For example, in Rmail mode, the speedbar shows a list of Rmail 897files, and lets you move the current message to another Rmail file by 898clicking on its @samp{<M>} box. 899 900 For more details on using and programming the speedbar, @xref{Top, 901Speedbar,,speedbar, Speedbar Manual}. 902 903@node Multiple Displays 904@section Multiple Displays 905@cindex multiple displays 906 907 A single Emacs can talk to more than one X display. Initially, Emacs 908uses just one display---the one specified with the @env{DISPLAY} 909environment variable or with the @samp{--display} option (@pxref{Initial 910Options}). To connect to another display, use the command 911@code{make-frame-on-display}: 912 913@findex make-frame-on-display 914@table @kbd 915@item M-x make-frame-on-display @key{RET} @var{display} @key{RET} 916Create a new frame on display @var{display}. 917@end table 918 919 A single X server can handle more than one screen. When you open 920frames on two screens belonging to one server, Emacs knows they share a 921single keyboard, and it treats all the commands arriving from these 922screens as a single stream of input. 923 924 When you open frames on different X servers, Emacs makes a separate 925input stream for each server. Each server also has its own selected 926frame. The commands you enter with a particular X server apply to 927that server's selected frame. 928 929 On multi-monitor displays it is possible to use the command 930@code{make-frame-on-monitor}: 931 932@findex make-frame-on-monitor 933@table @kbd 934@item M-x make-frame-on-monitor @key{RET} @var{monitor} @key{RET} 935Create a new frame on monitor @var{monitor} whose screen area is 936a part of the current display. 937@end table 938 939@node Frame Parameters 940@section Frame Parameters 941@vindex default-frame-alist 942 943 You can control the default appearance and behavior of all frames by 944specifying a default list of @dfn{frame parameters} in the variable 945@code{default-frame-alist}. Its value should be a list of entries, 946each specifying a parameter name and a value for that parameter. 947These entries take effect whenever Emacs creates a new frame, 948including the initial frame. 949 950@cindex frame size, specifying default 951 For example, you can add the following lines to your init file 952(@pxref{Init File}) to set the default frame width to 90 character 953columns, the default frame height to 40 character rows, and the 954default font to @samp{Monospace-10}: 955 956@example 957(add-to-list 'default-frame-alist '(width . 90)) 958(add-to-list 'default-frame-alist '(height . 40)) 959(add-to-list 'default-frame-alist '(font . "Monospace-10")) 960@end example 961 962 For a list of frame parameters and their effects, see @ref{Frame 963Parameters,,, elisp, The Emacs Lisp Reference Manual}. 964 965@vindex initial-frame-alist 966 You can also specify a list of frame parameters which apply to just 967the initial frame, by customizing the variable 968@code{initial-frame-alist}. 969 970 If Emacs is compiled to use an X toolkit, frame parameters that 971specify colors and fonts don't affect menus and the menu bar, since 972those are drawn by the toolkit and not directly by Emacs. 973 974 Frame appearance and behavior can also be customized through X 975resources (@pxref{X Resources}); these override the parameters of the 976initial frame specified in your init file. 977 978 Note that if you are using the desktop library to save and restore 979your sessions, the frames to be restored are recorded in the desktop 980file, together with their parameters. When these frames are restored, 981the recorded parameters take precedence over the frame parameters 982specified by @code{default-frame-alist} and @code{initial-frame-alist} 983in your init file. @xref{Saving Emacs Sessions}, for how to avoid 984that. 985 986@node Scroll Bars 987@section Scroll Bars 988@cindex Scroll Bar mode 989@cindex mode, Scroll Bar 990@cindex Vertical Scroll Bar 991 992 On graphical displays, there is a @dfn{vertical scroll bar} on the 993side of each Emacs window. Clicking @kbd{mouse-1} on the scroll bar's 994up and down buttons scrolls the window by one line at a time (but some 995toolkits allow you to customize the scroll bars to not have those 996buttons). Clicking @kbd{mouse-1} above or below the scroll bar's 997inner box scrolls the window by nearly the entire height of the 998window, like @kbd{M-v} and @kbd{C-v} respectively (@pxref{Moving 999Point}). (This, too, can behave differently with some toolkits.) 1000Dragging the inner box scrolls continuously. 1001 1002 If Emacs is compiled on the X Window System without X toolkit 1003support, the scroll bar behaves differently. Clicking @kbd{mouse-1} 1004anywhere on the scroll bar scrolls forward like @kbd{C-v}, while 1005@kbd{mouse-3} scrolls backward like @kbd{M-v}. Clicking @kbd{mouse-2} 1006in the scroll bar lets you drag the inner box up and down. 1007 1008@findex scroll-bar-mode 1009@findex toggle-scroll-bar 1010 To toggle the use of vertical scroll bars, type @kbd{M-x 1011scroll-bar-mode}. This command applies to all frames, including frames 1012yet to be created. To toggle vertical scroll bars for just the selected 1013frame, use the command @kbd{M-x toggle-scroll-bar}. 1014 1015@vindex scroll-bar-mode 1016 To control the use of vertical scroll bars at startup, customize the 1017variable @code{scroll-bar-mode} (@pxref{Customization}). Its value 1018should be either @code{right} (put scroll bars on the right side of 1019windows), @code{left} (put them on the left), or @code{nil} (disable 1020vertical scroll bars). By default, Emacs puts scroll bars on the 1021right if it was compiled with GTK+ support on the X Window System, and 1022on MS-Windows or macOS; Emacs puts scroll bars on the left if compiled 1023on the X Window System without GTK+ support (following the old 1024convention for X applications). 1025 1026@vindex scroll-bar-width 1027@cindex width of the vertical scroll bar 1028 You can also use the X resource @samp{verticalScrollBars} to enable 1029or disable the scroll bars (@pxref{Resources}). To control the scroll 1030bar width, change the @code{scroll-bar-width} frame parameter 1031(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). 1032 1033@vindex scroll-bar-adjust-thumb-portion 1034@cindex overscrolling 1035If you're using Emacs on X (with GTK+ or Motif), you can customize the 1036variable @code{scroll-bar-adjust-thumb-portion} to control 1037@dfn{overscrolling} of the scroll bar, i.e., dragging the thumb down even 1038when the end of the buffer is visible. If its value is 1039non-@code{nil}, the scroll bar can be dragged downwards even if the 1040end of the buffer is shown; if @code{nil}, the thumb will be at the 1041bottom when the end of the buffer is shown. You cannot over-scroll 1042when the entire buffer is visible. 1043 1044@cindex @code{scroll-bar} face 1045 The visual appearance of the scroll bars is controlled by the 1046@code{scroll-bar} face. (Some toolkits, such as GTK+ and MS-Windows, 1047ignore this face; the scroll-bar appearance there can only be 1048customized system-wide, for GTK+ @pxref{GTK resources}). 1049 1050@cindex vertical border 1051 On graphical frames, vertical scroll bars implicitly serve to separate 1052side-by-side windows visually. When vertical scroll bars are disabled, 1053Emacs by default separates such windows with the help of a one-pixel 1054wide @dfn{vertical border}. That border occupies the first pixel column 1055of the window on the right and may thus overdraw the leftmost pixels of 1056any glyph displayed there. If these pixels convey important 1057information, you can make them visible by enabling window dividers, see 1058@ref{Window Dividers}. To replicate the look of vertical borders, set 1059the @code{right-divider-width} parameter of frames to one and have the 1060@code{window-divider} face inherit from that of @code{vertical-border}, 1061@ref{Window Dividers,, Window Dividers, elisp, The Emacs Lisp Reference 1062Manual}. 1063 1064@cindex Horizontal Scroll Bar 1065@cindex Horizontal Scroll Bar mode 1066 On graphical displays with toolkit support, Emacs may also supply a 1067@dfn{horizontal scroll bar} on the bottom of each window. Clicking 1068@kbd{mouse-1} on that scroll bar's left and right buttons scrolls the 1069window horizontally by one column at a time. (Note that some toolkits 1070allow customizations of the scroll bar that cause these buttons not to 1071be shown.) Clicking @kbd{mouse-1} on the left or right of the scroll 1072bar's inner box scrolls the window by four columns. Dragging the 1073inner box scrolls the window continuously. 1074 1075 Note that such horizontal scrolling can make the window's position of 1076point disappear on the left or the right. Typing a character to insert 1077text or moving point with a keyboard command will usually bring it back 1078into view. 1079 1080@findex horizontal-scroll-bar-mode 1081 To toggle the use of horizontal scroll bars, type @kbd{M-x 1082horizontal-scroll-bar-mode}. This command applies to all frames, 1083including frames yet to be created. To toggle horizontal scroll bars 1084for just the selected frame, use the command @kbd{M-x 1085toggle-horizontal-scroll-bar}. 1086 1087@vindex horizontal-scroll-bar-mode 1088 To control the use of horizontal scroll bars at startup, customize the 1089variable @code{horizontal-scroll-bar-mode}. 1090 1091@vindex scroll-bar-height 1092@cindex height of the horizontal scroll bar 1093 You can also use the X resource @samp{horizontalScrollBars} to enable 1094or disable horizontal scroll bars (@pxref{Resources}). To control the 1095scroll bar height, change the @code{scroll-bar-height} frame parameter 1096(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). 1097 1098@node Window Dividers 1099@section Window Dividers 1100@cindex Window Divider mode 1101@cindex mode, Window Divider 1102 1103 On graphical displays, you can use @dfn{window dividers} in order to 1104separate windows visually. Window dividers are bars that can be dragged 1105with the mouse, thus allowing you to easily resize adjacent windows. 1106 1107@findex window-divider-mode 1108 To toggle the display of window dividers, use the command @kbd{M-x 1109window-divider-mode}. 1110 1111@vindex window-divider-default-places 1112 To customize where dividers should appear, use the option 1113@code{window-divider-default-places}. Its value should be either 1114@code{bottom-only} (to show dividers only on the bottom of windows), 1115@code{right-only} (to show dividers only on the right of windows), or 1116@code{t} (to show them on the bottom and on the right). 1117 1118@vindex window-divider-default-bottom-width 1119@vindex window-divider-default-right-width 1120 To adjust the width of window dividers displayed by this mode 1121customize the options @code{window-divider-default-bottom-width} and 1122@code{window-divider-default-right-width}. 1123 1124 When vertical scroll bars are disabled, dividers can be also useful to 1125make the first pixel column of a window visible, which would be otherwise 1126covered by the vertical border used to separate side-by-side windows 1127(@pxref{Scroll Bars}). 1128 1129For more details about window dividers see @ref{Window Dividers,, 1130Window Dividers, elisp, The Emacs Lisp Reference Manual}. 1131 1132@node Drag and Drop 1133@section Drag and Drop 1134@cindex drag and drop 1135 1136 In most graphical desktop environments, Emacs has basic support for 1137@dfn{drag and drop} operations. For instance, dropping text onto an 1138Emacs frame inserts the text where it is dropped. Dropping a file 1139onto an Emacs frame visits that file. As a special case, dropping the 1140file on a Dired buffer moves or copies the file (according to the 1141conventions of the application it came from) into the directory 1142displayed in that buffer. 1143 1144@vindex dnd-open-file-other-window 1145 Dropping a file normally visits it in the window you drop it on. If 1146you prefer to visit the file in a new window in such cases, customize 1147the variable @code{dnd-open-file-other-window}. 1148 1149 The XDND and Motif drag and drop protocols, and the old KDE 1.x 1150protocol, are currently supported. 1151 1152@vindex mouse-drag-and-drop-region 1153 Emacs can also optionally drag the region with the mouse into 1154another portion of this or another buffer. To enable that, customize 1155the variable @code{mouse-drag-and-drop-region} to a non-@code{nil} 1156value. Normally, the text is moved, i.e. cut and pasted, when the 1157destination is the same buffer as the origin; dropping the region on 1158another buffer copies the text instead. If the value of this variable 1159names a modifier key, such as @samp{shift}, @samp{control} or 1160@samp{alt}, then pressing that modifier key when dropping the text 1161will copy it instead of cutting it, even if you drop on the same 1162buffer as the one from which the text came. 1163 1164@vindex mouse-drag-and-drop-region-cut-when-buffers-differ 1165@vindex mouse-drag-and-drop-region-show-tooltip 1166@vindex mouse-drag-and-drop-region-show-cursor 1167In order to cut text even when source and destination buffers differ, 1168set the option 1169@code{mouse-drag-and-drop-region-cut-when-buffers-differ} to a 1170non-@code{nil} value. By default, on a graphic display the selected 1171text is shown in a tooltip and point moves together with the mouse 1172cursor during dragging. To suppress such behavior, set the options 1173@code{mouse-drag-and-drop-region-show-tooltip} and/or 1174@code{mouse-drag-and-drop-region-show-cursor} to @code{nil}. 1175 1176 1177@node Menu Bars 1178@section Menu Bars 1179@cindex menu bar mode 1180@cindex mode, Menu Bar 1181@findex menu-bar-mode 1182@vindex menu-bar-mode 1183 1184 You can toggle the use of menu bars with @kbd{M-x menu-bar-mode}. 1185With no argument, this command toggles Menu Bar mode, a global minor 1186mode. With an argument, the command turns Menu Bar mode on if the 1187argument is positive, off if the argument is not positive. To control 1188the use of menu bars at startup, customize the variable 1189@code{menu-bar-mode}. 1190 1191@kindex C-mouse-3 @r{(when menu bar is disabled)} 1192 Expert users often turn off the menu bar, especially on text 1193terminals, where this makes one additional line available for text. 1194If the menu bar is off, you can still pop up a menu of its contents 1195with @kbd{C-mouse-3} on a display which supports pop-up menus. 1196@xref{Menu Mouse Clicks}. 1197 1198 @xref{Menu Bar}, for information on how to invoke commands with the 1199menu bar. @xref{X Resources}, for how to customize the menu bar 1200menus' visual appearance. 1201 1202@node Tool Bars 1203@section Tool Bars 1204@cindex tool bar mode 1205@cindex mode, Tool Bar 1206@cindex icons, toolbar 1207 1208 On graphical displays, Emacs puts a @dfn{tool bar} at the top of 1209each frame, just below the menu bar. This is a row of icons which you 1210can click on with the mouse to invoke various commands. 1211 1212 The global (default) tool bar contains general commands. Some major 1213modes define their own tool bars; whenever a buffer with such a major 1214mode is current, the mode's tool bar replaces the global tool bar. 1215 1216@findex tool-bar-mode 1217@vindex tool-bar-mode 1218 To toggle the use of tool bars, type @kbd{M-x tool-bar-mode}. This 1219command applies to all frames, including frames yet to be created. To 1220control the use of tool bars at startup, customize the variable 1221@code{tool-bar-mode}. 1222 1223@vindex tool-bar-style 1224@cindex Tool Bar style 1225 When Emacs is compiled with GTK+ support, each tool bar item can 1226consist of an image, or a text label, or both. By default, Emacs 1227follows the Gnome desktop's tool bar style setting; if none is 1228defined, it displays tool bar items as just images. To impose a 1229specific tool bar style, customize the variable @code{tool-bar-style}. 1230 1231@cindex Tool Bar position 1232 You can also control the placement of the tool bar for the GTK+ tool 1233bar with the frame parameter @code{tool-bar-position}. @xref{Frame 1234Parameters,,, elisp, The Emacs Lisp Reference Manual}. 1235 1236 NS builds consider the tool bar to be a window decoration, and 1237therefore do not display it when a window is undecorated. @xref{Frame 1238Parameters,,, elisp, The Emacs Lisp Reference Manual}. On macOS the 1239tool bar is hidden when the frame is put into fullscreen, but can be 1240displayed by moving the mouse pointer to the top of the screen. 1241 1242@node Tab Bars 1243@section Tab Bars 1244@cindex tab bar mode 1245@cindex mode, Tab Bar 1246@cindex tabs, tabbar 1247 1248 On graphical displays and on text terminals, Emacs can optionally 1249display a @dfn{Tab Bar} at the top of each frame, just below the menu 1250bar. The Tab Bar is a row of @dfn{tabs}---buttons that you can click 1251to switch between window configurations on that frame. 1252 1253 Each tab on the Tab Bar represents a named persistent window 1254configuration. Its name is composed from the list of names of buffers 1255visible in windows of that window configuration. Clicking on the tab 1256switches to the window configuration recorded by the tab; it is a 1257configuration of windows and buffers which was previously used in the 1258frame when that tab was the current tab. 1259 1260 If you are using the desktop library to save and restore your 1261sessions (@pxref{Saving Emacs Sessions}), the tabs from the Tab Bar are 1262recorded in the desktop file, together with their associated window 1263configurations, and will be available after restoring the session. 1264 1265Note that the Tab Bar is different from the Tab Line (@pxref{Tab Line}). 1266Whereas tabs on the Tab Line at the top of each window are used to 1267switch between buffers, tabs on the Tab Bar at the top of each frame 1268are used to switch between window configurations containing several 1269windows with buffers. 1270 1271@findex tab-bar-mode 1272 To toggle the use of tab bars, type @kbd{M-x tab-bar-mode}. This 1273command applies to all frames, including frames yet to be created. To 1274control the use of tab bars at startup, customize the variable 1275@code{tab-bar-mode}. 1276 1277@vindex tab-bar-show 1278 The variable @code{tab-bar-show} controls whether the Tab Bar mode 1279is turned on automatically. If the value is @code{t}, then 1280@code{tab-bar-mode} is enabled when using the commands that create new 1281tabs. The value @code{1} hides the tab bar when it has only one tab, 1282and shows it again when more tabs are created. The value @code{nil} 1283always keeps the tab bar hidden; in this case it's still possible to 1284switch between named window configurations without the tab bar by 1285using @kbd{M-x tab-next}, @kbd{M-x tab-switcher}, and other commands 1286that provide completion on tab names. Also it's possible to create 1287and close tabs without the tab bar by using commands @kbd{M-x 1288tab-new}, @kbd{M-x tab-close}, etc. 1289 1290@kindex C-x t 1291 The prefix key @kbd{C-x t} is analogous to @kbd{C-x 5}. 1292Whereas each @kbd{C-x 5} command pops up a buffer in a different frame 1293(@pxref{Creating Frames}), the @kbd{C-x t} commands use a different 1294tab with a different window configuration in the selected frame. 1295 1296 The various @kbd{C-x t} commands differ in how they find or create the 1297buffer to select. The following commands can be used to select a buffer 1298in a new tab: 1299 1300@table @kbd 1301@item C-x t 2 1302@kindex C-x t 2 1303@findex tab-new 1304Add a new tab (@code{tab-new}). You can control the choice of the 1305buffer displayed in a new tab by customizing the variable 1306@code{tab-bar-new-tab-choice}. 1307 1308@item C-x t b @var{bufname} @key{RET} 1309Select buffer @var{bufname} in another tab. This runs 1310@code{switch-to-buffer-other-tab}. 1311 1312@item C-x t f @var{filename} @key{RET} 1313Visit file @var{filename} and select its buffer in another tab. This 1314runs @code{find-file-other-tab}. @xref{Visiting}. 1315 1316@item C-x t d @var{directory} @key{RET} 1317Select a Dired buffer for directory @var{directory} in another tab. 1318This runs @code{dired-other-tab}. @xref{Dired}. 1319@end table 1320 1321@vindex tab-bar-new-tab-choice 1322 By default, a new tab starts with the buffer that was 1323current before calling the command that adds a new tab. 1324To start a new tab with other buffers, customize the variable 1325@code{tab-bar-new-tab-choice}. 1326 1327@vindex tab-bar-new-tab-to 1328 The variable @code{tab-bar-new-tab-to} defines where to place a new tab. 1329By default, a new tab is added on the right side of the current tab. 1330 1331 The following commands can be used to delete tabs: 1332 1333@table @kbd 1334@item C-x t 0 1335@kindex C-x t 0 1336@findex tab-close 1337Close the selected tab (@code{tab-close}). It has no effect if there 1338is only one tab, unless the variable @code{tab-bar-close-last-tab-choice} 1339is customized to a non-default value. 1340 1341@item C-x t 1 1342@kindex C-x t 1 1343@findex tab-close-other 1344Close all tabs on the selected frame, except the selected one. 1345@end table 1346 1347@vindex tab-bar-close-tab-select 1348 The variable @code{tab-bar-close-tab-select} defines what tab to 1349select after closing the current tab. By default, it selects 1350a recently used tab. 1351 1352@findex tab-undo 1353 The command @code{tab-undo} restores the last closed tab. 1354 1355 The following commands can be used to switch between tabs: 1356 1357@table @kbd 1358@item C-x t o 1359@itemx C-@key{TAB} 1360@kindex C-x t o 1361@kindex C-TAB 1362@findex tab-next 1363Switch to the next tab. If you repeat this command, it cycles through 1364all the tabs on the selected frame. With a positive numeric argument 1365@var{n}, it switches to the next @var{n}th tab; with a negative 1366argument @minus{}@var{n}, it switches back to the previous @var{n}th 1367tab. 1368 1369@item S-C-@key{TAB} 1370@kindex S-C-TAB 1371@findex tab-previous 1372Switch to the previous tab. With a positive numeric argument @var{n}, 1373it switches to the previous @var{n}th tab; with a negative argument 1374@minus{}@var{n}, it switches back to the next @var{n}th tab. 1375 1376@item C-x t @key{RET} @var{tabname} @key{RET} 1377Switch to the tab by its name, with completion on all tab names. 1378Default values are tab names sorted by recency, so you can use 1379@kbd{M-n} (@code{next-history-element}) to get the name of the last 1380visited tab, the second last, and so on. 1381 1382@item @var{modifier}-@var{tabnumber} 1383@findex tab-select 1384Switch to the tab by its number. After customizing the variable 1385@code{tab-bar-select-tab-modifiers} to specify a @var{modifier} key, you 1386can select a tab by its ordinal number using the specified modifier in 1387combination with the tab number to select. To display the tab number 1388alongside the tab name, you can customize another variable 1389@code{tab-bar-tab-hints}. This will help you to decide what key to press 1390to select the tab by its number. 1391 1392@item @var{modifier}-@kbd{0} 1393@findex tab-recent 1394Switch to the recent tab. The key combination is the modifier key 1395defined by @code{tab-bar-select-tab-modifiers} and the key @kbd{0}. 1396With a numeric argument @var{n}, switch to the @var{n}th recent tab. 1397@end table 1398 1399 The following commands can be used to operate on tabs: 1400 1401@table @kbd 1402@item C-x t r @var{tabname} @key{RET} 1403@findex tab-rename 1404Rename the current tab to @var{tabname}. You can control the 1405programmatic name given to a tab by default by customizing the 1406variable @code{tab-bar-tab-name-function}. 1407 1408@item C-x t m 1409@findex tab-move 1410Move the current tab @var{n} positions to the right with a positive 1411numeric argument @var{n}. With a negative argument @minus{}@var{n}, 1412move the current tab @var{n} positions to the left. 1413@end table 1414 1415@findex tab-bar-history-mode 1416 You can enable @code{tab-bar-history-mode} to remember window 1417configurations used in every tab, and restore them. 1418 1419@table @kbd 1420@item tab-bar-history-back 1421Restore a previous window configuration used in the current tab. 1422This navigates back in the history of window configurations. 1423 1424@item tab-bar-history-forward 1425Cancel restoration of the previous window configuration. 1426This navigates forward in the history of window configurations. 1427@end table 1428 1429@node Dialog Boxes 1430@section Using Dialog Boxes 1431@cindex dialog boxes 1432 1433@vindex use-dialog-box 1434 A dialog box is a special kind of menu for asking you a yes-or-no 1435question or some other special question. Many Emacs commands use a 1436dialog box to ask a yes-or-no question, if you used the mouse to 1437invoke the command that led to the question. 1438 1439 To disable the use of dialog boxes, change the variable 1440@code{use-dialog-box} to @code{nil}. In that case, Emacs always 1441performs yes-or-no prompts using the echo area and keyboard input. 1442This variable also controls whether to use file selection windows (but 1443those are not supported on all platforms). 1444 1445@vindex use-file-dialog 1446@cindex file selection dialog, how to disable 1447 A file selection window is a special kind of dialog box for asking 1448for file names. You can customize the variable @code{use-file-dialog} 1449to suppress the use of file selection windows, even if you still want 1450other kinds of dialogs. This variable has no effect if you have 1451suppressed all dialog boxes with the variable @code{use-dialog-box}. 1452 1453@vindex x-gtk-show-hidden-files 1454@vindex x-gtk-file-dialog-help-text 1455@cindex hidden files, in GTK+ file chooser 1456@cindex help text, in GTK+ file chooser 1457 When Emacs is compiled with GTK+ support, it uses the GTK+ file 1458chooser dialog. Emacs adds an additional toggle button to this 1459dialog, which you can use to enable or disable the display of hidden 1460files (files starting with a dot) in that dialog. If you want this 1461toggle to be activated by default, change the variable 1462@code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds 1463help text to the GTK+ file chooser dialog; to disable this help text, 1464change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. 1465 1466@node Tooltips 1467@section Tooltips 1468@cindex tooltips 1469 1470 @dfn{Tooltips} are small special frames that display text 1471information at the current mouse position. They activate when there 1472is a pause in mouse movement over some significant piece of text in a 1473window, or the mode line, or some other part of the Emacs frame such 1474as a tool bar button or menu item. 1475 1476@findex tooltip-mode 1477 You can toggle the use of tooltips with the command @kbd{M-x 1478tooltip-mode}. When Tooltip mode is disabled, the help text is 1479displayed in the echo area instead. To control the use of tooltips at 1480startup, customize the variable @code{tooltip-mode}. 1481 1482The following variables provide customization options for tooltip 1483display: 1484 1485@vtable @code 1486@item tooltip-delay 1487This variable specifies how long Emacs should wait before displaying 1488the first tooltip. The value is in seconds. 1489 1490@item tooltip-short-delay 1491This variable specifies how long Emacs should wait before displaying 1492subsequent tooltips on different items, having already displayed the 1493first tooltip. The value is in seconds. 1494 1495@item tooltip-hide-delay 1496The number of seconds since displaying a tooltip to hide it, if the 1497mouse doesn't move. 1498 1499@item tooltip-x-offset 1500@itemx tooltip-y-offset 1501The X and Y offsets, in pixels, of the left top corner of the tooltip 1502from the mouse pointer position. Note that these are ignored if 1503@code{tooltip-frame-parameters} was customized to include, 1504respectively, the @code{left} and @code{top} parameters. The values 1505of the offsets should be chosen so that the tooltip doesn't cover the 1506mouse pointer's hot spot, or it might interfere with clicking the 1507mouse. 1508 1509@item tooltip-frame-parameters 1510The frame parameters used for displaying tooltips. @xref{Frame 1511Parameters,,, elisp, The Emacs Lisp Reference Manual}, and also 1512@ref{Tooltips,,, elisp, The Emacs Lisp Reference Manual}. 1513@end vtable 1514 1515For additional customization options for displaying tooltips, use 1516@kbd{M-x customize-group @key{RET} tooltip @key{RET}}. 1517 1518@vindex x-gtk-use-system-tooltips 1519 If Emacs is built with GTK+ support, it displays tooltips via GTK+, 1520using the default appearance of GTK+ tooltips. To disable this, 1521change the variable @code{x-gtk-use-system-tooltips} to @code{nil}. 1522If you do this, or if Emacs is built without GTK+ support, most 1523attributes of the tooltip text are specified by the @code{tooltip} 1524face, and by X resources (@pxref{X Resources}). 1525 1526 @dfn{GUD tooltips} are special tooltips that show the values of 1527variables when debugging a program with GUD@. @xref{Debugger 1528Operation}. 1529 1530@node Mouse Avoidance 1531@section Mouse Avoidance 1532@cindex avoiding mouse in the way of your typing 1533@cindex mouse avoidance 1534 1535 On graphical terminals, the mouse pointer may obscure the text in 1536the Emacs frame. Emacs provides two methods to avoid this problem. 1537 1538 Firstly, Emacs hides the mouse pointer each time you type a 1539self-inserting character, if the pointer lies inside an Emacs frame; 1540moving the mouse pointer makes it visible again. To disable this 1541feature, set the variable @code{make-pointer-invisible} to @code{nil}. 1542@xref{Display Custom}. 1543 1544@vindex mouse-avoidance-mode 1545 Secondly, you can use Mouse Avoidance mode, a minor mode, to keep 1546the mouse pointer away from point. To use Mouse Avoidance mode, 1547customize the variable @code{mouse-avoidance-mode}. You can set this 1548to various values to move the mouse in several ways: 1549 1550@table @code 1551@item banish 1552Move the pointer to a corner of the frame on any key-press. You can 1553customize the variable @code{mouse-avoidance-banish-position} to 1554specify where the pointer goes when it is banished. 1555@item exile 1556Banish the pointer only if the cursor gets too close, and allow it to 1557return once the cursor is out of the way. 1558@item jump 1559If the cursor gets too close to the pointer, displace the pointer by a 1560random distance and direction. 1561@item animate 1562As @code{jump}, but shows steps along the way for illusion of motion. 1563@item cat-and-mouse 1564The same as @code{animate}. 1565@item proteus 1566As @code{animate}, but changes the shape of the mouse pointer too. 1567@end table 1568 1569@findex mouse-avoidance-mode 1570You can also use the command @kbd{M-x mouse-avoidance-mode} to enable 1571the mode. Whenever Mouse Avoidance mode moves the mouse, it also 1572raises the frame. 1573 1574@node Non-Window Terminals 1575@section Non-Window Terminals 1576@cindex text terminal 1577 1578 On a text terminal, Emacs can display only one Emacs frame at a 1579time. However, you can still create multiple Emacs frames, and switch 1580between them. Switching frames on these terminals is much like 1581switching between different window configurations. 1582 1583 Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x 15845 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete 1585the current frame. 1586 1587 Each frame has a number to distinguish it. If your terminal can 1588display only one frame at a time, the selected frame's number @var{n} 1589appears near the beginning of the mode line, in the form 1590@samp{F@var{n}}. 1591 1592@findex set-frame-name 1593@findex select-frame-by-name 1594 @samp{F@var{n}} is in fact the frame's initial name. You can give 1595frames more meaningful names if you wish, and you can select a frame 1596by its name. Use the command @kbd{M-x set-frame-name @key{RET} 1597@var{name} @key{RET}} to specify a new name for the selected frame, 1598and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}} 1599to select a frame according to its name. The name you specify appears 1600in the mode line when the frame is selected. 1601 1602@node Text-Only Mouse 1603@section Using a Mouse in Text Terminals 1604@cindex mouse support 1605@cindex terminal emulators, mouse support 1606 1607Some text terminals support mouse clicks in the terminal window. 1608 1609@cindex xterm 1610 In a terminal emulator which is compatible with @command{xterm}, you 1611can use @kbd{M-x xterm-mouse-mode} to give Emacs control over simple 1612uses of the mouse---basically, only non-modified single clicks are 1613supported. Newer versions of @command{xterm} also support 1614mouse-tracking. The normal @command{xterm} mouse functionality for 1615such clicks is still available by holding down the @key{SHIFT} key 1616when you press the mouse button. Xterm Mouse mode is a global minor 1617mode (@pxref{Minor Modes}). Repeating the command turns the mode off 1618again. 1619 1620@findex gpm-mouse-mode 1621 In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to 1622enable mouse support. You must have the gpm server installed and 1623running on your system in order for this to work. Note that when 1624this mode is enabled, you cannot use the mouse to transfer text 1625between Emacs and other programs which use GPM@. This is due to 1626limitations in GPM and the Linux kernel. 1627 1628@iftex 1629@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}, 1630@end iftex 1631@ifnottex 1632@xref{MS-DOS Mouse}, 1633@end ifnottex 1634for information about mouse support on MS-DOS. 1635