# 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

• activationTypes
• defaultNotificationSound

Variables - Configurable values

• registry
• warnAboutMissingFunctionTag

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

• new
• show

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

---

# defaultNotificationSound

---

# Variables

# registry

---

# warnAboutMissingFunctionTag

---

# Functions

# deliveredNotifications

---

# register

---

# scheduledNotifications

---

# unregister

---

# unregisterall

---

# withdrawAll

---

# withdrawAllScheduled

---

# 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 informativeText - see hs.notify:informativeText soundName - see hs.notify:soundName subTitle - see hs.notify:subTitle title - see hs.notify:title setIdImage - see hs.notify:setIdImage -- note the border will automatically be set to false if assigned as an attribute in this table. 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 additionalActions - see hs.notify:additionalActions hasReplyButton - see hs.notify:hasReplyButton responsePlaceholder - see hs.notify:responsePlaceholder alwaysShowAdditionalActions - see hs.notify:alwaysShowAdditionalActions withdrawAfter - see hs.notify:withdrawAfter

| | 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.

| | Examples | None | | Source | extensions/notify/notify.lua line 60 |

---

# show

---

# Methods

# 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

---

---