Documentation
¶
Overview ¶
Package card is AutoDoc's native UI kit for dialog and card plugins (ADR 1792254331): a plugin describes what its card shows as a Page of blocks and controls, and a Card fits it to the size AutoDoc gives, draws it in the theme's colours, and handles the keys, the focus and the pointer.
The controls (Input, Buttons, List, Tree) are values the plugin keeps between draws; the Card asks for the page afresh on every draw, so the screen is always the plugin's state:
type myPlugin struct {
peer *plugin.Peer
card *card.Card
name card.Input
ok card.Buttons
}
func (p *myPlugin) page() card.Page {
return card.Page{
Title: "Hello",
Header: []card.Block{card.Line(card.Title, "Who are you?")},
Body: []card.Block{&p.name},
Buttons: &p.ok,
Keys: "Tab: move · Enter: greet · q: close",
}
}
A plugin forwards its Handler's methods to the Card (Open, Resize, Theme, Focus, Pointer, and Key, keeping the keys the Card does not use). The Card's methods run on the Handler's goroutine only, as the plugin's own state does.
Index ¶
- type Block
- type Buttons
- type Card
- func (c *Card) Attach(h Host, w, hh int, t plugin.Theme)
- func (c *Card) Draw()
- func (c *Card) Focus(focused bool)
- func (c *Card) FocusOn(ctl Control)
- func (c *Card) Focused() Control
- func (c *Card) Key(k plugin.Key) bool
- func (c *Card) Open(p *plugin.Peer, o plugin.Open)
- func (c *Card) Pointer(at plugin.Pointer) bool
- func (c *Card) Resize(w, h int)
- func (c *Card) Theme(t plugin.Theme)
- func (c *Card) Typing() bool
- type Control
- type Host
- type Input
- type List
- type Node
- type Options
- type Page
- type Role
- type Tree
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Block ¶
type Block interface {
// contains filtered or unexported methods
}
Block is one part of a page. Only the kit makes them: Text, Line, Blank, and the controls.
type Buttons ¶
type Buttons struct {
Labels []string
OnPress func(i int) // Enter, Space, or a left press
// contains filtered or unexported fields
}
Buttons are a row of buttons, "[ label ]" each, centred, wrapping as words do.
type Card ¶
type Card struct {
// contains filtered or unexported fields
}
Card is a plugin's card or dialog: its size, theme and focus, the page it shows, and the control with the focus. Its methods run on the Handler's goroutine only.
func (*Card) Draw ¶
func (c *Card) Draw()
Draw sends the card as it stands: the page laid out to the size AutoDoc last gave, and the title when it has changed.
func (*Card) Focus ¶
Focus is plugin.focus: the card took AutoDoc's keys, or gave them back. A modal one ignores it.
func (*Card) Key ¶
Key is a key typed into the card. It returns true when the card used it, and has drawn; false leaves it to the plugin: its own letters, q to close (never while an Input has the keys, where q is text).
any control Tab / Shift+Tab the next / previous control, wrapping; every button of a
Buttons bar is a stop of its own
Input text inserted at the cursor (an IME commit or a paste, whole)
Backspace Delete Left Right Home End edit, move the cursor
Ctrl+U Clear
Up / Down the previous / next control
Enter OnEnter, else the next control
Buttons Left / Right the previous / next button
Enter / Space OnPress
Up / Down the previous / next control
List, Tree Up k, Down j the selection
PageUp Ctrl+U, PageDown Ctrl+D half the card's height
Home g, End G the first, the last row
List Enter OnEnter(Sel); nothing on an empty list
Tree Right l open (OnOpen first); on an open node, its first row
Left h close; on a closed node or a leaf, the row holding it
Enter OnEnter; when it returns false, open or close
func (*Card) Pointer ¶
Pointer is a left press or a wheel step on the card (protocol 6), read against the last draw. It returns true when the card used it, and has drawn.
press, left, on an Input's row focus it
press, left, on a button focus the Buttons on it, and OnPress it
press, left, on a List or Tree row focus it, and select that row
wheel the focused List's or Tree's selection, 3 rows a step
(48 at most); with neither focused, the body scrolls
type Control ¶
type Control interface {
Block
// contains filtered or unexported methods
}
Control is a block that takes focus: *Input, *Buttons, *List, *Tree.
type Input ¶
type Input struct {
Label string // the row above the field; "" for none
Masked bool // each character drawn as •
OnEnter func() // nil: Enter moves to the next control
// contains filtered or unexported fields
}
Input is a one-row text field, under its label. A Masked one draws each character as •, and its value never leaves the rune buffer to be drawn: read it with Runes and Clear it when done.
func (*Input) Runes ¶
Runes is the live buffer, for a passphrase read without a string copy. It is valid until the next key or Clear.
type List ¶
List is Len rows of text, one selected. Item is asked only for the rows in view, so a list of thousands is never drawn whole.
type Node ¶
type Node struct {
Text string
Leaf bool // a row that never opens
Open bool
Children []*Node
Empty string // shown under an open node with no children: "(no tables)"
Value any // the plugin's own
}
Node is one row of a Tree.
type Options ¶
type Options struct {
Modal bool // a modal dialog: always focused, since AutoDoc sends it no plugin.focus
}
Options are a Card's settings.
type Page ¶
type Page struct {
Title string // host.title, sent only when it changes; "" sends nothing
Header []Block // always shown, from the top
Body []Block // under it; scrolls to keep the focused control's row in view
Buttons *Buttons // the bar under the rule; nil for none
Keys string // the hint line, in Dim
Status string // what was done last, in Plain
Problem string // what went wrong, in Problem
}
Page is what the card shows now, built by the plugin on every draw.
type Tree ¶
type Tree struct {
Roots []*Node
OnOpen func(n *Node) bool // a closed node opening; false keeps it closed (a load failed)
OnEnter func(n *Node) bool // false: Enter opens or closes the node, as on one with no handler
// contains filtered or unexported fields
}
Tree is nodes under their parents, open ones showing what they hold. Its selection is a node, kept by identity as nodes open, close and change.
Source Files