State and ids

Note

This page is generated from the doc comments in kiln/ by tools/docgen. Fix the comment, not the page.

At a glance

Id :: clay.ElementId
Interaction :: struct {...}
Pointer_Event :: struct {...}
Pointer_Event_Kind :: enum {...}
scope :: proc{scope_int, scope_string}
after :: proc(name: string, seconds: f64) -> bool
anim :: proc(eid: Id, slot: u32, target: f32, speed: f32 = 0, from: Maybe(f32) = nil) -> f32
clicked :: proc() -> bool
every :: proc(name: string, seconds: f64) -> bool
hide :: proc()
hovered :: proc() -> bool
id :: proc(label: string) -> Id
id_indexed :: proc(label: string, index: int) -> Id
interact :: proc(eid: Id, disabled := false) -> (s: Interaction)
is_shown :: proc(name: string) -> bool
last_id :: proc() -> Id
pointer_events :: proc(eid: Id, wheel := false) -> []Pointer_Event
reset_timer :: proc(name: string)
scope_int :: proc(key: int) -> bool
scope_string :: proc(key: string) -> bool
set_last :: proc(eid: Id, state := Interaction{}, submitted := false)
show :: proc(name: string)
sub_id :: proc(parent: Id, name: string, index := 0) -> Id
submitted :: proc() -> bool
widget_state :: proc(eid: Id, $T: typeid, destroy: proc(_: ^T) = nil) -> (state: ^T, created: bool)

Types

Id

Id :: clay.ElementId

Source: kiln/state.odin:13

Interaction

Interaction :: struct {
  hovered:       bool, // the pointer is over the element
  pressed:       bool, // the left button went down on the element and is down over it
  held:          bool, // the left button went down on the element and is still down (anywhere)
  clicked:       bool, // released over the element in this frame
  right_clicked: bool, // the right button went down on the element in this frame
  started:       bool, // the left button went down on the element in this frame (a drag starts)
  released:      bool, // the left button that went down on the element was released in this frame, anywhere
  disabled:      bool,
  pos:           [2]f32, // pointer position in pixels, relative to the element's top left corner (as laid out in the previous frame)
}

Pointer state of an element in the current frame, returned by interact.

Field	Type	Notes
hovered	bool	the pointer is over the element
pressed	bool	the left button went down on the element and is down over it
held	bool	the left button went down on the element and is still down (anywhere)
clicked	bool	released over the element in this frame
right_clicked	bool	the right button went down on the element in this frame
started	bool	the left button went down on the element in this frame (a drag starts)
released	bool	the left button that went down on the element was released in this frame, anywhere
disabled	bool
pos	[2]f32	pointer position in pixels, relative to the element’s top left corner (as laid out in the previous frame)

Source: kiln/state.odin:120

Pointer_Event

Pointer_Event :: struct {
  kind:      Pointer_Event_Kind,
  button:    MouseButton, // Press and Release
  pos:       [2]f32, // pixels, relative to the element's top left corner (window for the backend)
  wheel:     [2]f32, // Wheel: pixels to scroll
  pressure:  f32, // 0..1; 1 for devices without pressure, like a mouse
  modifiers: bit_set[Modifier],
  time:      f64, // seconds since the app started
}

One thing the pointer did, in the order it happened. Several moves in one frame are the pointer’s path between frames, if the platform reports it.

Field	Type	Notes
kind	Pointer_Event_Kind
button	MouseButton	Press and Release
pos	[2]f32	pixels, relative to the element’s top left corner (window for the backend)
wheel	[2]f32	Wheel: pixels to scroll
pressure	f32	0..1; 1 for devices without pressure, like a mouse
modifiers	bit_set[Modifier]
time	f64	seconds since the app started

Source: kiln/state.odin:211

Pointer_Event_Kind

Pointer_Event_Kind :: enum {
  Move,
  Press,
  Release,
  Wheel,
}

Values: .Move, .Press, .Release, .Wheel

Source: kiln/state.odin:202

Procedure groups

scope

scope :: proc{scope_int, scope_string}

Opens an id scope: elements inside get ids that depend on key instead of their position. Use it in loops over data that can change, so the UI state of an item follows the item:

for p in m.people {
    if kiln.scope(p.id) { ... }
}

Calls one of these, depending on the argument types:

• scope_int proc(key: int) -> bool
• scope_string proc(key: string) -> bool

Source: kiln/state.odin:88

Procedures

after

after :: proc(name: string, seconds: f64) -> bool

True once, seconds after the first call (while it is called in every frame).

Argument	Type	Default
name	string	required
seconds	f64	required

Returns	Type
#0	bool

Source: kiln/state.odin:454

anim

anim :: proc(eid: Id, slot: u32, target: f32, speed: f32 = 0, from: Maybe(f32) = nil) -> f32

Moves the value stored for (id, slot) exponentially towards target and returns it. slot lets one widget animate several values, speed is the rate per second (0 = the theme’s anim_speed). The first value of a new tween is target, or from if given (e.g. from = 0 for things that fade in when they appear).

