Search documentation of Plushie

# Plushie.Widget.Toggler (Plushie v0.7.2)

Copy Markdown View Source

Toggler, on/off switch.

## Props

Name | Type | Default | Description
--- | --- | --- | ---
`is_toggled` | `boolean()` | required | Whether the toggler is on.
`label` | `String.t() | atom()` | `nil` | Text label next to the toggler.
`spacing` | `number()` | `nil` | Space between toggler and label in pixels.
`width` | `:fill | :shrink | {:fill_portion, pos_integer()} | number()` | `nil` | Widget width. Default: shrink.
`size` | `number()` | `nil` | Toggler size in pixels.
`text_size` | `number()` | `nil` | Label text size in pixels.
`font` | `:default | :monospace | String.t() | %Plushie.Type.Font{}` | `nil` | Label font.
`line_height` | `number() | %{relative: number()} | %{absolute: number()}` | `nil` | Label line height.
`shaping` | `:basic | :advanced | :auto` | `nil` | Text shaping strategy.
`wrapping` | `:none | :word | :glyph | :word_or_glyph` | `nil` | Text wrapping mode.
`text_alignment` | `:left | :center | :right | :top | :bottom` | `nil` | Horizontal label alignment.

| `style` | `:default \| :primary \| :secondary \| :success \| :danger \| :warning \| :dark \| :weak \| :rounded_box \| term()` | `nil` | Named style preset. | | `disabled` | `boolean()` | `nil` | When true, cannot be toggled. | | `event_rate` | `integer()` | `nil` | Max events per second for coalescable events. | | `a11y` | `%Plushie.Type.A11y{} \| map() \| keyword()` | `%{role: :switch, label_from: :label}` | Accessibility annotations. |

## Events

Event | Type | Description
--- | --- | ---
`:toggle` | `value: boolean()` | Emitted when toggled. Value is the new boolean state.

## Constructor

    Toggler.new(id, is_toggled)
    Toggler.new(id, is_toggled, opts)

## Summary

### Types

option()
t()

### Functions

a11y(widget, descriptor)

Accessibility annotations.

build(widget)

Converts this widget struct to a `ui_node()` map.

disabled(widget, descriptor)

When true, cannot be toggled.

event_rate(widget, descriptor)

Max events per second for coalescable events.

font(widget, descriptor)

Label font.

is_toggled(widget, descriptor)

Whether the toggler is on.

label(widget, descriptor)

Text label next to the toggler.

line_height(widget, descriptor)

Label line height.

new(id, is_toggled, opts \\ [])

Creates a new widget struct with the given positional args and keyword options.

shaping(widget, descriptor)

Text shaping strategy.

size(widget, descriptor)

Toggler size in pixels.

spacing(widget, descriptor)

Space between toggler and label in pixels.

style(widget, descriptor)

Named style preset.

text_alignment(widget, descriptor)

Horizontal label alignment.

text_size(widget, descriptor)

Label text size in pixels.

toggler(id, opts \\ [])

Creates a `:toggler` widget.

width(widget, descriptor)

Widget width. Default: shrink.

with_options(widget, opts)

Applies keyword options to an existing widget struct.

wrapping(widget, descriptor)

Text wrapping mode.

## Types

