Search documentation of Plushie

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

Copy Markdown View Source

Text display, renders static text.

## Props

Name | Type | Default | Description
--- | --- | --- | ---
`content` | `String.t() | atom()` | required | The text string to display.
`size` | `number()` | `nil` | Font size in pixels.
`color` | `String.t()` | `nil` | Text color.
`font` | `:default | :monospace | String.t() | %Plushie.Type.Font{}` | `nil` | Font specification.
`width` | `:fill | :shrink | {:fill_portion, pos_integer()} | number()` | `nil` | Text widget width.
`height` | `:fill | :shrink | {:fill_portion, pos_integer()} | number()` | `nil` | Text widget height.
`line_height` | `number() | %{relative: number()} | %{absolute: number()}` | `nil` | Line height. Number is a relative multiplier; map with `%{relative: n}` or `%{absolute: n}` for explicit control.
`align_x` | `:left | :center | :right | :top | :bottom` | `nil` | Horizontal text alignment: `:left`, `:center`, `:right`.
`align_y` | `:left | :center | :right | :top | :bottom` | `nil` | Vertical text alignment: `:top`, `:center`, `:bottom`.
`wrapping` | `:none | :word | :glyph | :word_or_glyph` | `nil` | Text wrapping: `:none`, `:word`, `:glyph`, `:word_or_glyph`.
`ellipsis` | `:none | :start | :middle | :end` | `nil` | Ellipsis mode: `:none`, `:start`, `:middle`, `:end`.
`shaping` | `:basic | :advanced | :auto` | `nil` | Text shaping strategy: `:basic` or `:advanced`.

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

## Constructor

    Text.new(id, content)
    Text.new(id, content, opts)

## Summary

### Types

option()
t()

### Functions

a11y(widget, descriptor)

Accessibility annotations.

align_x(widget, descriptor)

Horizontal text alignment: `:left`, `:center`, `:right`.

align_y(widget, descriptor)

Vertical text alignment: `:top`, `:center`, `:bottom`.

build(widget)

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

color(widget, descriptor)

Text color.

content(widget, descriptor)

The text string to display.

ellipsis(widget, descriptor)

Ellipsis mode: `:none`, `:start`, `:middle`, `:end`.

event_rate(widget, descriptor)

Max events per second for coalescable events.

font(widget, descriptor)

Font specification.

height(widget, descriptor)

Text widget height.

line_height(widget, descriptor)

Line height. Number is a relative multiplier; map with `%{relative: n}` or `%{absolute: n}` for explicit control.

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

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

shaping(widget, descriptor)

Text shaping strategy: `:basic` or `:advanced`.

size(widget, descriptor)

Font size in pixels.

style(widget, descriptor)

Named style: `:default`, `:primary`, `:secondary`, `:success`, `:danger`, `:warning`.

text(id, opts \\ [])

Creates a `:text` widget.

width(widget, descriptor)

Text widget width.

with_options(widget, opts)

Applies keyword options to an existing widget struct.

wrapping(widget, descriptor)

Text wrapping: `:none`, `:word`, `:glyph`, `:word_or_glyph`.

## Types

# option()

    @type option() ::
      (((((((((((({:size, number()} | {:color, atom() | String.t() | map()})
                 | {:font,
                    :default
                    | :monospace
                    | String.t()
                    | %Plushie.Type.Font{
                        family: term(),
                        stretch: term(),
                        style: term(),
                        weight: term()
                      }})
                | {:width,
                   :fill | :shrink | {:fill_portion, pos_integer()} | number()})
               | {:height,
                  :fill | :shrink | {:fill_portion, pos_integer()} | number()})
              | {:line_height,
                 number() | %{relative: number()} | %{absolute: number()}})
             | {:align_x, :left | :center | :right | :top | :bottom})
            | {:align_y, :left | :center | :right | :top | :bottom})
           | {:wrapping, :none | :word | :glyph | :word_or_glyph})
          | {:ellipsis, :none | :start | :middle | :end})
         | {:shaping, :basic | :advanced | :auto})
        | {:style,
           :default
           | :primary
           | :secondary
           | :success
           | :danger
           | :warning
           | :dark
           | :weak
           | :rounded_box
           | term()})
       | {: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.Text{
      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,
      align_x:
        (:left | :center | :right | :top | :bottom)
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      align_y:
        (:left | :center | :right | :top | :bottom)
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      color:
        String.t()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      content:
        (String.t() | atom())
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      ellipsis:
        (:none | :start | :middle | :end)
        | 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,
      height:
        (:fill | :shrink | {:fill_portion, pos_integer()} | number())
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      id: String.t(),
      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,
      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,
      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()`.

# align_x(widget, descriptor)

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

Horizontal text alignment: `:left`, `:center`, `:right`.

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

# align_y(widget, descriptor)

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

Vertical text alignment: `:top`, `:center`, `:bottom`.

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

# build(widget)

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

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

# color(widget, descriptor)

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

Text color.

Accepts `String.t()`.

# content(widget, descriptor)

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

The text string to display.

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

# ellipsis(widget, descriptor)

    @spec ellipsis(widget :: t(), value :: (:none | :start | :middle | :end) | nil) :: t()

Ellipsis mode: `:none`, `:start`, `:middle`, `:end`.

Accepts `:none | :start | :middle | :end`.

# 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()

Font specification.

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

# height(widget, descriptor)

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

Text widget height.

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

# line_height(widget, descriptor)

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

Line height. Number is a relative multiplier; map with `%{relative: n}` or `%{absolute: n}` for explicit control.

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

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

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

## Arguments

- `id` - unique widget identifier
- `content` - The text string to display.
- `opts` - keyword list of optional props

# shaping(widget, descriptor)

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

Text shaping strategy: `:basic` or `:advanced`.

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

# size(widget, descriptor)

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

Font size 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: `:default`, `:primary`, `:secondary`, `:success`, `:danger`, `:warning`.

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

# text(id, opts \\ [])

(macro)

Creates a `:text` widget.

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

    import Plushie.Widget.Text, only: [text: 2]

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

# width(widget, descriptor)

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

Text widget width.

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: `:none`, `:word`, `:glyph`, `:word_or_glyph`.

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