On this page
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
- Constants - Useful values which cannot be changed
- Variables - Configurable values
- Functions - API calls offered directly by the extension
- deliveredNotifications
- register
- scheduledNotifications
- unregister
- unregisterall
- withdrawAll
- withdrawAllScheduled
- Constructors - API calls which return an object, typically one that offers API methods
- Methods - API calls which can only be made on an object returned by a constructor
- actionButtonTitle
- activationType
- actualDeliveryDate
- additionalActions
- additionalActivationAction
- alwaysPresent
- alwaysShowAdditionalActions
- autoWithdraw
- contentImage
- delivered
- getFunctionTag
- hasActionButton
- hasReplyButton
- informativeText
- otherButtonTitle
- presented
- response
- responsePlaceholder
- schedule
- send
- setIdImage
- soundName
- subTitle
- title
- withdraw
- withdrawAfter
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. |
Notes |
|
Source | extensions/notify/libnotify.m line 1315 |
defaultNotificationSound
Signature | hs.notify.defaultNotificationSound |
---|---|
Type | Constant |
Description | The string representation of the default notification sound. Use |
Source | extensions/notify/libnotify.m line 1503 |
Variables
registry
Signature | hs.notify.registry[] |
---|---|
Type | Variable |
Description | A table containing the registered callback functions and their tags. |
Notes |
|
Source | extensions/notify/notify.lua line 253 |
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 |
Source | extensions/notify/notify.lua line 50 |
Functions
deliveredNotifications
Signature | hs.notify.deliveredNotifications() -> table |
---|---|
Type | Function |
Description | Returns a table containing notifications which have been delivered. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 212 |
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 |
|
Returns |
|
Notes |
|
Source | extensions/notify/notify.lua line 178 |
scheduledNotifications
Signature | hs.notify.scheduledNotifications() -> table |
---|---|
Type | Function |
Description | Returns a table containing notifications which are scheduled but have not yet been delivered. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 259 |
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 |
|
Returns |
|
Source | extensions/notify/notify.lua line 212 |
unregisterall
Signature | hs.notify.unregisterall() |
---|---|
Type | Function |
Description | Unregisters all functions registered as callbacks. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/notify.lua line 239 |
withdrawAll
Signature | hs.notify.withdrawAll() |
---|---|
Type | Function |
Description | Withdraw all delivered notifications from Hammerspoon |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 177 |
withdrawAllScheduled
Signature | hs.notify.withdrawAllScheduled() |
---|---|
Type | Function |
Description | Withdraw all scheduled notifications from Hammerspoon |
Parameters |
|
Returns |
|
Source | extensions/notify/libnotify.m line 196 |
Constructors
new
Signature | hs.notify.new([fn,][attributes]) -> notification |
---|---|
Type | Constructor |
Description | Creates a new notification object |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/notify.lua line 60 |
show
Signature | hs.notify.show(title, subTitle, information[, tag]) -> notification |
---|---|
Type | Constructor |
Description | Shorthand constructor to create and show simple notifications |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/notify.lua line 140 |
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 |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 555 |
activationType
Signature | hs.notify:activationType() -> number |
---|---|
Type | Method |
Description | Returns how the notification was activated by the user. |
Parameters |
|
Returns |
|
Source | extensions/notify/libnotify.m line 1255 |
actualDeliveryDate
Signature | hs.notify:actualDeliveryDate() -> number |
---|---|
Type | Method |
Description | Returns the date and time when a notification was delivered |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 1273 |
additionalActions
Signature | hs.notify:additionalActions([actionsTable]) -> notificationObject | table |
---|---|
Type | Method |
Description | Get or set additional actions which will be displayed for an alert type notification when the user clicks and holds down the action button of the alert. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 1104 |
additionalActivationAction
Signature | hs.notify:additionalActivationAction() -> string | nil |
---|---|
Type | Method |
Description | Return the additional action that the user selected from an alert type notification that has additional actions available. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 1165 |
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 |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 673 |
alwaysShowAdditionalActions
Signature | hs.notify:alwaysShowAdditionalActions([state]) -> notificationObject | boolean |
---|---|
Type | Method |
Description | Get or set whether an alert notification should always show an alternate action menu. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 950 |
autoWithdraw
Signature | hs.notify:autoWithdraw([shouldWithdraw]) -> notificationObject | current-setting |
---|---|
Type | Method |
Description | Get or set whether a notification should automatically withdraw once activated |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 767 |
contentImage
Signature | hs.notify:contentImage([image]) -> notificationObject | current-setting |
---|---|
Type | Method |
Description | Get or set a notification's content image. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/notify.lua line 273 |
delivered
Signature | hs.notify:delivered() -> bool |
---|---|
Type | Method |
Description | Returns whether the notification has been delivered to the Notification Center |
Parameters |
|
Returns |
|
Source | extensions/notify/libnotify.m line 1213 |
getFunctionTag
Signature | hs.notify:getFunctionTag() -> functiontag |
---|---|
Type | Method |
Description | Return the name of the function tag the notification will call when activated. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 737 |
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 |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 637 |
hasReplyButton
Signature | hs.notify:hasReplyButton([state]) -> notificationObject | boolean |
---|---|
Type | Method |
Description | Get or set whether an alert notification has a "Reply" button for additional user input. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 912 |
informativeText
Signature | hs.notify:informativeText([informativeText]) -> notificationObject | current-setting |
---|---|
Type | Method |
Description | Get or set the informative text of a notification |
Parameters |
|
Returns |
|
Source | extensions/notify/libnotify.m line 518 |
otherButtonTitle
Signature | hs.notify:otherButtonTitle([buttonTitle]) -> notificationObject | current-setting |
---|---|
Type | Method |
Description | Get or set the label of a notification's other button |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 596 |
presented
Signature | hs.notify:presented() -> bool |
---|---|
Type | Method |
Description | Returns whether the users Notification Center decided to display the notification |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 1192 |
response
Signature | hs.notify:response() -> string | nil |
---|---|
Type | Method |
Description | Get the users input from an alert type notification with a reply button. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 1076 |
responsePlaceholder
Signature | hs.notify:responsePlaceholder([string]) -> notificationObject | string |
---|---|
Type | Method |
Description | Set a placeholder string for alert type notifications with a reply button. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 1035 |
schedule
Signature | hs.notify:schedule(date) -> notificationObject |
---|---|
Type | Method |
Description | Schedules a notification for delivery in the future. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 346 |
send
Signature | hs.notify:send() -> notificationObject |
---|---|
Type | Method |
Description | Delivers the notification immediately to the users Notification Center. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 312 |
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 |
|
Returns |
|
Notes |
|
Source | extensions/notify/notify.lua line 309 |
soundName
Signature | hs.notify:soundName([soundName]) -> notificationObject | current-setting |
---|---|
Type | Method |
Description | Get or set the sound for a notification |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 811 |
subTitle
Signature | hs.notify:subTitle([subtitleText]) -> notificationObject | current-setting |
---|---|
Type | Method |
Description | Get or set the subtitle of a notification |
Parameters |
|
Returns |
|
Source | extensions/notify/libnotify.m line 481 |
title
Signature | hs.notify:title([titleText]) -> notificationObject | current-setting |
---|---|
Type | Method |
Description | Get or set the title of a notification |
Parameters |
|
Returns |
|
Source | extensions/notify/libnotify.m line 444 |
withdraw
Signature | hs.notify:withdraw() -> notificationObject |
---|---|
Type | Method |
Description | Withdraws a delivered notification from the Notification Center. |
Parameters |
|
Returns |
|
Source | extensions/notify/libnotify.m line 406 |
withdrawAfter
Signature | hs.notify:withdrawAfter([seconds]) -> notificationObject | number |
---|---|
Type | Method |
Description | Get or set the number of seconds after which to automatically withdraw a notification |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/notify/libnotify.m line 992 |
© 2014–2017 Hammerspoon contributors
Licensed under the MIT License.
https://www.hammerspoon.org/docs/hs.notify.html