# option()

    @type option() ::
      (((((((((((({:label, String.t() | atom()} | {:spacing, number()})
                 | {:width,
                    :fill | :shrink | {:fill_portion, pos_integer()} | number()})
                | {:size, number()})
               | {:text_size, number()})
              | {:font,
                 :default
                 | :monospace
                 | String.t()
                 | %Plushie.Type.Font{
                     family: term(),
                     stretch: term(),
                     style: term(),
                     weight: term()
                   }})
             | {:line_height,
                number() | %{relative: number()} | %{absolute: number()}})
            | {:shaping, :basic | :advanced | :auto})
           | {:wrapping, :none | :word | :glyph | :word_or_glyph})
          | {:text_alignment, :left | :center | :right | :top | :bottom})
         | {:style,
            :default
            | :primary
            | :secondary
            | :success
            | :danger
            | :warning
            | :dark
            | :weak
            | :rounded_box
            | term()})
        | {:disabled, boolean()})
       | {:event_rate, integer()})
      | {:a11y,
         %Plushie.Type.A11y{
           active_descendant: term(),
           busy: term(),
           described_by: term(),
           description: term(),
           disabled: term(),
           error_message: term(),
           expanded: term(),
           has_popup: term(),
           hidden: term(),
           invalid: term(),
           label: term(),
           label_from: term(),
           labelled_by: term(),
           level: term(),
           live: term(),
           mnemonic: term(),
           modal: term(),
           orientation: term(),
           position_in_set: term(),
           radio_group: term(),
           read_only: term(),
           required: term(),
           role: term(),
           selected: term(),
           size_of_set: term(),
           toggled: term(),
           value: term()
         }
         | map()
         | keyword()}

# t()

    @type t() :: %Plushie.Widget.Toggler{
      a11y:
        (%Plushie.Type.A11y{
           active_descendant: term(),
           busy: term(),
           described_by: term(),
           description: term(),
           disabled: term(),
           error_message: term(),
           expanded: term(),
           has_popup: term(),
           hidden: term(),
           invalid: term(),
           label: term(),
           label_from: term(),
           labelled_by: term(),
           level: term(),
           live: term(),
           mnemonic: term(),
           modal: term(),
           orientation: term(),
           position_in_set: term(),
           radio_group: term(),
           read_only: term(),
           required: term(),
           role: term(),
           selected: term(),
           size_of_set: term(),
           toggled: term(),
           value: term()
         }
         | map()
         | keyword())
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      disabled:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      event_rate:
        integer()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      font:
        (:default
         | :monospace
         | String.t()
         | %Plushie.Type.Font{
             family: term(),
             stretch: term(),
             style: term(),
             weight: term()
           })
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      id: String.t(),
      is_toggled:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      label:
        (String.t() | atom())
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      line_height:
        (number() | %{relative: number()} | %{absolute: number()})
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      shaping:
        (:basic | :advanced | :auto)
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      size:
        number()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      spacing:
        number()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      style:
        (:default
         | :primary
         | :secondary
         | :success
         | :danger
         | :warning
         | :dark
         | :weak
         | :rounded_box
         | term())
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      text_alignment:
        (:left | :center | :right | :top | :bottom)
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      text_size:
        number()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      width:
        (:fill | :shrink | {:fill_portion, pos_integer()} | number())
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      wrapping:
        (:none | :word | :glyph | :word_or_glyph)
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil
    }

## Functions

# a11y(widget, descriptor)

    @spec a11y(
      widget :: t(),
      value ::
        (%Plushie.Type.A11y{
           active_descendant: term(),
           busy: term(),
           described_by: term(),
           description: term(),
           disabled: term(),
           error_message: term(),
           expanded: term(),
           has_popup: term(),
           hidden: term(),
           invalid: term(),
           label: term(),
           label_from: term(),
           labelled_by: term(),
           level: term(),
           live: term(),
           mnemonic: term(),
           modal: term(),
           orientation: term(),
           position_in_set: term(),
           radio_group: term(),
           read_only: term(),
           required: term(),
           role: term(),
           selected: term(),
           size_of_set: term(),
           toggled: term(),
           value: term()
         }
         | map()
         | keyword())
        | nil
    ) :: t()

Accessibility annotations.

Accepts `%Plushie.Type.A11y{} | map() | keyword()`.

# build(widget)

    @spec build(widget :: t()) :: Plushie.Widget.ui_node()

Converts this widget struct to a `ui_node()` map.

# disabled(widget, descriptor)

    @spec disabled(widget :: t(), value :: boolean() | nil) :: t()

