118 lines
No EOL
3.7 KiB
Text
118 lines
No EOL
3.7 KiB
Text
---
|
|
.title = "Palettes",
|
|
.date = @date("2025-10-20T00:00:00"),
|
|
.author = "Igor Támara",
|
|
.layout = "tutorial.shtml",
|
|
.draft = false,
|
|
.custom = {
|
|
.githubedit = "docs/architecture/palette.smd",
|
|
.codepath ="src/tui/mode/overlay/clipboard_palette.zig",
|
|
},
|
|
---
|
|
|
|
Palettes are overlay menus 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.
|
|
|
|
Examples of palettes are command_palette, clipboard_palette, they all
|
|
are based on palette.zig that does 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 keyboards and execute the beforehand mentioned
|
|
actions in response.
|
|
|
|
To get the most of this section, it's recommended to have read about
|
|
[commands](/docs/architecture/command), and optionally
|
|
[minimodes](/docs/architecture/minimode).
|
|
|
|
[]($section.id("anatomy"))
|
|
## Defining the palette
|
|
|
|
Palettes are under `tui/overlay` and use the facilities offered by
|
|
`palette.zig` to perform all the operations.
|
|
|
|
1. Defining the list of elements
|
|
2. Filtering the elements
|
|
3. Perform an action with the selected element
|
|
|
|
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.
|
|
|
|
[]($section.id("basic"))
|
|
### Fields
|
|
|
|
Basic fields that give hints to the user and need to be set are:
|
|
|
|
```zig
|
|
pub const label = "Clipboard history";
|
|
pub const name = " clipboard";
|
|
pub const description = "clipboard";
|
|
pub const icon = " ";
|
|
```
|
|
|
|
[]($section.id("entries"))
|
|
### Defining the list of elements in the palette
|
|
|
|
`load_entries` is in charge of populating the visible entries, each one
|
|
with an index.
|
|
|
|
```zig
|
|
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` used when the user writes in the input to filter out
|
|
options.
|
|
|
|
```zig
|
|
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
|
|
|
|
```zig
|
|
try palette.menu.add_item_with_handler(value.written(), select);
|
|
```
|
|
|
|
[]($section.id("select"))
|
|
### Acting on selection
|
|
|
|
When the selection happens, it is time to invoke the command with the
|
|
selection and the palette needs to be closed. Those actions will be
|
|
handled inside `select`, whose signature is:
|
|
|
|
```zig
|
|
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
|
|
are ready, it's time to make the palette available as a command.
|
|
|
|
[]($section.id("register"))
|
|
## Registering the palette
|
|
|
|
Commands that open the palette are defined in `tui.zig` in a similar way
|
|
it is done with [minimodes](/docs/architecture/minimode). We have got
|
|
you covered if in doubt about
|
|
[how to create a command](/docs/architecture/command).
|
|
|
|
To view a complete implementation of a palette, take a look at
|
|
[clipboard history palette commit](https://github.com/neurocyte/flow/commit/634a18cb5685a3c3fcfc08301306e628d33c3256)
|
|
|
|
[]($section.id("next"))
|
|
## Next steps
|
|
|
|
* [Minimodes](/docs/architecture/minimode)
|
|
* [Editor topics](/docs/architecture/editor)
|
|
* [On commands](/docs/architecture/command)
|
|
* [Architecture](/docs/architecture) |