docs » hs.notify

This module allows you to create on screen notifications in the User Notification Center located at the right of the users screen.

Notifications can be sent immediately or scheduled for delivery at a later time, even if that scheduled time occurs when Hammerspoon is not currently running. Currently, if you take action on a notification while Hammerspoon is not running, the callback function is not honored for the first notification clicked upon -- This is expected to be fixed in a future release.

When setting up a callback function, you have the option of specifying it with the creation of the notification (hs.notify.new) or by pre-registering it with hs.notify.register and then referring it to by the tag name specified with hs.notify.register. If you use this registration method for defining your callback functions, and make sure to register all expected callback functions within your init.lua file or files it includes, then callback functions will remain available for existing notifications in the User Notification Center even if Hammerspoon's configuration is reloaded or if Hammerspoon is restarted. If the callback tag is not present when the user acts on the notification, the Hammerspoon console will be raised as a default action.

A shorthand, based upon the original inspiration for this module from Hydra and Mjolnir, hs.notify.show, is provided if you just require a quick and simple informative notification without the bells and whistles.

This module is based in part on code from the previous incarnation of Mjolnir by Steven Degutis.

API Overview

API Documentation

Constants

activationTypes
Signature hs.notify.activationTypes[]
Type Constant
Description

Convenience array of the possible activation types for a notification, and their reverse for reference.

  • None - The user has not interacted with the notification.
  • ContentsClicked - User clicked on notification
  • ActionButtonClicked - User clicked on Action button

Notes:

  • Count starts at zero. (implemented in Objective-C)
defaultNotificationSound
Signature hs.notify.defaultNotificationSound
Type Constant
Description

The string representation of the default notification sound. Use hs.notify:soundName() or set the soundName attribute in hs:notify.new(), to this constant, if you want to use the default sound

Variables

registry
Signature hs.notify.registry[]
Type Variable
Description

A table containing the registered callback functions and their tags.

Notes:

  • This table should not be modified directly. Use the hs.notify.register(tag, fn) and hs.notify.unregister(id) functions.
  • This table has a __tostring metamethod so you can see the list of registered function tags in the console by typing hs.notify.registry
  • See hs.notify.warnAboutMissingFunctionTag for determining the behavior when a notification attempts to perform a callback to a function tag which is not present in this table. This occurrence is most common with notifications which are acted upon by the user after Hammerspoon has been reloaded.
warnAboutMissingFunctionTag
Signature hs.notify.warnAboutMissingFunctionTag
Type Variable
Description

A value indicating whether or not a missing notification function tag should cause a warning. Defaults to true.

If this variable is set to a function, the function will be called with two parameters tag, which will match the tag specified if you used hs.notify.show or a UUID if you used hs.notify.new to define the notification, and notification which will be the notificationObject representing the notification. No return value is expected.

If this variable is not set to a function, it will be evaluated as a lua boolean (i.e. any value except false and nil is considered true). If it evaluates to true, a warning will be displayed to the console indicating that the callback function is missing; if it is false, the notification will be silently discarded.

Functions

register
Signature hs.notify.register(tag, fn) -> id
Type Function
Description

Registers a function callback with the specified tag for a notification. The callback function will be invoked when the user clicks on or interacts with a notification.

Parameters:

  • tag - a string tag to identify the registered callback function. Use this as the function tag in hs.notify.new and hs.notify.show
  • fn - the function which should be invoked when a notification with this tag is interacted with.

Returns:

  • a numerical id representing the entry in hs.notify.registry for this function. This number can be used with hs.notify.unregister to unregister a function later if you wish.

Notes:

  • If a function is already registered with the specified tag, it is replaced by with the new one.
unregister
Signature hs.notify.unregister(id|tag)
Type Function
Description

Unregisters a function callback so that it is no longer available as a callback when notifications corresponding to the specified entry are interacted with.

