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

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 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.