Module fields

Fields are the columns shown in the filemanager’s panels.

You can create your own fields via Lua, as explained in depth in the user guide.

To create a field you pass a table describing it to ui.Panel.register_field:

ui.Panel.register_field {
  id = "upname",
  title = N"Uppercased name",
  render = function(filename, ...)
    return filename:upper()
  end,
}

The documentation herein describes the keys in this table.

The fields module itself exposes no functions to the end user.

A field may serve either, or both, of two roles: showing some data (“rendering”), or sorting by it. The documentation herein is sectioned into these two roles.

As a quick reference, here’s a field that uses all the definition keys:

ui.Panel.register_field {
  id = "upname",
  title = N"U&ppercased name",  -- Note: "N" instead of "T".

  -- Rendering

  render = function (filename, stat, width, info)
    return filename:upper()
  end,
  default_align = "center or left~",
  default_width = 20,
  expand = true,

  -- Sorting

  sort = function (filename1, stat1, filename2, stat2, info)
    if filename1 > filename2 then
      return 1
    elseif filename1 < filename2 then
      return -1
    else
      return 0
    end
  end,
  sort_indicator = N"sort|up",  -- Note: "N" instead of "Q".
}

Mandatory keys

id A string uniquely identifying the field.
title A human readable name for this field.

Rendering

default_align The default alignment for the field.
default_width The default width for the field.
expands Whether to allocate any extra space in the panel to the field.
render A function to render a field.

Sorting

sort A function to compare two files.
sort_indicator A short string identifying the sort.


Mandatory keys

The following are keys that you must define.
id
A string uniquely identifying the field.

This ID is used to refer to this field. For example, using MC’s “Listing mode” dialog you embed this ID in the “User defined” format string.

title
A human readable name for this field.

It’s displayed as the column header near the top of the panel, for renderable fields.

You may designate a letter in it as a hot key by preceding it with “&”. This allows quick activation of sortable fields, in the “Sort order” dialog.

Since typically little visual space is allotted to this string (it’s cropped to the width of the column), make sure to include the gist of the title in the first word already.

Rendering

If you want your field to be visible —that is, if it renders some data— you need only implement the render function. The other, optional keys tweak the field’s appearance.
default_align
The default alignment for the field.

Either “left”, “right”, or “center or left”. Append “~” (e.g., “left~”) to trim the contents if it’s too long. See tty.text_align for details. If not specified, the alignment defaults to “left”.

The user may override this alignment by using a special syntax in the format string.

default_width
The default width for the field.

If not specified, the width defaults to 6 characters.

The user may override this width by using the “field_id:WIDTH” syntax in the format string.

expands
Whether to allocate any extra space in the panel to the field.
render

A function to render a field.

The string (or number) this function returns will be shown in the panel. (Returning nothing, or nil, is like returning an empty string.)

The arguments this function gets:

  • The file’s basename.
  • The file’s stat,
  • The field’s width on the screen.
  • A parcel, info, with the panel at info.panel and the panel’s directory at info.dir (which is faster than accessing info.panel.dir).

Sorting

If you want your field to be sortable you need only set the sort key.
sort
A function to compare two files.

It should return a positive number, zero, or negative number, depending on which of the two files is greater.

Or, instead of providing your own function, you can “borrow” a sort of a built-in field by putting its ID here (one of: “name”, “version”, “extension”, “size”, “mtime”, “atime”, “ctime”, “inode”, “unsorted”).

The arguments this function gets:

  • The 1st file’s basename.
  • The 1st file’s stat.
  • The 2nd file’s basename.
  • The 2nd file’s stat.
  • A parcel, info, described earlier.

At the time of this writing, sorting isn’t fully implemented: directories and normal files will be mixed, and “reverse” sort isn’t supported.

sort_indicator
A short string identifying the sort. It will be displayed at the panel’s top-left corner to remind the user of the active sort field.
generated by LDoc 1.4.3 Last updated 2016-08-23 17:29:40