Argument	Type	Default
eid	Id	required
slot	u32	required
target	f32	required
speed	f32	0
from	Maybe(f32)	nil

Returns	Type
#0	f32

Source: kiln/state.odin:344

clicked

clicked :: proc() -> bool

True if the last widget or container was clicked in this frame.

Returns	Type
#0	bool

Source: kiln/state.odin:308

every

every :: proc(name: string, seconds: f64) -> bool

True once every seconds (the first time seconds after the first call) while it is called in every frame. Timers are keyed by name like dialogs, not by position:

if kiln.every("refresh", 300) {append(out, Refresh{})}

Argument	Type	Default
name	string	required
seconds	f64	required

Returns	Type
#0	bool

Source: kiln/state.odin:445

hide

hide :: proc()

Hides the shown dialog or drawer.

Source: kiln/state.odin:407

hovered

hovered :: proc() -> bool

True if the pointer is over the last widget or container.

Returns	Type
#0	bool

Source: kiln/state.odin:313

id

id :: proc(label: string) -> Id

The id of an element labeled label in the current scope. The n-th use of the same label in a scope gets its own id, so equal labels never clash.

Argument	Type	Default
label	string	required

Returns	Type
#0	Id

Source: kiln/state.odin:39

id_indexed

id_indexed :: proc(label: string, index: int) -> Id

Like id, for the index-th element of a kind (list rows, tabs, …).

Argument	Type	Default
label	string	required
index	int	required

Returns	Type
#0	Id

Source: kiln/state.odin:44

interact

interact :: proc(eid: Id, disabled := false) -> (s: Interaction)

Tracks the pointer for an element. Call it once per frame before declaring the element. A press goes to the topmost interactive element under the pointer, so a button inside a clickable list item takes the click and the item does not. Disabled elements never react.

Argument	Type	Default
eid	Id	required
disabled	bool	false

Returns	Type
s	Interaction

Source: kiln/state.odin:142

is_shown

is_shown :: proc(name: string) -> bool

Argument	Type	Default
name	string	required

Returns	Type
#0	bool

Source: kiln/state.odin:411

last_id

last_id :: proc() -> Id

The id of the last widget or container, e.g. to attach custom floating elements to it.

Returns	Type
#0	Id

Source: kiln/state.odin:323

pointer_events

pointer_events :: proc(eid: Id, wheel := false) -> []Pointer_Event

The pointer events of this frame that belong to an element: all of them while a press that started on it goes on (even outside of it), otherwise those over it while it is the topmost interactive element. Call interact for the element before, every frame. With wheel, the element takes the mouse wheel: scroll containers around it do not scroll while the pointer is over it. The events live until the end of the frame.

for e in kiln.pointer_events(eid) {
    if e.kind == .Move && s.held {append(&points, e.pos)}
}

Argument	Type	Default
eid	Id	required
wheel	bool	false

Returns	Type
#0	[]Pointer_Event

Source: kiln/state.odin:237

reset_timer

reset_timer :: proc(name: string)

Starts the timer name over.

Argument	Type	Default
name	string	required

Source: kiln/state.odin:462

scope_int

scope_int :: proc(key: int) -> bool

Argument	Type	Default
key	int	required

Returns	Type
#0	bool

Source: kiln/state.odin:94

scope_string

scope_string :: proc(key: string) -> bool

Argument	Type	Default
key	string	required

Returns	Type
#0	bool

Source: kiln/state.odin:100

set_last

set_last :: proc(eid: Id, state := Interaction{}, submitted := false)

Makes a custom widget the last item, so clicked, hovered, submitted, tooltip and context_menu after it refer to it. Pass the Interaction from interact.

Argument	Type	Default
eid	Id	required
state	Interaction	Interaction{}
submitted	bool	false

Source: kiln/state.odin:303

show

show :: proc(name: string)

Shows the dialog or drawer with this name (replacing the one that is shown).

Argument	Type	Default
name	string	required

Source: kiln/state.odin:401

sub_id

sub_id :: proc(parent: Id, name: string, index := 0) -> Id

Id of a part of a widget (list entry, segment, popup, …), derived from the widget’s id.

Argument	Type	Default
parent	Id	required
name	string	required
index	int	0

Returns	Type
#0	Id

Source: kiln/state.odin:78

submitted

submitted :: proc() -> bool

True if Enter was pressed in the last text field in this frame.

Returns	Type
#0	bool

Source: kiln/state.odin:318

widget_state

widget_state :: proc(eid: Id, $T: typeid, destroy: proc(_: ^T) = nil) -> (state: ^T, created: bool)

UI state of a custom widget that kiln keeps between frames, one T per element id (a drag in progress, a scroll position, a cache). It starts zeroed (created is true then) and is freed when the widget was not shown for a while; destroy frees what T owns:

Draft :: struct {points: [dynamic][2]f32}
draft, _ := kiln.widget_state(eid, Draft, proc(d: ^Draft) {delete(d.points)})

Argument	Type	Default
eid	Id	required
$T	typeid	required
destroy	proc(_: ^T)	nil

Returns	Type
state	^T
created	bool

Source: kiln/state.odin:487