Palettes are overlay menus with auto complete that allow to select an item from the presented list, applying a command with the selected element, optionally deleting the selected item; it’s possible to close the palette without selecting anything(a.k.a. cancel), filter the elements, and having special elements that trigger different actions, for example, the task palette.
Examples of palettes are command_palette, clipboard_palette, they all are based on src/tui/mode/overlay/palette.zig doing all the heavy lifting and sets the framework to create new palettes as simple as possible.
Palettes are an special case of [minimode] and for instance a mode, they receive inputs from the keyboard and execute the beforehand mentioned actions in response.
To get the most of this section, it’s recommended to have read about commands, and optionally, minimodes.
Palettes are under tui/overlay and use the facilities offered by palette.zig to perform all the operations.
Note: Palettes are meant to show options and allowing to select the options to execute an action on the given selection. To maintain as readable as possible the code and thus extensible, the data to be used should be prepared previously.
Basic fields that give hints to the user and need to be set are:
pub const label = "Clipboard history";
pub const name = " clipboard";
pub const description = "clipboard";
pub const icon = " ";
load_entries is in charge of populating the visible entries, each one with an index.
pub fn load_entries(palette: *Type) !usize
The index will identify the action to be taken.
When populating with each entry, there must be a relation that links the option chosen with the required action, and this happens in add_menu_entry.
pub fn add_menu_entry(palette: *Type, entry: *Entry, matches: ?[]const usize) !void {
The common line that will be used when registering the event to a selected item is
try palette.menu.add_item_with_handler(value, select);
Which will apply the select function when the value is selected.
When the selection happens, it is time to invoke the command with the selection making sure to close the palette. Those actions will be handled inside select, whose signature is:
fn select(menu: **Type.MenuType, button: *Type.ButtonType, pos: Type.Pos) void {
Other common operations in the palettes can be inspected looking at the source code of the palettes, all of them import palette.zig. Once the palette is ready, it’s time to make the palette available as a command.
Commands that open the palette are defined in tui.zig in a similar way it is done with minimodes. We have got you covered if in doubt about how to create a command.
To view a complete implementation of a palette, take a look at clipboard history palette commit