From: Juri Linkov Date: Sat, 28 Sep 2019 19:55:05 +0000 (+0300) Subject: Update documentation for tabs. X-Git-Tag: emacs-27.0.90~1328^2~1 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=457a7edb4784869079eac2a47d2dc1738332c07a;p=emacs.git Update documentation for tabs. * doc/emacs/frames.texi (Tab Bars): New node. --- diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index d3d7d97120a..25509878f9b 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -2150,6 +2150,10 @@ The mouse was in a vertical scroll bar. (This is the only kind of scroll bar Emacs currently supports.) @item menu-bar The mouse was in the menu bar. +@item tab-bar +The mouse was in a tab bar. +@item tab-line +The mouse was in a tab line. @item header-line The mouse was in a header line. @ignore diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 6fc99bd2716..84363d0f0d2 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -722,6 +722,10 @@ Similar to @code{highlight} and @code{mode-line-highlight}, but used for mouse-sensitive portions of text on header lines. This is a separate face because the @code{header-line} face might be customized in a way that does not interact well with @code{highlight}. +@item tab-line +@cindex @code{tab-line} face +Similar to @code{mode-line} for a window's tab line, which appears +at the top of a window with tabs representing window buffers. @item vertical-border @cindex @code{vertical-border} face This face is used for the vertical divider between windows on text @@ -763,6 +767,8 @@ This face determines the visual appearance of the scroll bar. @xref{Scroll Bars}. @item tool-bar This face determines the color of tool bar icons. @xref{Tool Bars}. +@item tab-bar +This face determines the color of tab bar icons. @xref{Tab Bars}. @item menu @cindex menu bar appearance @cindex @code{menu} face, no effect if customized diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index ad4be90aaf3..aef0e9b37e3 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -540,6 +540,7 @@ Frames and Graphical Displays * Drag and Drop:: Using drag and drop to open files and insert text. * Menu Bars:: Enabling and disabling the menu bar. * Tool Bars:: Enabling and disabling the tool bar. +* Tab Bars:: Enabling and disabling the tab bar. * Dialog Boxes:: Controlling use of dialog boxes. * Tooltips:: Displaying information at the current mouse position. * Mouse Avoidance:: Preventing the mouse pointer from obscuring text. diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 367ac43a0a4..0003881fad1 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -58,6 +58,7 @@ for doing so on MS-DOS). Menus are supported on all text terminals. * Drag and Drop:: Using drag and drop to open files and insert text. * Menu Bars:: Enabling and disabling the menu bar. * Tool Bars:: Enabling and disabling the tool bar. +* Tab Bars:: Enabling and disabling the tab bar. * Dialog Boxes:: Controlling use of dialog boxes. * Tooltips:: Displaying information at the current mouse position. * Mouse Avoidance:: Preventing the mouse pointer from obscuring text. @@ -1214,6 +1215,41 @@ Parameters,,, elisp, The Emacs Lisp Reference Manual}. On macOS the tool bar is hidden when the frame is put into fullscreen, but can be displayed by moving the mouse pointer to the top of the screen. +@node Tab Bars +@section Tab Bars +@cindex Tab Bar mode +@cindex mode, Tab Bar +@cindex tabs, tabbar + + On graphical displays and on text terminals, Emacs puts a @dfn{tab bar} +at the top of each frame, just below the menu bar. This is a row of +tabs which you can click on with the mouse to switch window configurations. + + Each tab on the tab bar represents a named persistent window +configuration. Its name is composed from the names of buffers +visible in windows of the window configuration. Clicking on the +tab name switches the current window configuration to the previously +used configuration of windows and buffers. + + If you are using the desktop library to save and restore your +sessions, the tabs from the tab bar are recorded in the desktop file, +together with their associated window configurations. + +@findex tab-bar-mode +@vindex tab-bar-mode + To toggle the use of tab bars, type @kbd{M-x tab-bar-mode}. This +command applies to all frames, including frames yet to be created. To +control the use of tab bars at startup, customize the variable +@code{tab-bar-mode}. + +@vindex tab-bar-new-tab-choice +@cindex Tab Bar new tab + By default, Emacs follows the same behavior as when creating frames, +to start a new tab with the current buffer, i.e. the buffer +that was current before calling the command that adds a new tab. +To start a new tab with other buffers, customize the variable +@code{tab-bar-new-tab-choice}. + @node Dialog Boxes @section Using Dialog Boxes @cindex dialog boxes diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index ad16d72ddbf..30ddffab696 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -1360,6 +1360,15 @@ your buffers, unsaved edits, undo history, etc. @xref{Exiting}. @key{TAB} is the tab character. In Emacs it is typically used for indentation or completion. +@item Tab Bar +The tab bar is a row of tabs at the top of an Emacs frame. +Clicking on one of these tabs switches named persistent window +configurations. @xref{Tab Bars}. + +@item Tab Line +The tab line is a line of tabs at the top of an Emacs window. +Clicking on one of these tabs switches window buffers. + @anchor{Glossary---Tags Table} @item Tags Table A tags table is a file that serves as an index to the function diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi index e01dfa2677b..64034d71860 100644 --- a/doc/emacs/modes.texi +++ b/doc/emacs/modes.texi @@ -295,6 +295,12 @@ Tool Bar mode gives each frame a tool bar. It is enabled by default, but the tool bar is only displayed on graphical terminals. @xref{Tool Bars}. +@item +Tab Bar mode gives each frame a tab bar. @xref{Tab Bars}. + +@item +Tab Line mode gives each window a tab line. + @item Transient Mark mode highlights the region, and makes many Emacs commands operate on the region when the mark is active. It is enabled diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 1fd56d02841..541a97f8add 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1348,7 +1348,7 @@ button. @xref{Repeat Events}. @var{position} slot of a click event, you should typically use the functions documented in @ref{Accessing Mouse}. The explicit format of the list depends on where the click occurred. For clicks in the text -area, mode line, header line, or in the fringe or marginal areas, the +area, mode line, header line, tab line, or in the fringe or marginal areas, the mouse position list has the form @example @@ -1368,7 +1368,7 @@ The window in which the click occurred. The buffer position of the character clicked on in the text area; or, if the click was outside the text area, the window area where it occurred. It is one of the symbols @code{mode-line}, -@code{header-line}, @code{vertical-line}, @code{left-margin}, +@code{header-line}, @code{tab-line}, @code{vertical-line}, @code{left-margin}, @code{right-margin}, @code{left-fringe}, or @code{right-fringe}. In one special case, @var{pos-or-area} is a list containing a symbol @@ -1380,7 +1380,7 @@ by Emacs. @xref{Key Sequence Input}. The relative pixel coordinates of the click. For clicks in the text area of a window, the coordinate origin @code{(0 . 0)} is taken to be the top left corner of the text area. @xref{Window Sizes}. For -clicks in a mode line or header line, the coordinate origin is the top +clicks in a mode line, header line or tab line, the coordinate origin is the top left corner of the window itself. For fringes, margins, and the vertical border, @var{x} does not have meaningful data. For fringes and margins, @var{y} is relative to the bottom edge of the header @@ -1407,7 +1407,7 @@ The position in the string where the click occurred. @item @var{text-pos} For clicks on a marginal area or on a fringe, this is the buffer position of the first visible character in the corresponding line in -the window. For clicks on the mode line or the header line, this is +the window. For clicks on the mode line, the header line or the tab line, this is @code{nil}. For other events, it is the buffer position closest to the click. @@ -1416,7 +1416,8 @@ These are the actual column and row coordinate numbers of the glyph under the @var{x}, @var{y} position. If @var{x} lies beyond the last column of actual text on its line, @var{col} is reported by adding fictional extra columns that have the default character width. Row 0 -is taken to be the header line if the window has one, or the topmost +is taken to be the header line if the window has one, or Row 1 +if the window also has the tab line, or the topmost row of the text area otherwise. Column 0 is taken to be the leftmost column of the text area for clicks on a window text area, or the leftmost mode line or header line column for clicks there. For clicks @@ -2094,7 +2095,7 @@ computed values.) Note that @var{row} is counted from the top of the text area. If the window given by @var{position} possesses a header line (@pxref{Header -Lines}), it is @emph{not} included in the @var{row} count. +Lines}) or a tab line, they are @emph{not} included in the @var{row} count. @end defun @defun posn-actual-col-row position @@ -2452,12 +2453,14 @@ button-down events entirely. It also reshuffles focus events and miscellaneous window events so that they never appear in a key sequence with any other events. +@cindex @code{tab-line} prefix key @cindex @code{header-line} prefix key @cindex @code{mode-line} prefix key @cindex @code{vertical-line} prefix key @cindex @code{horizontal-scroll-bar} prefix key @cindex @code{vertical-scroll-bar} prefix key @cindex @code{menu-bar} prefix key +@cindex @code{tab-bar} prefix key @cindex mouse events, in special parts of frame When mouse events occur in special parts of a window, such as a mode line or a scroll bar, the event type shows nothing special---it is the @@ -2465,8 +2468,8 @@ same symbol that would normally represent that combination of mouse button and modifier keys. The information about the window part is kept elsewhere in the event---in the coordinates. But @code{read-key-sequence} translates this information into imaginary -prefix keys, all of which are symbols: @code{header-line}, -@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, +prefix keys, all of which are symbols: @code{tab-line}, @code{header-line}, +@code{horizontal-scroll-bar}, @code{menu-bar}, @code{tab-bar}, @code{mode-line}, @code{vertical-line}, and @code{vertical-scroll-bar}. You can define meanings for mouse clicks in special window parts by defining key sequences using these imaginary prefix keys. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 7c0a56dcad3..3b2049a2876 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2944,6 +2944,7 @@ If the text lies within the mode line of the selected window, Emacs applies the @code{mode-line} face. For the mode line of a non-selected window, Emacs applies the @code{mode-line-inactive} face. For a header line, Emacs applies the @code{header-line} face. +For a tab line, Emacs applies the @code{tab-line} face. @item If the text comes from an overlay string via @code{before-string} or diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 39d3960c9a2..f05a6db1761 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -5558,6 +5558,9 @@ The coordinates are in the mode line of @var{window}. @item header-line The coordinates are in the header line of @var{window}. +@item tab-line +The coordinates are in the tab line of @var{window}. + @item right-divider The coordinates are in the divider separating @var{window} from a window on the right. @@ -6115,6 +6118,15 @@ to suppress display of a header line for this window. Display and contents of the header line on other windows showing this buffer are not affected. +@item tab-line-format +@vindex tab-line-format@r{, a window parameter} +This parameter replaces the value of the buffer-local variable +@code{tab-line-format} (@pxref{Mode Line Basics}) of this window's +buffer whenever this window is displayed. The symbol @code{none} means +to suppress display of a tab line for this window. Display and +contents of the tab line on other windows showing this buffer are not +affected. + @item min-margins @vindex min-margins@r{, a window parameter} The value of this parameter is a cons cell whose @sc{car} and diff --git a/etc/NEWS b/etc/NEWS index 37382e843bd..f824eccaefc 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1896,12 +1896,12 @@ New tab-based keybindings (similar to frame-based): Also it's possible to switch named persistent window configurations without having graphical access to the tab-bar, even on a tty or when 'tab-bar-mode' is disabled, with these commands: -'list-tabs' displays a list of named window configurations for switching; -'make-tab' creates a new window configuration; -'delete-tab' deletes the current window configuration; -'switch-to-tab' switches to the window configuration by its name; -'previous-tab' switches to the previous window configuration; -'next-tab' switches to the next window configuration. +'tab-new' creates a new window configuration; +'tab-delete' deletes the current window configuration; +'tab-select' switches to the window configuration by its name; +'tab-previous' switches to the previous window configuration; +'tab-next' switches to the next window configuration; +'tab-list' displays a list of named window configurations for switching. ** 'global-tab-line-mode' enables the tab-line above each window to switch buffers in it to previous/next buffers. Selecting a previous diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el index fb13ff4178b..3108c595e94 100644 --- a/lisp/tab-bar.el +++ b/lisp/tab-bar.el @@ -481,7 +481,7 @@ specified by `tab-bar-close-tab-select'." ;;; Non-graphical access to frame-local tabs (named window configurations) -(defun tab-make () +(defun tab-new () "Create a new named window configuration without having to click a tab." (interactive) (tab-bar-new-tab) @@ -500,6 +500,7 @@ specified by `tab-bar-close-tab-select'." (defalias 'tab-select 'tab-bar-select-tab) (defalias 'tab-previous 'tab-bar-switch-to-prev-tab) (defalias 'tab-next 'tab-bar-switch-to-next-tab) +(defalias 'tab-list 'tab-bar-list) (defun tab-bar-list () "Display a list of named window configurations.