Search documentation of Plushie

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

Copy Markdown View Source

Top-level window container node.

Holds window-level configuration (title, size, position, decorations, etc.) and wraps the child widget tree for that window. The runtime detects window nodes by their `"window"` type string and synchronizes open/close/update operations with the Rust binary via the bridge.

## Props

Name | Type | Default | Description
--- | --- | --- | ---
`title` | `String.t() | atom()` | `nil` | Window title bar text.
`size` | `{number(), number()}` | `nil` | Initial window size as `{width, height}` tuple.
`width` | `:fill | :shrink | {:fill_portion, pos_integer()} | number()` | `nil` | Content width layout. Default: fill.
`height` | `:fill | :shrink | {:fill_portion, pos_integer()} | number()` | `nil` | Content height layout. Default: fill.
`position` | `{number(), number()}` | `nil` | Initial window position as `{x, y}` tuple.
`min_size` | `{number(), number()}` | `nil` | Minimum window dimensions as `{width, height}`.
`max_size` | `{number(), number()}` | `nil` | Maximum window dimensions as `{width, height}`.
`maximized` | `boolean()` | `nil` | Start maximized.
`fullscreen` | `boolean()` | `nil` | Start in fullscreen mode.
`visible` | `boolean()` | `nil` | Whether the window is visible.
`resizable` | `boolean()` | `nil` | Whether the window can be resized.
`closeable` | `boolean()` | `nil` | Whether the window close button is shown.
`minimizable` | `boolean()` | `nil` | Whether the window can be minimized.
`decorations` | `boolean()` | `nil` | Show window decorations (title bar, borders).
`transparent` | `boolean()` | `nil` | Transparent window background.
`blur` | `boolean()` | `nil` | Blur the window background.
`level` | `:normal | :always_on_top | :always_on_bottom` | `nil` | Stacking level: `:normal`, `:always_on_top`, `:always_on_bottom`.
`exit_on_close_request` | `boolean()` | `nil` | Whether closing the window exits the app.
`scale_factor` | `number()` | `nil` | Window scale factor override.
`theme` | `atom() | map()` | `nil` | Per-window theme: built-in atom, `:system`, or custom palette.
`event_rate` | `integer()` | `nil` | Max events per second for coalescable events.
`a11y` | `%Plushie.Type.A11y{} | map() | keyword()` | `%{role: :window}` | Accessibility annotations.

## Summary

### Types

option()
t()

### Functions

a11y(widget, descriptor)

Accessibility annotations.

blur(widget, descriptor)

Blur the window background.

build(widget)

Converts this widget struct to a `ui_node()` map. Validates at most one child.

closeable(widget, descriptor)

Whether the window close button is shown.

decorations(widget, descriptor)

Show window decorations (title bar, borders).

event_rate(widget, descriptor)

Max events per second for coalescable events.

exit_on_close_request(widget, descriptor)

Whether closing the window exits the app.

extend(widget, children)

Appends multiple children to the widget.

fullscreen(widget, descriptor)

Start in fullscreen mode.

height(widget, descriptor)

Content height layout. Default: fill.

level(widget, descriptor)

Stacking level: `:normal`, `:always_on_top`, `:always_on_bottom`.

max_size(widget, descriptor)

Maximum window dimensions as `{width, height}`.

maximized(widget, descriptor)

Start maximized.

min_size(widget, descriptor)

Minimum window dimensions as `{width, height}`.

minimizable(widget, descriptor)

Whether the window can be minimized.

new(id, opts \\ [])

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

position(widget, descriptor)

Initial window position as `{x, y}` tuple.

push(widget, child)

Appends a child to the widget.

resizable(widget, descriptor)

Whether the window can be resized.

scale_factor(widget, descriptor)

Window scale factor override.

size(widget, descriptor)

Initial window size as `{width, height}` tuple.

theme(widget, descriptor)

Per-window theme: built-in atom, `:system`, or custom palette.

title(widget, descriptor)

Window title bar text.

transparent(widget, descriptor)

Transparent window background.

visible(widget, descriptor)

Whether the window is visible.

width(widget, descriptor)

Content width layout. Default: fill.

window(id, opts \\ [])

Creates a `:window` widget.

with_options(widget, opts)

Applies keyword options to an existing widget struct.

## Types

