Give Tabulated List mode its own Lisp manual node.
* modes.texi (Tabulated List Mode): New node. (Basic Major Modes): Add xref to it. * processes.texi (Process Information): Mention Process Menu mode.
This commit is contained in:
Chong Yidong
parent
57939ff41e
commit
82233bead8
6 changed files with 195 additions and 61 deletions
|
|
@ -1,3 +1,10 @@
|
|||
2012-02-18 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* modes.texi (Tabulated List Mode): New node.
|
||||
(Basic Major Modes): Add xref to it.
|
||||
|
||||
* processes.texi (Process Information): Mention Process Menu mode.
|
||||
|
||||
2012-02-17 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* syntax.texi (Motion via Parsing): Doc fix for scan-lists.
|
||||
|
|
|
|||
|
|
@ -781,9 +781,10 @@ Major Modes
|
|||
* Derived Modes:: Defining a new major mode based on another major
|
||||
mode.
|
||||
* Basic Major Modes:: Modes that other modes are often derived from.
|
||||
* Mode Hooks:: Hooks run at the end of major mode functions.
|
||||
* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
|
||||
* Generic Modes:: Defining a simple major mode that supports
|
||||
comment syntax and Font Lock mode.
|
||||
* Mode Hooks:: Hooks run at the end of major mode functions.
|
||||
* Example Major Modes:: Text mode and Lisp modes.
|
||||
|
||||
Minor Modes
|
||||
|
|
|
|||
|
|
@ -284,9 +284,10 @@ buffer is put in Fundamental mode (@pxref{Major Mode Conventions}).
|
|||
* Derived Modes:: Defining a new major mode based on another major
|
||||
mode.
|
||||
* Basic Major Modes:: Modes that other modes are often derived from.
|
||||
* Mode Hooks:: Hooks run at the end of major mode commands.
|
||||
* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
|
||||
* Generic Modes:: Defining a simple major mode that supports
|
||||
comment syntax and Font Lock mode.
|
||||
* Mode Hooks:: Hooks run at the end of major mode commands.
|
||||
* Example Major Modes:: Text mode and Lisp modes.
|
||||
@end menu
|
||||
|
||||
|
|
@ -893,9 +894,9 @@ Prog mode binds @code{parse-sexp-ignore-comments} to @code{t}
|
|||
|
||||
@deffn Command special-mode
|
||||
Special mode is a basic major mode for buffers containing text that is
|
||||
produced specially by Emacs, rather than from a file. Major modes
|
||||
derived from Special mode are given a @code{mode-class} property of
|
||||
@code{special} (@pxref{Major Mode Conventions}).
|
||||
produced specially by Emacs, rather than directly from a file. Major
|
||||
modes derived from Special mode are given a @code{mode-class} property
|
||||
of @code{special} (@pxref{Major Mode Conventions}).
|
||||
|
||||
Special mode sets the buffer to read-only. Its keymap defines several
|
||||
common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
|
||||
|
|
@ -907,60 +908,9 @@ mode, which is used by the @samp{*Buffer List*} buffer. @xref{List
|
|||
Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
|
||||
@end deffn
|
||||
|
||||
@cindex tables of data
|
||||
@deffn Command tabulated-list-mode
|
||||
Tabulated List mode is another mode that derives from Special mode. It
|
||||
displays tabulated data, i.e. a series of rows and columns, where each
|
||||
row represents a particular entry, whose properties are displayed in the
|
||||
various columns. It provides a general mechanism for sorting on
|
||||
columns. You can use Tabulated List mode as the basis for other modes
|
||||
that need to display lists. For example, the @samp{*Packages*} buffer
|
||||
uses this (@pxref{Packages,,, emacs, The GNU Emacs Manual}). The
|
||||
documentation of the @code{tabulated-list-mode} function explains what
|
||||
you need to do to use it. At a minimum, specify the column format via
|
||||
the @code{tabulated-list-format} variable.
|
||||
@end deffn
|
||||
|
||||
@node Generic Modes
|
||||
@subsection Generic Modes
|
||||
@cindex generic mode
|
||||
|
||||
@dfn{Generic modes} are simple major modes with basic support for
|
||||
comment syntax and Font Lock mode. To define a generic mode, use the
|
||||
macro @code{define-generic-mode}. See the file @file{generic-x.el}
|
||||
for some examples of the use of @code{define-generic-mode}.
|
||||
|
||||
@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
|
||||
This macro defines a generic mode command named @var{mode} (a symbol,
|
||||
not quoted). The optional argument @var{docstring} is the
|
||||
documentation for the mode command. If you do not supply it,
|
||||
@code{define-generic-mode} generates one by default.
|
||||
|
||||
The argument @var{comment-list} is a list in which each element is
|
||||
either a character, a string of one or two characters, or a cons cell.
|
||||
A character or a string is set up in the mode's syntax table as a
|
||||
``comment starter.'' If the entry is a cons cell, the @sc{car} is set
|
||||
up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
|
||||
(Use @code{nil} for the latter if you want comments to end at the end
|
||||
of the line.) Note that the syntax table mechanism has limitations
|
||||
about what comment starters and enders are actually possible.
|
||||
@xref{Syntax Tables}.
|
||||
|
||||
The argument @var{keyword-list} is a list of keywords to highlight
|
||||
with @code{font-lock-keyword-face}. Each keyword should be a string.
|
||||
Meanwhile, @var{font-lock-list} is a list of additional expressions to
|
||||
highlight. Each element of this list should have the same form as an
|
||||
element of @code{font-lock-keywords}. @xref{Search-based
|
||||
Fontification}.
|
||||
|
||||
The argument @var{auto-mode-list} is a list of regular expressions to
|
||||
add to the variable @code{auto-mode-alist}. They are added by the execution
|
||||
of the @code{define-generic-mode} form, not by expanding the macro call.
|
||||
|
||||
Finally, @var{function-list} is a list of functions for the mode
|
||||
command to call for additional setup. It calls these functions just
|
||||
before it runs the mode hook variable @code{@var{mode}-hook}.
|
||||
@end defmac
|
||||
In addition, modes for buffers of tabulated data can inherit from
|
||||
Tabulated List mode, which is in turn derived from Special mode.
|
||||
@xref{Tabulated List Mode}.
|
||||
|
||||
@node Mode Hooks
|
||||
@subsection Mode Hooks
|
||||
|
|
@ -1021,6 +971,177 @@ This is a normal hook run by @code{run-mode-hooks}. It is run at the
|
|||
very end of every properly-written major mode command.
|
||||
@end defvar
|
||||
|
||||
@node Tabulated List Mode
|
||||
@subsection Tabulated List mode
|
||||
@cindex Tabulated List mode
|
||||
|
||||
Tabulated List mode is a major mode for displaying tabulated data,
|
||||
i.e.@: data consisting of @dfn{entries}, each entry occupying one row of
|
||||
text with its contents divided into columns. Tabulated List mode
|
||||
provides facilities for pretty-printing rows and columns, and sorting
|
||||
the rows according to the values in each column. It is derived from
|
||||
Special mode (@pxref{Basic Major Modes}).
|
||||
|
||||
Tabulated List mode is intended to be used as a parent mode by a more
|
||||
specialized major mode. Examples include Process Menu mode
|
||||
(@pxref{Process Information}) and Package Menu mode (@pxref{Package
|
||||
Menu,,, emacs, The GNU Emacs Manual}).
|
||||
|
||||
@findex tabulated-list-mode
|
||||
Such a derived mode should use @code{define-derived-mode} in the usual
|
||||
way, specifying @code{tabulated-list-mode} as the second argument
|
||||
(@pxref{Derived Modes}). The body of the @code{define-derived-mode}
|
||||
form should specify the format of the tabulated data, by assigning
|
||||
values to the variables documented below; then, it should call the
|
||||
function @code{tabulated-list-init-header} to initialize the header
|
||||
line.
|
||||
|
||||
The derived mode should also define a @dfn{listing command}. This,
|
||||
not the mode command, is what the user calls (e.g.@: @kbd{M-x
|
||||
list-processes}). The listing command should create or switch to a
|
||||
buffer, turn on the derived mode, specify the tabulated data, and
|
||||
finally call @code{tabulated-list-print} to populate the buffer.
|
||||
|
||||
@defvar tabulated-list-format
|
||||
This buffer-local variable specifies the format of the Tabulated List
|
||||
data. Its value should be a vector. Each element of the vector
|
||||
represents a data column, and should be a list @code{(@var{name}
|
||||
@var{width} @var{sort})}, where
|
||||
|
||||
@itemize
|
||||
@item
|
||||
@var{name} is the column's name (a string).
|
||||
|
||||
@item
|
||||
@var{width} is the width to reserve for the column (an integer). This
|
||||
is meaningless for the last column, which runs to the end of each line.
|
||||
|
||||
@item
|
||||
@var{sort} specifies how to sort entries by the column. If @code{nil},
|
||||
the column cannot be used for sorting. If @code{t}, the column is
|
||||
sorted by comparing string values. Otherwise, this should be a
|
||||
predicate function for @code{sort} (@pxref{Rearrangement}), which
|
||||
accepts two arguments with the same form as the elements of
|
||||
@code{tabulated-list-entries} (see below).
|
||||
@end itemize
|
||||
@end defvar
|
||||
|
||||
@defvar tabulated-list-entries
|
||||
This buffer-local variable specifies the entries displayed in the
|
||||
Tabulated List buffer. Its value should be either a list, or a
|
||||
function.
|
||||
|
||||
If the value is a list, each list element corresponds to one entry, and
|
||||
should have the form @w{@code{(@var{id} @var{contents})}}, where
|
||||
|
||||
@itemize
|
||||
@item
|
||||
@var{id} is either @code{nil}, or a Lisp object that identifies the
|
||||
entry. If the latter, the cursor stays on the ``same'' entry when
|
||||
re-sorting entries. Comparison is done with @code{equal}.
|
||||
|
||||
@item
|
||||
@var{contents} is a vector with the same number of elements as
|
||||
@code{tabulated-list-format}. Each vector element is either a string,
|
||||
which is inserted into the buffer as-is, or a list @code{(@var{label}
|
||||
. @var{properties})}, which means to insert a text button by calling
|
||||
@code{insert-text-button} with @var{label} and @var{properties} as
|
||||
arguments (@pxref{Making Buttons}).
|
||||
|
||||
There should be no newlines in any of these strings.
|
||||
@end itemize
|
||||
|
||||
Otherwise, the value should be a function which returns a list of the
|
||||
above form when called with no arguments.
|
||||
@end defvar
|
||||
|
||||
@defvar tabulated-list-revert-hook
|
||||
This normal hook is run prior to reverting a Tabulated List buffer. A
|
||||
derived mode can add a function to this hook to recompute
|
||||
@code{tabulated-list-entries}.
|
||||
@end defvar
|
||||
|
||||
@defvar tabulated-list-printer
|
||||
The value of this variable is the function called to insert an entry at
|
||||
point, including its terminating newline. The function should accept
|
||||
two arguments, @var{id} and @var{contents}, having the same meanings as
|
||||
in @code{tabulated-list-entries}. The default value is a function which
|
||||
inserts an entry in a straightforward way; a mode which uses Tabulated
|
||||
List mode in a more complex way can specify another function.
|
||||
@end defvar
|
||||
|
||||
@defvar tabulated-list-sort-key
|
||||
The value of this variable specifies the current sort key for the
|
||||
Tabulated List buffer. If it is @code{nil}, no sorting is done.
|
||||
Otherwise, it should have the form @code{(@var{name} . @var{flip})},
|
||||
where @var{name} is a string matching one of the column names in
|
||||
@code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means
|
||||
to invert the sort order.
|
||||
@end defvar
|
||||
|
||||
@defun tabulated-list-init-header
|
||||
This function computes and sets @code{header-line-format} for the
|
||||
Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to
|
||||
the header line to allow sort entries by clicking on column headers.
|
||||
|
||||
Modes derived from Tabulated List mode should call this after setting
|
||||
the above variables (in particular, only after setting
|
||||
@code{tabulated-list-format}).
|
||||
@end defun
|
||||
|
||||
@defun tabulated-list-print &optional remember-pos
|
||||
This function populates the current buffer with entries. It should be
|
||||
called by the listing command. It erases the buffer, sorts the entries
|
||||
specified by @code{tabulated-list-entries} according to
|
||||
@code{tabulated-list-sort-key}, then calls the function specified by
|
||||
@code{tabulated-list-printer} to insert each entry.
|
||||
|
||||
If the optional argument @var{remember-pos} is non-@code{nil}, this
|
||||
function looks for the @var{id} element on the current line, if any, and
|
||||
tries to move to that entry after all the entries are (re)inserted.
|
||||
@end defun
|
||||
|
||||
@node Generic Modes
|
||||
@subsection Generic Modes
|
||||
@cindex generic mode
|
||||
|
||||
@dfn{Generic modes} are simple major modes with basic support for
|
||||
comment syntax and Font Lock mode. To define a generic mode, use the
|
||||
macro @code{define-generic-mode}. See the file @file{generic-x.el}
|
||||
for some examples of the use of @code{define-generic-mode}.
|
||||
|
||||
@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
|
||||
This macro defines a generic mode command named @var{mode} (a symbol,
|
||||
not quoted). The optional argument @var{docstring} is the
|
||||
documentation for the mode command. If you do not supply it,
|
||||
@code{define-generic-mode} generates one by default.
|
||||
|
||||
The argument @var{comment-list} is a list in which each element is
|
||||
either a character, a string of one or two characters, or a cons cell.
|
||||
A character or a string is set up in the mode's syntax table as a
|
||||
``comment starter.'' If the entry is a cons cell, the @sc{car} is set
|
||||
up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
|
||||
(Use @code{nil} for the latter if you want comments to end at the end
|
||||
of the line.) Note that the syntax table mechanism has limitations
|
||||
about what comment starters and enders are actually possible.
|
||||
@xref{Syntax Tables}.
|
||||
|
||||
The argument @var{keyword-list} is a list of keywords to highlight
|
||||
with @code{font-lock-keyword-face}. Each keyword should be a string.
|
||||
Meanwhile, @var{font-lock-list} is a list of additional expressions to
|
||||
highlight. Each element of this list should have the same form as an
|
||||
element of @code{font-lock-keywords}. @xref{Search-based
|
||||
Fontification}.
|
||||
|
||||
The argument @var{auto-mode-list} is a list of regular expressions to
|
||||
add to the variable @code{auto-mode-alist}. They are added by the execution
|
||||
of the @code{define-generic-mode} form, not by expanding the macro call.
|
||||
|
||||
Finally, @var{function-list} is a list of functions for the mode
|
||||
command to call for additional setup. It calls these functions just
|
||||
before it runs the mode hook variable @code{@var{mode}-hook}.
|
||||
@end defmac
|
||||
|
||||
@node Example Major Modes
|
||||
@subsection Major Mode Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -714,6 +714,9 @@ This command displays a listing of all living processes. In addition,
|
|||
it finally deletes any process whose status was @samp{Exited} or
|
||||
@samp{Signaled}. It returns @code{nil}.
|
||||
|
||||
The processes are shown in a buffer named @samp{*Process List*}, whose
|
||||
major mode is named Process Menu mode.
|
||||
|
||||
If @var{query-only} is non-@code{nil} then it lists only processes
|
||||
whose query flag is non-@code{nil}. @xref{Query Before Exit}.
|
||||
@end deffn
|
||||
|
|
|
|||
|
|
@ -802,9 +802,10 @@ Major Modes
|
|||
* Derived Modes:: Defining a new major mode based on another major
|
||||
mode.
|
||||
* Basic Major Modes:: Modes that other modes are often derived from.
|
||||
* Mode Hooks:: Hooks run at the end of major mode commands.
|
||||
* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
|
||||
* Generic Modes:: Defining a simple major mode that supports
|
||||
comment syntax and Font Lock mode.
|
||||
* Mode Hooks:: Hooks run at the end of major mode commands.
|
||||
* Example Major Modes:: Text mode and Lisp modes.
|
||||
|
||||
Minor Modes
|
||||
|
|
|
|||
|
|
@ -801,9 +801,10 @@ Major Modes
|
|||
* Derived Modes:: Defining a new major mode based on another major
|
||||
mode.
|
||||
* Basic Major Modes:: Modes that other modes are often derived from.
|
||||
* Mode Hooks:: Hooks run at the end of major mode commands.
|
||||
* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
|
||||
* Generic Modes:: Defining a simple major mode that supports
|
||||
comment syntax and Font Lock mode.
|
||||
* Mode Hooks:: Hooks run at the end of major mode commands.
|
||||
* Example Major Modes:: Text mode and Lisp modes.
|
||||
|
||||
Minor Modes
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue