View Source Kino.Control (Kino v0.10.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: "client1"}}
#=> {:hello, %{origin: "client1"}}

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.

Merges several inputs and controls into a single stream of events.

Subscribes the calling process to control or input events.

Same as stream/1, but attaches custom tag to every stream item.

Unsubscribes the calling process from control or input events.

Link to this section Types

@type event_source() :: t() | Kino.Input.t() | interval() | Kino.JS.Live.t()
@opaque interval()
@opaque t()

Link to this section Functions

@spec button(String.t()) :: t()

Creates a new button.

Link to this function

form(fields, opts \\ [])

View Source
@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 to false

  • :reset_on_submit - a list of fields to revert to their default values once the form is submitted. Use true 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: "client1",
#=>     type: :submit
#=>   }}
#=> {:chat_form,
#=>   %{
#=>     data: %{message: "Hey!", name: "Jake"},
#=>     origin: "client2",
#=>     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: "client1", type: :status}
#=> {:keyboard, %{key: "o", origin: "client1", type: :keydown}}
#=> {:keyboard, %{key: "k", origin: "client1", type: :keydown}}
#=> {:keyboard, %{key: "o", origin: "client1", type: :keyup}}
#=> {:keyboard, %{key: "k", origin: "client1", type: :keyup}}
@spec stream(event_source() | [event_source()]) :: Enumerable.t()

Merges several inputs and controls into a single stream of events.

It accepts a single source or a list of sources, where each source is either of:

  • %Kino.Control{} - emitting value on relevant interaction

  • %Kino.Input{} - emitting value on value change

  • %Kino.JS.Live{} - emitting value programmatically

  • interval/0 - emitting value periodically, see interval/1

You can then consume the stream to access its events. The stream is typically consumed via Kino.listen/2.

example

Example

button = Kino.Control.button("Hello")
input = Kino.Input.checkbox("Check")
interval = Kino.Control.interval(1000)

[button, input, interval]
|> Kino.Control.stream()
|> Kino.listen(fn event ->
  IO.inspect(event)
end)
#=> %{type: :interval, iteration: 0}
#=> %{origin: "client1", type: :click}
#=> %{origin: "client1", type: :change, value: true}
@spec subscribe(t() | Kino.Input.t(), term()) :: :ok

Subscribes the calling process to control or input events.

This is an alternative API to stream/1, such that event messages are consumed via process messages instead of streams.

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(keyword(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")

[hello: button, check: input]
|> Kino.Control.tagged_stream()
|> Kino.listen(fn event ->
  IO.inspect(event)
end)
#=> {:hello, %{origin: "client1", type: :click}}
#=> {:check, %{origin: "client1", type: :change, value: true}}
@spec unsubscribe(t() | Kino.Input.t()) :: :ok

Unsubscribes the calling process from control or input events.