---

3 Making A Table

The interface function for making (and optionally inserting a table into a buffer) is make-vtable. It returns a table object.

The keyword parameters are described below.

There are many callback interface functions possible in make-vtable, and many of them take a object argument (an object from the :objects list), a column index argument (an integer starting at zero), and a table argument (the object returned by make-vtable).

:objects

This is a list of objects to be displayed. It should either be a list of strings (which will then be displayed as a single-column table), or a list where each element is a sequence containing a mixture of strings, numbers, and other objects that can be displayed “simply”.

In the latter case, if :columns is non-nil and there’s more elements in the sequence than there is in :columns, only the :columns first elements are displayed.

:objects-function

It’s often convenient to generate the objects dynamically (for instance, to make reversion work automatically). In that case, this should be a function (which will be called with no arguments), and should return a value as accepted as an :objects list.

:columns

This is a list where each element is either a string (the column name), a plist of keyword/values (to make a vtable-column object), or a full vtable-column object. A vtable-column object has the following slots:

name

The name of the column.

width

The width of the column. This is either a number (the width of that many ‘x’ characters in the table’s face), or a string on the form ‘Xex’, where x is a number of ‘x’ characters, or a string on the form ‘Xpx’ (denoting a number of pixels), or a string on the form ‘X%’ (a percentage of the window’s width).

min-width

This uses the same format as width, but specifies the minimum width (and overrides width if width is smaller than this.

max-width

This uses the same format as width, but specifies the maximum width (and overrides width if width is larger than this. min-width/max-width can be useful if width is given as a percentage of the window width, and you want to ensure that the column doesn’t grow pointlessly large or unreadably narrow.

primary

Whether this is the primary column—this will be used for initial sorting. This should be either ascend or descend to say in which order the table should be sorted.

getter

If present, this function will be called to return the column value.

Function: column-getter object table ¶

It’s called with two parameters: the object and the table.

formatter

If present, this function will be called to format the value.

Function: column-formatter value ¶

It’s called with one parameter: the column value.

displayer

If present, this function will be called to prepare the formatted value for display. This function should return a string with the table face applied, and also limit the width of the string to the display width.

Function: column-displayer fvalue max-width table ¶

fvalue is the formatted value; max-width is the maximum width (in pixels), and table is the table.

align

Should be either right or left.

:getter

If given, this is a function that should return the values to use in the table, and will be called once for each element in the table (unless overridden by a column getter function).

Function: getter object index table ¶

For a simple object (like a sequence), this function will typically just return the element corresponding to the column index (zero-based), but the function can do any computation it wants. If it’s more convenient to write the function based on column names rather than the column index, the vtable-column function can be used to map from index to name.

:formatter

If present, this is a function that should format the value, and it will be called on all values in the table (unless overridden by a column formatter).

Function: formatter value index table ¶

This function is called with three parameters: the value (as returned by the getter); the column index, and the table. It can return any value.

This can be used to (for instance) format numbers in a human-readable form.

:displayer

Before displaying an element, it’s passed to the displaying function (if any).

Function: displayer fvalue index max-width table ¶

This is called with four arguments: the formatted value of the element (as returned by the formatter function); the column index; the display width (in pixels); and the table.

This function should return a string with the table face applied, and truncated to the display width.

This can be used to (for instance) change the size of images that are displayed in the table.

:use-header-line

If non-nil (which is the default), display the column names on the header line. This is the most common use case, but if there’s other text in the buffer before the table, or there are several tables in the same buffer, then this should be nil.

:face

The face to be used. This defaults to vtable. This face doesn’t override the faces in the data, or the faces supplied by the getter and formatter functions.

:row-colors

If present, this should be a list of color names to be used as the background color on the rows. If there are fewer colors here than there are rows, the rows will be repeated. The most common use case here is to have alternating background colors on the rows, so this would usually be a list of two colors. This can also be a list of faces to be used.

:column-colors

If present, this should be a list of color names to be used as the background color on the columns. If there are fewer colors here than there are columns, the colors will be repeated. The most common use case here is to have alternating background colors on the columns, so this would usually be a list of two colors. This can also be a list of faces to be used. If both :row-colors and :column-colors is present, the colors will be “blended” to produce the final colors in the table.

:actions

This uses the same syntax as define-keymap, but doesn’t refer to commands directly. Instead each key is bound to a command that picks out the current object, and then calls the function specified with that as the argument.

:keymap

This is a keymap used on the table. The commands here are called as usual, and if they’re supposed to work on the object displayed on the current line, they can use the vtable-current-object function (see Interface Functions) to determine what that object is.

:separator-width

The width of the blank space between columns.

:divider-width

:divider

You can have a divider inserted between the columns. This can either be specified by using :divider, which should be a string to be displayed between the columns, or :divider-width, which specifies the width of the space to be used as the divider.

:sort-by

This should be a list of tuples, and specifies how the table is to be sorted. Each tuple should consist of an integer (the column index) and either ascend or descend.

The table is first sorted by the first element in this list, and then the next, until the end is reached.

:ellipsis

By default, when shortening displayed values, an ellipsis will be shown. If this is nil, no ellipsis is shown. (The text to use as the ellipsis is determined by the truncate-string-ellipsis function.)

:insert

By default, make-vtable will insert the table at point. If this is nil, nothing is inserted, but the vtable object is returned, and you can insert it later with the vtable-insert function.

make-table returns a vtable object. You can access the slots in that object by using accessor functions that have names based on the keywords described above. For instance, to access the face, use vtable-face.