Parameters:

  • id or tag - the numerical id provided by hs.notify.register or string tag representing the callback function to be removed

Returns:

  • None
unregisterall
Signature hs.notify.unregisterall()
Type Function
Description

Unregisters all functions registered as callbacks.

Parameters:

  • None

Returns:

  • None

Notes:

  • This does not remove the notifications from the User Notification Center, it just removes their callback function for when the user interacts with them. To remove all notifications, see hs.notify.withdrawAll and hs.notify.withdrawAllScheduled
withdrawAll
Signature hs.notify.withdrawAll()
Type Function
Description

Withdraw all delivered notifications from Hammerspoon

Parameters:

  • None

Returns:

  • None

Notes:

  • This will withdraw all notifications for Hammerspoon, including those not sent by this module or that linger from a previous load of Hammerspoon.
withdrawAllScheduled
Signature hs.notify.withdrawAllScheduled()
Type Function
Description

Withdraw all scheduled notifications from Hammerspoon

Parameters:

  • None

Returns:

  • None

Constructors

new
Signature hs.notify.new([fn,][attributes]) -> notification
Type Constructor
Description

Creates a new notification object

Parameters:

  • fn - An optional function or function-tag, which will be called when the user interacts with notifications. The notification object will be passed as an argument to the function. If you leave this parameter out or specify nil, then no callback will be attached to the notification.
  • attributes - An optional table for applying attributes to the notification. Possible keys are:

    • alwaysPresent - see hs.notify:alwaysPresent
    • autoWithdraw - see hs.notify:autoWithdraw
    • contentImage - see hs.notify:contentImage (only supported in 10.9 and later)
    • informativeText - see hs.notify:informativeText
    • soundName - see hs.notify:soundName
    • subTitle - see hs.notify:subTitle
    • title - see hs.notify:title

    The following can also be set, but will only have an apparent effect on the notification when the user has set Hammerspoon's notification style to "Alert" in the Notification Center panel of System Preferences:

    • actionButtonTitle - see hs.notify:actionButtonTitle
    • hasActionButton - see hs.notify:hasActionButton
    • otherButtonTitle - see hs.notify:otherButtonTitle

Returns:

  • A notification object

Notes:

  • A function-tag is a string key which corresponds to a function stored in the hs.notify.registry table with the hs.notify.register() function.
  • If a notification does not have a title attribute set, OS X will not display it, so by default it will be set to "Notification". You can use the title key in the attributes table, or call hs.notify:title() before displaying the notification to change this.
show
Signature hs.notify.show(title, subTitle, information[, tag]) -> notfication
Type Constructor
Description

Shorthand constructor to create and show simple notifications

Parameters:

  • title - the title for the notification
  • subTitle - the subtitle, or second line, of the notification
  • information - the main textual body of the notification
  • tag - a function tag corresponding to a function registered with hs.notify.register

Returns:

  • a notification object

Notes:

  • All three textual parameters are required, though they can be empty strings
  • This function is really a shorthand for hs.notify.new(...):send()

Methods

actionButtonTitle
Signature hs.notify:actionButtonTitle([buttonTitle]) -> notificationObject | current-setting
Type Method
Description

Get or set the label of a notification's action button

Parameters:

  • buttonTitle - An optional string containing the title for the notification's action button. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if buttonTitle is present; otherwise the current setting.

Notes:

  • The affects of this method only apply if the user has set Hammerspoon notifications to Alert in the Notification Center pane of System Preferences
activationType
Signature hs.notify:activationType() -> number
Type Method
Description

Returns how the notification was activated by the user.

Parameters:

  • None

Returns:

  • the integer value corresponding to how the notification was activated by the user. See the table hs.notify.activationTypes[] for more information.
actualDeliveryDate
Signature hs.notify:actualDeliveryDate() -> number
Type Method
Description

Returns the date and time when a notification was delivered

Parameters:

  • None

