# `Toddy.Iced.Widget.PickList`
[🔗](https://github.com/toddy-ui/toddy-elixir/blob/v0.3.0/lib/toddy/iced/widget/pick_list.ex#L1)

Pick list -- dropdown selection.

## Props

- `options` (list of strings) -- the available choices.
- `selected` (string | nil) -- the currently selected value.
- `placeholder` (string) -- placeholder text when nothing is selected.
- `width` (length) -- widget width. Default: shrink. See `Toddy.Iced.Length`.
- `padding` (number | map) -- internal padding. See `Toddy.Iced.Padding`.
- `text_size` (number) -- text size in pixels.
- `font` (string | map) -- font specification. See `Toddy.Iced.Font`.
- `line_height` (number | map) -- text line height.
- `menu_height` (number) -- maximum height of the dropdown menu in pixels.
- `text_shaping` -- text shaping strategy. See `Toddy.Iced.Shaping`.
- `handle` (map) -- customise the dropdown handle indicator. Map with a `type` key:
  - `%{type: "arrow"}` -- default arrow (optional `size` in pixels).
  - `%{type: "arrow", size: 12}` -- arrow with explicit size.
  - `%{type: "static", icon: icon_map}` -- fixed icon.
  - `%{type: "dynamic", closed: icon_map, open: icon_map}` -- state-dependent icons.
  - `%{type: "none"}` -- no handle.
  Icon maps: `%{code_point: "char", size: n, font: font, spacing: n, line_height: n}`.
- `ellipsis` (string) -- text ellipsis strategy: `"none"`, `"start"`, `"middle"`, or `"end"`.
  Default: `"end"`.
- `menu_style` (map) -- inline style for the dropdown menu. Map with optional keys:
  `background`, `text_color`, `selected_text_color`, `selected_background`, `border`, `shadow`.
- `style` -- `:default` or `StyleMap.t()` for custom styling. See `Toddy.Iced.StyleMap`.
- `a11y` (map) -- accessibility overrides. See `Toddy.Iced.A11y`.

## Events

- `%Widget{type: :select, id: id, value: value}` -- emitted when an option is selected.
- `%Widget{type: :open, id: id}` -- emitted when the dropdown menu is opened (requires `on_open: true`).
- `%Widget{type: :close, id: id}` -- emitted when the dropdown menu is closed (requires `on_close: true`).

# `option`

```elixir
@type option() ::
  {:selected, String.t()}
  | {:placeholder, String.t()}
  | {:width, Toddy.Iced.Length.t()}
  | {:padding, Toddy.Iced.Padding.t()}
  | {:text_size, number()}
  | {:font, Toddy.Iced.Font.t()}
  | {:line_height, number() | map()}
  | {:menu_height, number()}
  | {:text_shaping, Toddy.Iced.Shaping.t()}
  | {:handle, map()}
  | {:ellipsis, String.t()}
  | {:menu_style, map()}
  | {:style, style()}
  | {:on_open, boolean()}
  | {:on_close, boolean()}
  | {:a11y, Toddy.Iced.A11y.t()}
```

# `style`

```elixir
@type style() :: :default | Toddy.Iced.StyleMap.t()
```

# `t`

```elixir
@type t() :: %Toddy.Iced.Widget.PickList{
  a11y: Toddy.Iced.A11y.t() | nil,
  ellipsis: String.t() | nil,
  font: Toddy.Iced.Font.t() | nil,
  handle: map() | nil,
  id: String.t(),
  line_height: number() | map() | nil,
  menu_height: number() | nil,
  menu_style: map() | nil,
  on_close: boolean() | nil,
  on_open: boolean() | nil,
  options: [String.t()],
  padding: Toddy.Iced.Padding.t() | nil,
  placeholder: String.t() | nil,
  selected: String.t() | nil,
  style: style() | nil,
  text_shaping: Toddy.Iced.Shaping.t() | nil,
  text_size: number() | nil,
  width: Toddy.Iced.Length.t() | nil
}
```

# `a11y`

```elixir
@spec a11y(pick_list :: t(), a11y :: Toddy.Iced.A11y.t()) :: t()
```

Sets accessibility annotations.

# `build`

```elixir
@spec build(pick_list :: t()) :: Toddy.Iced.ui_node()
```

Converts this pick list struct to a `ui_node()` map via the `Toddy.Iced.Widget` protocol.

# `ellipsis`

```elixir
@spec ellipsis(pick_list :: t(), ellipsis :: String.t()) :: t()
```

Sets the text ellipsis strategy.

# `font`

```elixir
@spec font(pick_list :: t(), font :: Toddy.Iced.Font.t()) :: t()
```

Sets the font.

# `handle`

```elixir
@spec handle(pick_list :: t(), handle :: map()) :: t()
```

Sets the dropdown handle style.

# `line_height`

```elixir
@spec line_height(pick_list :: t(), line_height :: number() | map()) :: t()
```

Sets the text line height.

# `menu_height`

```elixir
@spec menu_height(pick_list :: t(), menu_height :: number()) :: t()
```

Sets the maximum dropdown menu height in pixels.

# `menu_style`

```elixir
@spec menu_style(pick_list :: t(), menu_style :: map()) :: t()
```

Sets the dropdown menu style overrides.

# `new`

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

Creates a new pick list struct with the given options and optional keyword opts.

# `on_close`

```elixir
@spec on_close(pick_list :: t(), on_close :: boolean()) :: t()
```

Enables or disables the close event when the dropdown menu closes.

# `on_open`

```elixir
@spec on_open(pick_list :: t(), on_open :: boolean()) :: t()
```

Enables or disables the open event when the dropdown menu opens.

# `padding`

```elixir
@spec padding(pick_list :: t(), padding :: Toddy.Iced.Padding.t()) :: t()
```

Sets the internal padding.

# `placeholder`

```elixir
@spec placeholder(pick_list :: t(), placeholder :: String.t()) :: t()
```

Sets the placeholder text.

# `selected`

```elixir
@spec selected(pick_list :: t(), selected :: String.t()) :: t()
```

Sets the currently selected value.

# `style`

```elixir
@spec style(pick_list :: t(), style :: style()) :: t()
```

Sets the pick list style. Accepts `:default` or a `StyleMap`.

# `text_shaping`

```elixir
@spec text_shaping(pick_list :: t(), text_shaping :: Toddy.Iced.Shaping.t()) :: t()
```

Sets the text shaping strategy.

# `text_size`

```elixir
@spec text_size(pick_list :: t(), text_size :: number()) :: t()
```

Sets the text size in pixels.

# `width`

```elixir
@spec width(pick_list :: t(), width :: Toddy.Iced.Length.t()) :: t()
```

Sets the pick list width.

# `with_options`

```elixir
@spec with_options(pick_list :: t(), opts :: [option()]) :: t()
```

Applies keyword options to an existing pick list struct.

---

*Consult [api-reference.md](api-reference.md) for complete listing*