Module naughty

Notification library

Info:

  • Copyright: 2008 koniu
  • Author: koniu <[email protected]>

Functions

is_suspended () Notification state
suspend () Suspend notifications
resume () Resume notifications
toggle () Toggle notification state
destroy (notification, reason[, keep_visible=false]) Destroy notification by notification object
destroy_all_notifications (screens, reason) Destroy all notifications on given screens.
getById (id) Get notification by ID
reset_timeout (notification, new_timeout) Set new notification timeout.
replace_text (notification, new_title, new_text) Replace title and text of an existing notification.
notify (args) Create a notification.

Theme variables

beautiful.notification_font Notifications font.
beautiful.notification_bg Notifications background color.
beautiful.notification_fg Notifications foreground color.
beautiful.notification_border_width Notifications border width.
beautiful.notification_border_color Notifications border color.
beautiful.notification_shape Notifications shape.
beautiful.notification_opacity Notifications opacity.
beautiful.notification_margin Notifications margin.
beautiful.notification_width Notifications width.
beautiful.notification_height Notifications height.

Tables

config Naughty configuration – a table containing common popup settings.
config.presets Notification presets for naughty.notify.
config.defaults Defaults for naughty.notify.
notifications Index of notifications per screen and position.


Functions

Methods
is_suspended ()
Notification state
suspend ()
Suspend notifications
resume ()
Resume notifications
toggle ()
Toggle notification state
destroy (notification, reason[, keep_visible=false])
Destroy notification by notification object
  • notification Notification object to be destroyed
  • reason One of the reasons from notificationClosedReason
  • keep_visible If true, keep the notification visible (default false)

Returns:

    True if the popup was successfully destroyed, nil otherwise
destroy_all_notifications (screens, reason)
Destroy all notifications on given screens.
  • screens table Table of screens on which notifications should be destroyed. If nil, destroy notifications on all screens.
  • reason naughty.notificationClosedReason Reason for closing notifications.

Returns:

    true or nil True if all notifications were successfully destroyed, nil otherwise.
getById (id)
Get notification by ID
  • id ID of the notification

Returns:

    notification object if it was found, nil otherwise
reset_timeout (notification, new_timeout)
Set new notification timeout.
  • notification notification Notification object, which timer is to be reset.
  • new_timeout number Time in seconds after which notification disappears.

Returns:

    None.
replace_text (notification, new_title, new_text)
Replace title and text of an existing notification.
  • notification notification Notification object, which contents are to be replaced.
  • new_title string New title of notification. If not specified, old title remains unchanged.
  • new_text string New text of notification. If not specified, old text remains unchanged.

Returns:

    None.
notify (args)
Create a notification.
  • args The argument table containing any of the arguments below.
    • text string Text of the notification. (default "")
    • title string Title of the notification. (optional)
    • timeout int Time in seconds after which popup expires. Set 0 for no timeout. (default 5)
    • hover_timeout int Delay in seconds after which hovered popup disappears. (optional)
    • screen integer or screen Target screen for the notification. (default focused)
    • position string Corner of the workarea displaying the popups. Values: "top_right", "top_left", "bottom_left", "bottom_right", "top_middle", "bottom_middle". (default "top_right")
    • ontop bool Boolean forcing popups to display on top. (default true)
    • height int Popup height. (default `beautiful.notification_height` or auto)
    • width int Popup width. (default `beautiful.notification_width` or auto)
    • font string Notification font. (default `beautiful.notification_font` or `beautiful.font` or `awesome.font`)
    • icon string Path to icon. (optional)
    • icon_size int Desired icon size in px. (optional)
    • fg string Foreground color. (default `beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`)
    • bg string Background color. (default `beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`)
    • border_width int Border width. (default `beautiful.notification_border_width` or 1)
    • border_color string Border color. (default `beautiful.notification_border_color` or `beautiful.border_focus` or `'#535d6c'`)
    • shape gears.shape Widget shape. (default `beautiful.notification_shape`)
    • opacity gears.opacity Widget opacity. (default `beautiful.notification_opacity`)
    • margin gears.margin Widget margin. (default `beautiful.notification_margin`)
    • run func Function to run on left click. The notification object will be passed to it as an argument. You need to call e.g. notification.die(naughty.notificationClosedReason.dismissedByUser) from there to dismiss the notification yourself. (optional)
    • destroy func Function to run when notification is destroyed. (optional)
    • preset table Table with any of the above parameters. Note: Any parameters specified directly in args will override ones defined in the preset. (optional)
    • replaces_id int Replace the notification with the given ID. (optional)
    • callback func Function that will be called with all arguments. The notification will only be displayed if the function returns true. Note: this function is only relevant to notifications sent via dbus. (optional)
    • actions table Mapping that maps a string to a callback when this action is selected. (optional)
    • ignore_suspend bool If set to true this notification will be shown even if notifications are suspended via naughty.suspend. (default false)