Returns:

  • A number containing the delivery date/time of the notification, in seconds since the epoch (i.e. 1970-01-01 00:00:00 +0000)

Notes:

  • You can turn epoch times into a human readable string or a table of date elements with the os.date() function.
alwaysPresent
Signature hs.notify:alwaysPresent([alwaysPresent]) -> notificationObject | current-setting
Type Method
Description

Get or set whether a notification should be presented even if this overrides Notification Center's decision process.

Parameters:

  • alwaysPresent - An optional boolean parameter indicating whether the notification should override Notification Center's decision about whether to present the notification or not. Defaults to true. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if alwaysPresent is provided; otherwise the current setting.

Notes:

  • This does not affect the return value of hs.notify:presented() -- that will still reflect the decision of the Notification Center
  • Examples of why the users Notification Center would choose not to display a notification would be if Hammerspoon is the currently focussed application, being attached to a projector, or the user having set Do Not Disturb.
autoWithdraw
Signature hs.notify:autoWithdraw([shouldWithdraw]) -> notificationObject | current-setting
Type Method
Description

Get or set whether a notification should automatically withdraw once activated

Parameters:

  • shouldWithdraw - An optional boolean indicating whether the notification should automatically withdraw. Defaults to true. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if shouldWithdraw is present; otherwise the current setting.

Note:

  • This method has no effect if the user has set Hammerspoon notifications to Alert in the Notification Center pane of System Preferences: clicking on either the action or other button will clear the notification automatically.
  • If a notification which was created before your last reload (or restart) of Hammerspoon and is clicked upon before hs.notify has been loaded into memory, this setting will not be honored because the initial application delegate is not aware of this option and is set to automatically withdraw all notifications which are acted upon.
contentImage
Signature hs.notify:contentImage([image]) -> notificationObject | current-setting
Type Method
Description

Get or set a notification's content image.

Parameters:

  • image - An optional hs.image parameter containing the image to display. Defaults to nil. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if image is provided; otherwise the current setting.

Notes:

  • See hs.image for details on how to specify or define an image
  • This method is only supported in OS X 10.9 or greater. A warning will be displayed in the console and the method will be treated as a no-op if used on an unsupported system.
delivered
Signature hs.notify:delivered() -> bool
Type Method
Description

Returns whether the notification has been delivered to the Notification Center

Parameters:

  • None

Returns:

  • A boolean indicating whether the notification has been delivered to the users Notification Center
getFunctionTag
Signature hs.notify:getFunctionTag() -> functiontag
Type Method
Description

Return the name of the function tag the notification will call when activated.

Parameters:

  • None

Returns:

  • The function tag for this notification as a string.

Notes:

  • This tag should correspond to a function in hs.notify.registry and can be used to either add a replacement with hs.notify.register(...) or remove it with hs.notify.unregister(...)
hasActionButton
Signature hs.notify:hasActionButton([hasButton]) -> notificationObject | current-setting
Type Method
Description

Get or set the presence of an action button in a notification

Parameters:

  • hasButton - An optional boolean indicating whether an action button should be present. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if hasButton is present; otherwise the current setting.

Notes:

  • The affects of this method only apply if the user has set Hammerspoon notifications to Alert in the Notification Center pane of System Preferences
informativeText
Signature hs.notify:informativeText([informativeText]) -> notificationObject | current-setting
Type Method
Description

Get or set the informative text of a notification

Parameters:

  • informativeText - An optional string containing the informative text to be set on the notification object. This can be an empty string. If nil is passed, any existing informative text will be removed. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if informativeText is present; otherwise the current setting.
otherButtonTitle
Signature hs.notify:otherButtonTitle([buttonTitle]) -> notificationObject | current-setting
Type Method
Description

Get or set the label of a notification's other button

Parameters:

  • buttonTitle - An optional string containing the title for the notification's other button. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if buttonTitle is present; otherwise the current setting.

