Next: Generic Modes, Previous: Mode Hooks, Up: Major Modes
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 (see 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 (see Process Information) and Package Menu mode (see Package Menu).
Such a derived mode should use define-derived-mode in the usual
way, specifying tabulated-list-mode as the second argument
(see 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; then, it should call the
function tabulated-list-init-header to initialize the header
line.
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.
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. Ift, the column is sorted by comparing string values. Otherwise, this should be a predicate function forsort(see Rearrangement), which accepts two arguments with the same form as the elements oftabulated-list-entries(see below).
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
(idcontents), 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 withequal.- 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 callinginsert-text-buttonwith label and properties as arguments (see 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.
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.
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.
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 intabulated-list-format, and flip, if non-nil, means to invert the sort order.
This function computes and sets
header-line-formatfor the Tabulated List buffer (see 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
tabulated-list-format).
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-entriesaccording totabulated-list-sort-key, then calls the function specified bytabulated-list-printerto 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.