elisp: Tabulated List Mode
22.2.7 Tabulated List mode
--------------------------
Tabulated List mode is a major mode for displaying tabulated data, i.e.,
data consisting of “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
(
Basic Major Modes).
Tabulated List mode is intended to be used as a parent mode by a more
Process Information::) and Package Menu mode ((emacs)Package
Menu).
Such a derived mode should use ‘define-derived-mode’ in the usual
way, specifying ‘tabulated-list-mode’ as the second argument (
Derived Modes). The body of the ‘define-derived-mode’ form should
specify the format of the tabulated data, by assigning values to the
variables documented below; optionally, it can then call the function
‘tabulated-list-init-header’, which will populate a header with the
names of the columns.
The derived mode should also define a “listing command”. This, not
the mode command, is what the user calls (e.g., ‘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
‘tabulated-list-print’ to populate the buffer.
-- Variable: 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 ‘(NAME WIDTH
SORT)’, where
• NAME is the column’s name (a string).
• 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.
• SORT specifies how to sort entries by the column. If ‘nil’,
the column cannot be used for sorting. If ‘t’, the column is
sorted by comparing string values. Otherwise, this should be
a predicate function for ‘sort’ (Rearrangement), which
accepts two arguments with the same form as the elements of
‘tabulated-list-entries’ (see below).
-- Variable: 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 ‘(ID CONTENTS)’, where
• ID is either ‘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 ‘equal’.
• CONTENTS is a vector with the same number of elements as
‘tabulated-list-format’. Each vector element is either a
string, which is inserted into the buffer as-is, or a list
‘(LABEL . PROPERTIES)’, which means to insert a text button by
calling ‘insert-text-button’ with LABEL and PROPERTIES as
arguments (Making Buttons).
There should be no newlines in any of these strings.
Otherwise, the value should be a function which returns a list of
the above form when called with no arguments.
-- Variable: 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
‘tabulated-list-entries’.
-- Variable: 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, ID and CONTENTS, having the same
meanings as in ‘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.
-- Variable: tabulated-list-sort-key
The value of this variable specifies the current sort key for the
Tabulated List buffer. If it is ‘nil’, no sorting is done.
Otherwise, it should have the form ‘(NAME . FLIP)’, where NAME is a
string matching one of the column names in ‘tabulated-list-format’,
and FLIP, if non-‘nil’, means to invert the sort order.
-- Function: tabulated-list-init-header
This function computes and sets ‘header-line-format’ for the
Tabulated List buffer (Header Lines), and assigns a keymap
to the header line to allow sorting 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
‘tabulated-list-format’).
-- Function: tabulated-list-print &optional remember-pos update
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 ‘tabulated-list-entries’ according to
‘tabulated-list-sort-key’, then calls the function specified by
‘tabulated-list-printer’ to insert each entry.
If the optional argument REMEMBER-POS is non-‘nil’, this function
looks for the ID element on the current line, if any, and tries to
move to that entry after all the entries are (re)inserted.
If the optional argument UPDATE is non-‘nil’, this function will
only erase or add entries that have changed since the last print.
This is several times faster if most entries haven’t changed since
the last time this function was called. The only difference in
outcome is that tags placed via ‘tabulated-list-put-tag’ will not
be removed from entries that haven’t changed (normally all tags are
removed).
Info Catalog
elisp: Mode Hooks
elisp: Major Modes
elisp: Generic Modes