# Module: `naughty.action`

A notification action.

A notification can have multiple actions to chose from. This module allows to manage such actions. An action object can be shared by multiple notifications.

### Info:

- Copyright: 2019 Emmanuel Lepage Vallee
- Originally authored by: Emmanuel Lepage Vallee <elv1313@gmail.com>
  (Full contributors list available on our github project)

## Constructors

naughty.action {[args]} | Create a new action. |

## Object properties

position | integer | The action position (index). |
icon | image or string or nil | The action icon. |
icon_only | boolean | If the action should hide the label and only display the icon. |

## Object methods

:invoke (notif) | Execute this action. |
:emit_signal (name, ...) | Emit a signal. | Inherited from gears.object
:connect_signal (name, func) | Connect to a signal. | Inherited from gears.object
:weak_connect_signal (name, func) | Connect to a signal weakly. | Inherited from gears.object

## Signals

invoked | When a notification is invoked. |

## Constructors

🔗 naughty.action {[args]}
  Create a new action.

  ### Parameters:

  Note: This constructors uses named parameters calling convention. It means you call it with `{}` and omit the parantheses. For example, calling this will all default argument would be `naughty.action{}`. This is a Lua shortcut syntax equivalent to `naughty.action({})`. `args` is only a placeholder name for the "lone table argument" used in named parameters calls.

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  args |  | table | The arguments.
  name |  | string | The name.
  position |  | string | The position.
  icon |  | string | The icon.
  notification |  | naughty.notification | The notification object.
  selected |  | boolean | If this action is currently selected.

  ### Returns:

  A new action.

## Object properties

🔗 position integer · 1 signal
  The action position (index).

  ### Constraints:

  Default value | : This is provided by DBus.
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::position` When the position value changes.
  - `self` naughty.action The object which changed (useful when connecting many object to the same callback).
  - `new_value` position The new value affected to the property.
🔗 icon image or string or nil · 1 signal
  The action icon.

  ### Constraints:

  Default value | : `nil`
  Type description:
  string | : Interpreted as a path to an image file.
  string | : A valid SVG content.
  cairo | : A cairo image surface: Directly used as-is.
  librsvg | : A librsvg handle object: Directly used as-is.
  nil | : Unset the image.

  Click to display more

  ### Emit signals:

  - `property::icon` When the icon value changes.
  - `self` naughty.action The object which changed (useful when connecting many object to the same callback).
  - `new_value` icon The new value affected to the property.
🔗 icon_only boolean · 1 signal
  If the action should hide the label and only display the icon.

  local notif = naughty.notification { title = "A notification", message = "This notification has actions!", actions = { naughty.action { name = "Accept", icon = beautiful.awesome_icon, icon_only = true, }, naughty.action { name = "Refuse", icon = beautiful.awesome_icon, icon_only = true, }, naughty.action { name = "Ignore", icon = beautiful.awesome_icon, icon_only = true, }, } } wibox.widget { notification = notif, widget = naughty.list.actions, }

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

  Click to display more

  ### Emit signals:

  - `property::icon_only` When the icon_only value changes.
  - `self` naughty.action The object which changed (useful when connecting many object to the same callback).
  - `new_value` icon_only The new value affected to the property.

## Object methods

🔗 :invoke (notif)
  Execute this action.

  This only emits the invoked signal.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  notif | Optional | naughty.notification | A notification object on which the action was invoked. If a notification is shared by many object (like a "mute" or "snooze" action added to all notification), calling `:invoke()` without adding the `notif` context will cause unexpected results. | `{}`

🔗 :emit_signal (name, ...) · Inherited from gears.object
  Emit a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  ... |  |  | Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

🔗 :connect_signal (name, func) · Inherited from gears.object
  Connect to a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

🔗 :weak_connect_signal (name, func) · Inherited from gears.object
  Connect to a signal weakly.

  This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

  **Warning:** Only use this function if you really, really, really know what you are doing.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

## Signals

🔗 invoked
  When a notification is invoked.

  Note that it is possible to call `:invoke()` without a notification object. It is possible the `notification` parameter will be nil.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  action |  | naughty.action | The action.
  notification |  | naughty.notification or nil | The notification, if known.

generated by LDoc 1.5.0