plushie/effect

Platform effects: file dialogs, clipboard, notifications.

Each function takes a tag string as the first argument and returns a Command(msg) that the runtime sends to the bridge as an effect request. The result arrives as an EffectResponse event with the matching tag for clean pattern matching in update.

Only one effect per tag can be in flight at a time. Starting a new effect with a tag that already has a pending request discards the previous one.

Example

fn update(model, event) {
  case event {
    Widget(Click(target: EventTarget(id: "open", ..))) ->
      #(model, effect.file_open("import", [effect.DialogTitle("Pick")]))

    Effect(EffectEvent(tag: "import", result: EffectOk(data))) ->
      #(Model(..model, file: data), command.none())

    Effect(EffectEvent(tag: "import", result: EffectCancelled)) ->
      #(model, command.none())
    _ -> #(model, command.none())
  }
}

Types

FileDialogOpt

</>

Options for file dialog effects.

pub type FileDialogOpt {
  DialogTitle(String)
  DefaultPath(String)
  Filters(List(#(String, String)))
}

Constructors

```
DialogTitle(String)
```
Title shown in the dialog window.
```
DefaultPath(String)
```
Default starting path.
```
Filters(List(#(String, String)))
```
File type filters as (label, pattern) pairs. Example: #(“Images”, “.png;.jpg”)

NotifUrgency

</>

Urgency level for notifications.

pub type NotifUrgency {
  Low
  Normal
  Critical
}

Constructors

```
Low
```
```
Normal
```
```
Critical
```

NotificationOpt

</>

Options for notification effects.

pub type NotificationOpt {
  NotifIcon(String)
  NotifTimeout(Int)
  Urgency(NotifUrgency)
  Sound(String)
}

Constructors

```
NotifIcon(String)
```
Path to notification icon.
```
NotifTimeout(Int)
```
Auto-dismiss timeout in milliseconds.
```
Urgency(NotifUrgency)
```
Notification urgency level.
```
Sound(String)
```
Sound theme name to play (e.g. “message-new-instant”).

Values

clipboard_clear

</>

pub fn clipboard_clear(tag: String) -> command.Command(msg)

Clear the system clipboard.

clipboard_read

</>

pub fn clipboard_read(tag: String) -> command.Command(msg)

Read text from the system clipboard.

clipboard_read_html

</>

pub fn clipboard_read_html(tag: String) -> command.Command(msg)

Read HTML from the system clipboard.

clipboard_read_primary

</>

pub fn clipboard_read_primary(
  tag: String,
) -> command.Command(msg)

Read text from the primary selection (X11).

clipboard_write

</>

pub fn clipboard_write(
  tag: String,
  text: String,
) -> command.Command(msg)

Write text to the system clipboard.

clipboard_write_html

</>

pub fn clipboard_write_html(
  tag: String,
  html: String,
  alt: option.Option(String),
) -> command.Command(msg)

Write HTML to the system clipboard, with optional plain-text fallback.

clipboard_write_primary

</>

pub fn clipboard_write_primary(
  tag: String,
  text: String,
) -> command.Command(msg)

Write text to the primary selection (X11).

default_timeout

</>

pub fn default_timeout(kind: String) -> Int

Returns the default timeout in milliseconds for the given effect kind. File dialogs get 120s (user interaction), clipboard and notification ops get 5s. Unknown kinds fall back to 30s.

directory_select

</>

pub fn directory_select(
  tag: String,
  opts: List(FileDialogOpt),
) -> command.Command(msg)

Open a directory selection dialog.

directory_select_multiple

</>

pub fn directory_select_multiple(
  tag: String,
  opts: List(FileDialogOpt),
) -> command.Command(msg)

Open a multiple directory selection dialog.

file_open

</>

pub fn file_open(
  tag: String,
  opts: List(FileDialogOpt),
) -> command.Command(msg)

Open a single file selection dialog.

file_open_multiple

</>

pub fn file_open_multiple(
  tag: String,
  opts: List(FileDialogOpt),
) -> command.Command(msg)

Open a multiple file selection dialog.

file_save

</>

pub fn file_save(
  tag: String,
  opts: List(FileDialogOpt),
) -> command.Command(msg)

Open a file save dialog.

is_supported_kind

</>

pub fn is_supported_kind(kind: String) -> Bool

Returns whether an effect kind is part of the platform effect API.

notification

</>

pub fn notification(
  tag: String,
  title: String,
  body: String,
  opts: List(NotificationOpt),
) -> command.Command(msg)

Show a desktop notification.

On macOS, notifications may require the app to be bundled (.app) or have notification entitlements to display.