path: root/devdocs/elisp/tabulated-list-mode.html

 <h4 class="subsection">Tabulated List mode</h4>  <p>Tabulated List mode is a major mode for displaying tabulated data, i.e., data consisting of <em>entries</em>, 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 <a href="basic-major-modes">Basic Major Modes</a>). </p> <p>Tabulated List mode is intended to be used as a parent mode by a more specialized major mode. Examples include Process Menu mode (see <a href="process-information">Process Information</a>) and Package Menu mode (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Menu.html#Package-Menu">Package Menu</a> in <cite>The GNU Emacs Manual</cite>). </p>  <p>Such a derived mode should use <code>define-derived-mode</code> in the usual way, specifying <code>tabulated-list-mode</code> as the second argument (see <a href="derived-modes">Derived Modes</a>). The body of the <code>define-derived-mode</code> form should specify the format of the tabulated data, by assigning values to the variables documented below; optionally, it can then call the function <code>tabulated-list-init-header</code>, which will populate a header with the names of the columns. </p> <p>The derived mode should also define a <em>listing command</em>. This, not the mode command, is what the user calls (e.g., <kbd>M-x list-processes</kbd>). 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</code> to populate the buffer. </p> <dl> <dt id="tabulated-list-gui-sort-indicator-asc">User Option: <strong>tabulated-list-gui-sort-indicator-asc</strong>
</dt> <dd>
<p>This variable specifies the character to be used on GUI frames as an indication that the column is sorted in the ascending order. </p> <p>Whenever you change the sort direction in Tabulated List buffers, this indicator toggles between ascending (“asc”) and descending (“desc”). </p>
</dd>
</dl> <dl> <dt id="tabulated-list-gui-sort-indicator-desc">User Option: <strong>tabulated-list-gui-sort-indicator-desc</strong>
</dt> <dd><p>Like <code>tabulated-list-gui-sort-indicator-asc</code>, but used when the column is sorted in the descending order. </p></dd>
</dl> <dl> <dt id="tabulated-list-tty-sort-indicator-asc">User Option: <strong>tabulated-list-tty-sort-indicator-asc</strong>
</dt> <dd><p>Like <code>tabulated-list-gui-sort-indicator-asc</code>, but used for text-mode frames. </p></dd>
</dl> <dl> <dt id="tabulated-list-tty-sort-indicator-desc">User Option: <strong>tabulated-list-tty-sort-indicator-desc</strong>
</dt> <dd><p>Like <code>tabulated-list-tty-sort-indicator-asc</code>, but used when the column is sorted in the descending order. </p></dd>
</dl> <dl> <dt id="tabulated-list-format">Variable: <strong>tabulated-list-format</strong>
</dt> <dd>
<p>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>
<var>width</var> <var>sort</var>)</code>, where </p> <ul> <li> <var>name</var> is the column’s name (a string). </li>
<li> <var>width</var> 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. </li>
<li> <var>sort</var> specifies how to sort entries by the column. If <code>nil</code>, the column cannot be used for sorting. If <code>t</code>, the column is sorted by comparing string values. Otherwise, this should be a predicate function for <code>sort</code> (see <a href="rearrangement">Rearrangement</a>), which accepts two arguments with the same form as the elements of <code>tabulated-list-entries</code> (see below). </li>
</ul> </dd>
</dl> <dl> <dt id="tabulated-list-entries">Variable: <strong>tabulated-list-entries</strong>
</dt> <dd>
<p>This buffer-local variable specifies the entries displayed in the Tabulated List buffer. Its value should be either a list, or a function. </p> <p>If the value is a list, each list element corresponds to one entry, and should have the form <code>(<var>id</var> <var>contents</var>)</code>, where </p> <ul> <li> <var>id</var> is either <code>nil</code>, 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</code>. </li>
<li> <var>contents</var> is a vector with the same number of elements as <code>tabulated-list-format</code>. Each vector element is either a string, which is inserted into the buffer as-is, or a list <code>(<var>label</var>
. <var>properties</var>)</code>, which means to insert a text button by calling <code>insert-text-button</code> with <var>label</var> and <var>properties</var> as arguments (see <a href="making-buttons">Making Buttons</a>). <p>There should be no newlines in any of these strings. </p>
</li>
</ul> <p>Otherwise, the value should be a function which returns a list of the above form when called with no arguments. </p>
</dd>
</dl> <dl> <dt id="tabulated-list-revert-hook">Variable: <strong>tabulated-list-revert-hook</strong>
</dt> <dd><p>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</code>. </p></dd>
</dl> <dl> <dt id="tabulated-list-printer">Variable: <strong>tabulated-list-printer</strong>
</dt> <dd><p>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</var> and <var>contents</var>, having the same meanings as in <code>tabulated-list-entries</code>. 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. </p></dd>
</dl> <dl> <dt id="tabulated-list-sort-key">Variable: <strong>tabulated-list-sort-key</strong>
</dt> <dd><p>The value of this variable specifies the current sort key for the Tabulated List buffer. If it is <code>nil</code>, no sorting is done. Otherwise, it should have the form <code>(<var>name</var> . <var>flip</var>)</code>, where <var>name</var> is a string matching one of the column names in <code>tabulated-list-format</code>, and <var>flip</var>, if non-<code>nil</code>, means to invert the sort order. </p></dd>
</dl> <dl> <dt id="tabulated-list-init-header">Function: <strong>tabulated-list-init-header</strong>
</dt> <dd>
<p>This function computes and sets <code>header-line-format</code> for the Tabulated List buffer (see <a href="header-lines">Header Lines</a>), and assigns a keymap to the header line to allow sorting entries by clicking on column headers. </p> <p>Modes derived from Tabulated List mode should call this after setting the above variables (in particular, only after setting <code>tabulated-list-format</code>). </p>
</dd>
</dl> <dl> <dt id="tabulated-list-print">Function: <strong>tabulated-list-print</strong> <em>&amp;optional remember-pos update</em>
</dt> <dd>
<p>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</code> according to <code>tabulated-list-sort-key</code>, then calls the function specified by <code>tabulated-list-printer</code> to insert each entry. </p> <p>If the optional argument <var>remember-pos</var> is non-<code>nil</code>, this function looks for the <var>id</var> element on the current line, if any, and tries to move to that entry after all the entries are (re)inserted. </p> <p>If the optional argument <var>update</var> is non-<code>nil</code>, 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 <code>tabulated-list-put-tag</code> will not be removed from entries that haven’t changed (normally all tags are removed). </p>
</dd>
</dl> <dl> <dt id="tabulated-list-delete-entry">Function: <strong>tabulated-list-delete-entry</strong>
</dt> <dd>
<p>This function deletes the entry at point. </p> <p>It returns a list <code>(<var>id</var> <var>cols</var>)</code>, where <var>id</var> is the ID of the deleted entry and <var>cols</var> is a vector of its column descriptors. It moves point to the beginning of the current line. It returns <code>nil</code> if there is no entry at point. </p> <p>Note that this function only changes the buffer contents; it does not alter <code>tabulated-list-entries</code>. </p>
</dd>
</dl> <dl> <dt id="tabulated-list-get-id">Function: <strong>tabulated-list-get-id</strong> <em>&amp;optional pos</em>
</dt> <dd><p>This <code>defsubst</code> returns the ID object from <code>tabulated-list-entries</code> (if that is a list) or from the list returned by <code>tabulated-list-entries</code> (if it is a function). If omitted or <code>nil</code>, <var>pos</var> defaults to point. </p></dd>
</dl> <dl> <dt id="tabulated-list-get-entry">Function: <strong>tabulated-list-get-entry</strong> <em>&amp;optional pos</em>
</dt> <dd><p>This <code>defsubst</code> returns the entry object from <code>tabulated-list-entries</code> (if that is a list) or from the list returned by <code>tabulated-list-entries</code> (if it is a function). This will be a vector for the ID at <var>pos</var>. If there is no entry at <var>pos</var>, then the function returns <code>nil</code>. </p></dd>
</dl>  <dl> <dt id="tabulated-list-header-overlay-p">Function: <strong>tabulated-list-header-overlay-p</strong> <em>&amp;optional POS</em>
</dt> <dd><p>This <code>defsubst</code> returns non-nil if there is a fake header at <var>pos</var>. A fake header is used if <code>tabulated-list-use-header-line</code> is <code>nil</code> to put the column names at the beginning of the buffer. If omitted or <code>nil</code>, <var>pos</var> defaults to <code>point-min</code>. </p></dd>
</dl>  <dl> <dt id="tabulated-list-put-tag">Function: <strong>tabulated-list-put-tag</strong> <em>tag &amp;optional advance</em>
</dt> <dd><p>This function puts <var>tag</var> in the padding area of the current line. The padding area can be empty space at the beginning of the line, the width of which is governed by <code>tabulated-list-padding</code>. <var>tag</var> should be a string, with a length less than or equal to <code>tabulated-list-padding</code>. If <var>advance</var> is non-nil, this function advances point by one line. </p></dd>
</dl> <dl> <dt id="tabulated-list-clear-all-tags">Function: <strong>tabulated-list-clear-all-tags</strong>
</dt> <dd><p>This function clears all tags from the padding area in the current buffer. </p></dd>
</dl> <dl> <dt id="tabulated-list-set-col">Function: <strong>tabulated-list-set-col</strong> <em>col desc &amp;optional change-entry-data</em>
</dt> <dd>
<p>This function changes the tabulated list entry at point, setting <var>col</var> to <var>desc</var>. <var>col</var> is the column number to change, or the name of the column to change. <var>desc</var> is the new column descriptor, which is inserted via <code>tabulated-list-print-col</code>. </p> <p>If <var>change-entry-data</var> is non-nil, this function modifies the underlying data (usually the column descriptor in the list <code>tabulated-list-entries</code>) by setting the column descriptor of the vector to <code>desc</code>. </p>
</dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Tabulated-List-Mode.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Tabulated-List-Mode.html</a>
  </p>
</div>