neurocyte/flow-website
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Links between developer docs

Browse source
This commit is contained in:
Igor Támara 2025-10-29 16:43:37 -05:00 • committed by CJ van den Berg
parent 5eedc17542
commit e837a66b97
10 changed files with 318 additions and 243 deletions
Download patch file Download diff file Expand all files Collapse all files

82
content/docs/architecture/palette.smd
View file

@ -5,35 +5,30 @@
.layout = "tutorial.shtml",
.draft = false,
.custom = {
.githubedit = "docs/architecture/palette.md",
.prevurl = "docs/minimode",
.prevtext = "Mini modes",
.topurl = "docs/architecture",
.toptext = "Architecture",
.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.
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.
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.
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
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
@ -43,11 +38,12 @@ Palettes are under `tui/overlay` and use the facilities offered by
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.
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:
@ -59,10 +55,11 @@ 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.
`load_entries` is in charge of populating the visible entries, each one
with an index.
```zig
pub fn load_entries(palette: *Type) !usize
@ -70,10 +67,10 @@ 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.
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 {
@ -86,25 +83,36 @@ selected item is
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:
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 functions are
ready, it's time to make the palette available as a command.
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 as 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).
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)