Returns:

    optional table The notification object, or nil in case a notification was not displayed.

Usage:

    naughty.notify({ title = "Achtung!", text = "You're idling", timeout = 0 })

Theme variables

beautiful.notification_font
Notifications font.

Type:

  • notification_font string or lgi.Pango.FontDescription
beautiful.notification_bg
Notifications background color.

Type:

  • notification_bg color
beautiful.notification_fg
Notifications foreground color.

Type:

  • notification_fg color
beautiful.notification_border_width
Notifications border width.

Type:

  • notification_border_width int
beautiful.notification_border_color
Notifications border color.

Type:

  • notification_border_color color
beautiful.notification_shape
Notifications shape.

Type:

  • notification_shape gears.shape (optional)

See also:

beautiful.notification_opacity
Notifications opacity.

Type:

  • notification_opacity int (optional)
beautiful.notification_margin
Notifications margin.

Type:

  • notification_margin int
beautiful.notification_width
Notifications width.

Type:

  • notification_width int
beautiful.notification_height
Notifications height.

Type:

  • notification_height int

Tables

config
Naughty configuration – a table containing common popup settings.

Fields:

  • padding int Space between popups and edge of the workarea. (default apply_dpi(4))
  • spacing int Spacing between popups. (default apply_dpi(1))
  • icon_dirs table List of directories that will be checked by getIcon(). (default {"/usr/share/pixmaps/"})
  • icon_formats table List of formats that will be checked by getIcon(). (default { "png")
  • notify_callback function Callback used to modify or reject notifications, e.g.

    naughty.config.notify_callback = function(args)
        args.text = 'prefix: ' .. args.text
        return args
    end
    

    To reject a notification return nil from the callback. If the notification is a freedesktop notification received via DBUS, you can access the freedesktop hints via args.freedesktop_hints if any where specified. (optional)

  • presets table Notification presets. See config.presets.
  • defaults table Default values for the params to notify(). These can optionally be overridden by specifying a preset. See config.defaults.
config.presets
Notification presets for naughty.notify. This holds presets for different purposes. A preset is a table of any parameters for notify(), overriding the default values (naughty.config.defaults).

You have to pass a reference of a preset in your notify() as the preset argument.

The presets "low", "normal" and "critical" are used for notifications over DBUS.

Fields:

  • low The preset for notifications with low urgency level.
    • timeout int (default 5)
  • normal table The default preset for every notification without a preset that will also be used for normal urgency level. (default empty)
  • critical The preset for notifications with a critical urgency level.
config.defaults
Defaults for naughty.notify.

Fields:

  • timeout int (default 5)
  • text string (default "")
  • screen int Defaults to awful.screen.focused. (optional)
  • ontop boolean (default true)
  • margin int (default apply_dpi(5))
  • border_width int (default apply_dpi(1))
  • position string (default "top_right")
notifications
Index of notifications per screen and position. See config table for valid ‘position’ values. Each element is a table consisting of:

Fields:

  • box Wibox object containing the popup
  • height Popup height
  • width Popup width
  • die Function to be executed on timeout
  • id Unique notification id based on a counter
generated by LDoc 1.4.6 Last updated 2017-07-25 16:21:08