Commit 82233bea authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 57939ff4
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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment