[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] feature/tabs 457a7ed 2/2: Update documentation for tabs.
|
From: |
Juri Linkov |
|
Subject: |
[Emacs-diffs] feature/tabs 457a7ed 2/2: Update documentation for tabs. |
|
Date: |
Sat, 28 Sep 2019 15:55:44 -0400 (EDT) |
branch: feature/tabs
commit 457a7edb4784869079eac2a47d2dc1738332c07a
Author: Juri Linkov <address@hidden>
Commit: Juri Linkov <address@hidden>
Update documentation for tabs.
* doc/emacs/frames.texi (Tab Bars): New node.
---
doc/emacs/custom.texi | 4 ++++
doc/emacs/display.texi | 6 ++++++
doc/emacs/emacs.texi | 1 +
doc/emacs/frames.texi | 36 ++++++++++++++++++++++++++++++++++++
doc/emacs/glossary.texi | 9 +++++++++
doc/emacs/modes.texi | 6 ++++++
doc/lispref/commands.texi | 19 +++++++++++--------
doc/lispref/display.texi | 1 +
doc/lispref/windows.texi | 12 ++++++++++++
etc/NEWS | 12 ++++++------
lisp/tab-bar.el | 3 ++-
11 files changed, 94 insertions(+), 15 deletions(-)
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index d3d7d97..2550987 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 6fc99bd..84363d0 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 ad4be90..aef0e9b 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 367ac43..0003881 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 ad16d72..30ddffa 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 e01dfa2..64034d7 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -296,6 +296,12 @@ 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
by default. @xref{Mark}.
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 1fd56d0..541a97f 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 7c0a56d..3b2049a 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 39d3960..f05a6db 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 37382e8..f824ecc 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 fb13ff4..3108c59 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.