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, }
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
- 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
- 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”.
- default_width
-
The default width for the field.
If not specified, the width defaults to 6 characters.
- 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 atinfo.panel
and the panel’s directory atinfo.dir
(which is faster than accessinginfo.panel.dir
).
Sorting
- 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:
- 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.