When true, cannot be toggled.

Accepts `boolean()`.

# event_rate(widget, descriptor)

    @spec event_rate(widget :: t(), value :: integer() | nil) :: t()

Max events per second for coalescable events.

Accepts `integer()`.

# font(widget, descriptor)

    @spec font(
      widget :: t(),
      value ::
        (:default
         | :monospace
         | String.t()
         | %Plushie.Type.Font{
             family: term(),
             stretch: term(),
             style: term(),
             weight: term()
           })
        | nil
    ) :: t()

Label font.

Accepts `:default | :monospace | String.t() | %Plushie.Type.Font{}`.

# is_toggled(widget, descriptor)

    @spec is_toggled(widget :: t(), value :: boolean() | nil) :: t()

Whether the toggler is on.

Accepts `boolean()`.

# label(widget, descriptor)

    @spec label(widget :: t(), value :: (String.t() | atom()) | nil) :: t()

Text label next to the toggler.

Accepts `String.t() | atom()`.

# line_height(widget, descriptor)

    @spec line_height(
      widget :: t(),
      value :: (number() | %{relative: number()} | %{absolute: number()}) | nil
    ) :: t()

Label line height.

Accepts `number() | %{relative: number()} | %{absolute: number()}`.

# new(id, is_toggled, opts \\ [])

Creates a new widget struct with the given positional args and keyword options.

## Arguments

- `id` - unique widget identifier
- `is_toggled` - Whether the toggler is on.
- `opts` - keyword list of optional props

# shaping(widget, descriptor)

    @spec shaping(widget :: t(), value :: (:basic | :advanced | :auto) | nil) :: t()

Text shaping strategy.

Accepts `:basic | :advanced | :auto`.

# size(widget, descriptor)

    @spec size(widget :: t(), value :: number() | nil) :: t()

Toggler size in pixels.

Accepts `number()`.

# spacing(widget, descriptor)

    @spec spacing(widget :: t(), value :: number() | nil) :: t()

Space between toggler and label in pixels.

Accepts `number()`.

# style(widget, descriptor)

    @spec style(
      widget :: t(),
      value ::
        (:default
         | :primary
         | :secondary
         | :success
         | :danger
         | :warning
         | :dark
         | :weak
         | :rounded_box
         | term())
        | nil
    ) :: t()

Named style preset.

Accepts `:default | :primary | :secondary | :success | :danger | :warning | :dark | :weak | :rounded_box | term()`.

# text_alignment(widget, descriptor)

    @spec text_alignment(
      widget :: t(),
      value :: (:left | :center | :right | :top | :bottom) | nil
    ) :: t()

Horizontal label alignment.

Accepts `:left | :center | :right | :top | :bottom`.

# text_size(widget, descriptor)

    @spec text_size(widget :: t(), value :: number() | nil) :: t()

Label text size in pixels.

Accepts `number()`.

# toggler(id, opts \\ [])

(macro)

Creates a `:toggler` widget.

Shorthand for `new/2`. Import this macro to use the widget name directly in view functions:

    import Plushie.Widget.Toggler, only: [toggler: 2]

    toggler("my-id", prop: value)

# width(widget, descriptor)

    @spec width(
      widget :: t(),
      value :: (:fill | :shrink | {:fill_portion, pos_integer()} | number()) | nil
    ) ::
      t()

Widget width. Default: shrink.

Accepts `:fill | :shrink | {:fill_portion, pos_integer()} | number()`.

# with_options(widget, opts)

    @spec with_options(widget :: t(), opts :: [option()]) :: t()

Applies keyword options to an existing widget struct.

# wrapping(widget, descriptor)

    @spec wrapping(
      widget :: t(),
      value :: (:none | :word | :glyph | :word_or_glyph) | nil
    ) :: t()

Text wrapping mode.

Accepts `:none | :word | :glyph | :word_or_glyph`.