Notes:

  • The affects of this method only apply if the user has set Hammerspoon notifications to Alert in the Notification Center pane of System Preferences
  • Due to OSX limitations, it is NOT possible to get a callback for this button.
presented
Signature hs.notify:presented() -> bool
Type Method
Description

Returns whether the users Notification Center decided to display the notification

Parameters:

  • None

Returns:

  • A boolean indicating whether the users Notification Center decided to display the notification

Notes:

  • Examples of why the users Notification Center would choose not to display a notification would be if Hammerspoon is the currently focussed application, being attached to a projector, or the user having set Do Not Disturb.
release
Signature hs.notify:release() -> notificationObject
Type Method
Description

This is a no-op included for backwards compatibility.

Parameters:

  • None

Returns:

  • The notification object

Notes:

  • This is no longer required during garbage collection as function tags can be re-established after a reload.
  • The proper way to release a notifications callback is to remove its tag from the hs.notify.registry with hs.notify.unregister.
  • This is included for backwards compatibility.
schedule
Signature hs.notify:schedule(date) -> notificationObject
Type Method
Description

Schedules a notification for delivery in the future.

Parameters:

  • date - the date the notification should be delivered to the users Notification Center specified as the number of seconds since 1970-01-01 00:00:00Z or as a string in rfc3339 format: "YYYY-MM-DD[T]HH:MM:SS[Z]".

Returns:

  • The notification object

Notes:

  • See also hs.notify:send()
  • hs.settings.dateFormat specifies a lua format string which can be used with os.date() to properly present the date and time as a string for use with this method.
send
Signature hs.notify:send() -> notificationObject
Type Method
Description

Delivers the notification immediately to the users Notification Center.

Parameters:

  • None

Returns:

  • The notification object

Notes:

  • See also hs.notify:schedule()
  • If a notification has been modified, then this will resend it.
  • You can invoke this multiple times if you wish to repeat the same notification.
setIdImage
Signature hs.notify:setIdImage(image[, withBorder]) -> notificationObject
Type Method
Description

Set a notification's identification image (replace the Hammerspoon icon with a custom image)

Parameters:

  • image - An hs.image object, a string containing an image path, or a string defining an ASCIImage
  • withBorder - An optional boolean to give the notification image a border. Defaults to false

Returns:

  • The notification object

Notes:

  • See hs.image for details on how to specify or define an image
  • WARNING: This method uses a private API. It could break at any time. Please file an issue if it does
soundName
Signature hs.notify:soundName([soundName]) -> notificationObject | current-setting
Type Method
Description

Get or set the sound for a notification

Parameters:

  • soundName - An optional string containing the name of a sound to play with the notification. If nil, no sound will be played. Defaults to nil. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if soundName is present; otherwise the current setting.

Notes:

  • Sounds will first be matched against the names of system sounds. If no matches can be found, they will then be searched for in the following paths, in order:
    • ~/Library/Sounds
    • /Library/Sounds
    • /Network/Sounds
    • /System/Library/Sounds
subTitle
Signature hs.notify:subTitle([subtitleText]) -> notificationObject | current-setting
Type Method
Description

Get or set the subtitle of a notification

Parameters:

  • subtitleText - An optional string containing the subtitle to be set on the notification object. This can be an empty string. If nil is passed, any existing subtitle will be removed. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if subtitleText is present; otherwise the current setting.
title
Signature hs.notify:title([titleText]) -> notificationObject | current-setting
Type Method
Description

Get or set the title of a notification

Parameters:

  • titleText - An optional string containing the title to be set on the notification object. The default value is "Notification". If nil is passed, then the title is set to the empty string. If no parameter is provided, then the current setting is returned.

Returns:

  • The notification object, if titleText is present; otherwise the current setting.
withdraw
Signature hs.notify:withdraw() -> notificationObject
Type Method
Description

Withdraws a delivered notification from the Notification Center.

Parameters:

  • None

Returns:

  • The notification object