# option()

    @type option() ::
      (((((((((((((((((((({:title, String.t() | atom()}
                          | {:size, {number(), number()}})
                         | {:width,
                            :fill
                            | :shrink
                            | {:fill_portion, pos_integer()}
                            | number()})
                        | {:height,
                           :fill
                           | :shrink
                           | {:fill_portion, pos_integer()}
                           | number()})
                       | {:position, {number(), number()}})
                      | {:min_size, {number(), number()}})
                     | {:max_size, {number(), number()}})
                    | {:maximized, boolean()})
                   | {:fullscreen, boolean()})
                  | {:visible, boolean()})
                 | {:resizable, boolean()})
                | {:closeable, boolean()})
               | {:minimizable, boolean()})
              | {:decorations, boolean()})
             | {:transparent, boolean()})
            | {:blur, boolean()})
           | {:level, :normal | :always_on_top | :always_on_bottom})
          | {:exit_on_close_request, boolean()})
         | {:scale_factor, number()})
        | {:theme, atom() | map()})
       | {: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.Window{
      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,
      blur:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      children: [Plushie.Widget.ui_node()],
      closeable:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      decorations:
        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,
      exit_on_close_request:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      fullscreen:
        boolean()
        | 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(),
      level:
        (:normal | :always_on_top | :always_on_bottom)
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      max_size:
        {number(), number()}
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      maximized:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      min_size:
        {number(), number()}
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      minimizable:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      position:
        {number(), number()}
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      resizable:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      scale_factor:
        number()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      size:
        {number(), number()}
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      theme:
        (atom() | map())
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      title:
        (String.t() | atom())
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      transparent:
        boolean()
        | Plushie.Animation.Transition.t()
        | Plushie.Animation.Spring.t()
        | Plushie.Animation.Sequence.t()
        | nil,
      visible:
        boolean()
        | 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
    }

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

# blur(widget, descriptor)

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

Blur the window background.

Accepts `boolean()`.

# build(widget)

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

Converts this widget struct to a `ui_node()` map. Validates at most one child.

# closeable(widget, descriptor)

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

Whether the window close button is shown.

Accepts `boolean()`.

# decorations(widget, descriptor)

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

Show window decorations (title bar, borders).

Accepts `boolean()`.

# event_rate(widget, descriptor)

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

Max events per second for coalescable events.

Accepts `integer()`.

# exit_on_close_request(widget, descriptor)

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

Whether closing the window exits the app.

Accepts `boolean()`.

# extend(widget, children)

    @spec extend(widget :: t(), children :: [Plushie.Widget.child()]) :: t()

Appends multiple children to the widget.

# fullscreen(widget, descriptor)

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

Start in fullscreen mode.

Accepts `boolean()`.

# height(widget, descriptor)

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

Content height layout. Default: fill.

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

# level(widget, descriptor)

    @spec level(
      widget :: t(),
      value :: (:normal | :always_on_top | :always_on_bottom) | nil
    ) :: t()

Stacking level: `:normal`, `:always_on_top`, `:always_on_bottom`.

Accepts `:normal | :always_on_top | :always_on_bottom`.

# max_size(widget, descriptor)

    @spec max_size(widget :: t(), value :: {number(), number()} | nil) :: t()

Maximum window dimensions as `{width, height}`.

Accepts `{number(), number()}`.

# maximized(widget, descriptor)

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

Start maximized.

Accepts `boolean()`.

# min_size(widget, descriptor)

    @spec min_size(widget :: t(), value :: {number(), number()} | nil) :: t()

Minimum window dimensions as `{width, height}`.

Accepts `{number(), number()}`.

# minimizable(widget, descriptor)

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

Whether the window can be minimized.

Accepts `boolean()`.

# new(id, opts \\ [])

    @spec new(id :: String.t(), opts :: [option()]) :: t()

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

# position(widget, descriptor)

    @spec position(widget :: t(), value :: {number(), number()} | nil) :: t()

Initial window position as `{x, y}` tuple.

Accepts `{number(), number()}`.

# push(widget, child)

    @spec push(widget :: t(), child :: Plushie.Widget.child()) :: t()

Appends a child to the widget.

# resizable(widget, descriptor)

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

Whether the window can be resized.

Accepts `boolean()`.

# scale_factor(widget, descriptor)

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

Window scale factor override.

Accepts `number()`.

# size(widget, descriptor)

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

Initial window size as `{width, height}` tuple.

Accepts `{number(), number()}`.

# theme(widget, descriptor)

    @spec theme(widget :: t(), value :: (atom() | map()) | nil) :: t()

Per-window theme: built-in atom, `:system`, or custom palette.

Accepts `atom() | map()`.

# title(widget, descriptor)

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

Window title bar text.

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

# transparent(widget, descriptor)

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

Transparent window background.

Accepts `boolean()`.

# visible(widget, descriptor)

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

Whether the window is visible.

Accepts `boolean()`.

# width(widget, descriptor)

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

Content width layout. Default: fill.

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

# window(id, opts \\ [])

(macro)

Creates a `:window` widget.

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

    import Plushie.Widget.Window, only: [window: 2]

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

# with_options(widget, opts)

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

Applies keyword options to an existing widget struct.