View Source Kino.Control (Kino v0.6.0)
Various widgets for user interactions.
Each widget is a UI control element that the user interacts with, consequently producing an event stream.
Those widgets are often useful paired with Kino.Frame
for
presenting content that changes upon user interactions.
examples
Examples
First, create a control and make sure it is rendered,
either by placing it at the end of a code cell or by
explicitly rendering it with Kino.render/1
.
button = Kino.Control.button("Hello")
Next, to receive events from the control, a process needs to subscribe to it and specify pick a name to distinguish the events.
Kino.Control.subscribe(button, :hello)
As the user interacts with the button, the subscribed process receives corresponding events.
IEx.Helpers.flush()
#=> {:hello, %{origin: #PID<10895.9854.0>}}
#=> {:hello, %{origin: #PID<10895.9854.0>}}
Link to this section Summary
Functions
Creates a new button.
Creates a new form.
Returns a new interval event source.
Creates a new keyboard control.
Returns a Stream
of control events.
Subscribes the given function to events from one or more event sources.
A stateful version of stream/1
.
Subscribes the calling process to control or input events.
Same as stream/1
, but attaches custom tag to every stream item.
Same as stream/2
, but attaches custom tag to every event.
A stateful version of tagged_stream/2
.
Unsubscribes the calling process from control or input events.
Link to this section Types
Link to this section Functions
Creates a new button.
@spec form([{atom(), Kino.Input.t()}], keyword()) :: t()
Creates a new form.
A form is composed of regular inputs from the Kino.Input
module,
however in a form input values are not synchronized between users.
Consequently, the form is another control for producing user-specific
events.
Either :submit
or :report_changes
must be specified.
options
Options
:submit
- specifies the label to use for the submit button and enables submit events:report_changes
- whether to send new form value whenever any of the input changes. Defaults tofalse
:reset_on_submit
- a list of fields to revert to their default values once the form is submitted. Usetrue
to indicate all fields. Defaults to[]
event-info
Event info
In addition to standard properties, all events include additional properties.
:type
- either:submit
or:change
:data
- a map with field values, matching the field list
examples
Examples
Create a form out of inputs:
form =
Kino.Control.form(
[
name: Kino.Input.text("Name"),
message: Kino.Input.textarea("Message")
],
submit: "Send"
)
Subscribe to events:
Kino.Control.subscribe(form, :chat_form)
As users submit the form the payload is sent:
IEx.Helpers.flush()
#=> {:chat_form,
#=> %{
#=> data: %{message: "Hola", name: "Amy"},
#=> origin: #PID<10905.5195.0>,
#=> type: :submit
#=> }}
#=> {:chat_form,
#=> %{
#=> data: %{message: "Hey!", name: "Jake"},
#=> origin: #PID<10905.5186.0>,
#=> type: :submit
#=> }}
@spec interval(non_neg_integer()) :: interval()
Returns a new interval event source.
This can be used as event source for stream/1
and tagged_stream/1
.
The events are emitted periodically with an increasing value, starting
from 0 and have the form:
%{type: :interval, iteration: non_neg_integer()}
@spec keyboard([:keyup | :keydown | :status]) :: t()
Creates a new keyboard control.
This widget is represented as button that toggles interception mode, in which the given keyboard events are captured.
event-info
Event info
In addition to standard properties, all events include additional properties.
key-events
Key events
:type
- either:keyup
or:keydown
:key
- the value matching the browser KeyboardEvent.key
status-event
Status event
:type
- either:status
:enabled
- whether the keyboard is activated
examples
Examples
Create the widget:
keyboard = Kino.Control.keyboard([:keyup, :keydown, :status])
Subscribe to events:
Kino.Control.subscribe(keyboard, :keyboard)
As the user types events are streamed:
IEx.Helpers.flush()
#=> {:keyboard, %{enabled: true, origin: #PID<10895.9854.0>, type: :status}
#=> {:keyboard, %{key: "o", origin: #PID<10895.9854.0>, type: :keydown}}
#=> {:keyboard, %{key: "k", origin: #PID<10895.9854.0>, type: :keydown}}
#=> {:keyboard, %{key: "o", origin: #PID<10895.9854.0>, type: :keyup}}
#=> {:keyboard, %{key: "k", origin: #PID<10895.9854.0>, type: :keyup}}
@spec stream(event_source() | [event_source()]) :: Enumerable.t()
Returns a Stream
of control events.
This is an alternative API to subscribe/2
, such that event
messages are consume via stream instead of process messages.
It accepts a single source or a list of sources, where each source is either of:
Kino.Control
- emitting value on relevant interactionKino.Input
- emitting value on value change
example
Example
button = Kino.Control.button("Hello")
for event <- Kino.Control.stream(button) do
IO.inspect(event)
end
#=> %{origin: #PID<10895.9854.0>, type: :click}
#=> %{origin: #PID<10895.9854.0>, type: :click}
Or with multiple sources:
button = Kino.Control.button("Hello")
input = Kino.Input.checkbox("Check")
interval = Kino.Control.interval(1000)
for event <- Kino.Control.stream([button, input, interval]) do
IO.inspect(event)
end
#=> %{type: :interval, iteration: 0}
#=> %{origin: #PID<10895.9854.0>, type: :click}
#=> %{origin: #PID<10895.9854.0>, type: :change, value: true}
@spec stream(event_source() | [event_source()], (term() -> any())) :: :ok
Subscribes the given function to events from one or more event sources.
The given function runs asynchronously.
See stream/1
for more details on event sources.
examples
Examples
button = Kino.Control.button("Greet")
Kino.Control.stream(button, fn _event ->
IO.puts("Hello!")
end)
@spec stream(event_source() | [event_source()], state, (term(), state -> state)) :: :ok when state: term()
A stateful version of stream/1
.
examples
Examples
button = Kino.Control.button("Greet")
Kino.Control.stream(button, 0, fn _event, counter ->
new_counter = counter + 1
IO.puts("clicks: #{new_counter}")
new_counter
end)
@spec subscribe(t() | Kino.Input.t(), term()) :: :ok
Subscribes the calling process to control or input events.
The events are sent as {tag, info}
, where info is a map with
event details. In particular, it always includes :origin
, which
is an opaque identifier of the client that triggered the event.
@spec tagged_stream([{atom(), event_source()}]) :: Enumerable.t()
Same as stream/1
, but attaches custom tag to every stream item.
example
Example
button = Kino.Control.button("Hello")
input = Kino.Input.checkbox("Check")
for event <- Kino.Control.tagged_stream([hello: button, check: input]) do
IO.inspect(event)
end
#=> {:hello, %{origin: #PID<10895.9854.0>, type: :click}}
#=> {:check, %{origin: #PID<10895.9854.0>, type: :change, value: true}}
@spec tagged_stream([{tag, event_source()}], ({tag, term()} -> any())) :: :ok when tag: atom()
Same as stream/2
, but attaches custom tag to every event.
example
Example
button = Kino.Control.button("Hello")
input = Kino.Input.checkbox("Check")
Kino.Control.tagged_stream([hello: button, check: input], fn
{:hello, event} -> ...
{:check, event} -> ...
end)
@spec tagged_stream([{tag, event_source()}], state, ({tag, term()}, state -> state)) :: :ok when tag: atom(), state: term()
A stateful version of tagged_stream/2
.
example
Example
up = Kino.Control.button("Up") |> Kino.render()
down = Kino.Control.button("Down") |> Kino.render()
Kino.Control.tagged_stream([up: up, down: down], 0, fn
{:up, _event}, counter ->
new_counter = counter + 1
IO.puts("counter: #{new_counter}")
new_counter
{:down, _event}, counter ->
new_counter = counter - 1
IO.puts("counter: #{new_counter}")
new_counter
end)
@spec unsubscribe(t() | Kino.Input.t()) :: :ok
Unsubscribes the calling process from control or input events.