nsnotify
nsnotify
TITLE
,
NAME
,
VALUE

The nsnotify statement delivers a notification.

Parameters

This statement has three parameters:

title – is the title of the notification. This is the only required parameter.

name – is the name of a notification option. The options include subtitle, text, button, code, stealth and sound (see below for details). The option names can be in any combination of upper and lower case.

value – is the value of the notification option. Depending on the option, this may be text or a number.

Description

The nsnotify statement delivers a notification to be displayed. In its simplest form, a notification has only a title.

    nsnotify "Danger Will Robinson!"

When this example is run, the message Danger Will Robinson! will appear in a bubble in the upper right hand corner of the screen (unless the user has disabled notifications from Panorama). After a few seconds the bubble will disappear, but the notification will still be visible in the notification center (by default, the last 5 notifications for each application appear there).

There are several different options available for customizing notifications. To configure these options, add one or more option/value pairs to the nsnotify statement.

    nsnotify "Title","option1","value1","option2","value2",...

Each of the available options is described below.

#### Subtitle

This option specifies a subtitle for the notification, which will be displayed below the title, in a slightly smaller font size.

    nsnotify "Danger!","Subtitle","Will Robinson"

#### Text

This option specifies the main text for the notification.

    nsnotify "Danger!","Text","Class 4 rapids ahead"

A notification can have both text and a subtitle.

    nsnotify "Danger!","Subtitle","Will Robinson","Text","Class 4 rapids ahead"

If the main text is too long, it will be cut off. Only about 15 words are allowed (this limit is imposed by Apple, not Panorama).

#### Button

This option adds a button to the notification. (To learn how button clicks are handled, see the Code option below.)

    nsnotify "Danger!","Button","Show Details"

The button option works differently depending on how Panorama’s notification alert style is configured in the System Preferences app. If the alert style is set to Banners, the button will normally be invisible. However, if you move the mouse over the notification, the button will appear and you can click on it.

If the alert style is set to Alerts, two buttons will appear – a Close button, and the button you specified. The notification will not go away until you press one of these two buttons.

#### Code

This option specifies code that should run if the user clicks on the notification. Any time the user clicks on a notification this code will run (unless the user clicks on the notification’s Close button). This code will even run if the user opens up the notification center and clicks on a notification there. It could be a notification from yesterday or last week!

    nsnotify "Danger!","CODE",{message "You were warned at }+superdatestr(supernow())

The program can use the info(“notification”) function to find out information about the notification that was clicked. This function returns a dictionary (see Dictionaries that contains information about the notification – its title, subtitle, text, etc. This example displays a notification with very long body text, most of which will be cut off. When you click on this notification, the code will display a large alert that shows all of the text.

    nsnotify "Danger!",
        "Text",{Risk is the potential of losing something of value, weighed against the potential
            ...
            ...
            ...
            some are much riskier than others.},
        "Code",{displaydata getdictionaryvalue(info("notification"),"TEXT"),
            "title="+getdictionaryvalue(info("notification"),"TITLE")}

One notification of particular interest is `"CLICKED"`. This indicates whether the user clicked in the content area of the notification, or clicked on the button. If you wish, your code can handle each type of click separately.

    getdictionaryvalue(info("notification"),"CLICKED") ☞ Contents
    getdictionaryvalue(info("notification"),"CLICKED") ☞ Button

This example displays a list of all of the notification components. It’s very handy for debugging and development.

    nsnotify "Danger!","CODE",{message dumpdictionary(info("notification"))}

Keep in mind that the code set up by the nsnotify statement could run at any time, in any context. There’s no guarantee that the same window will be active, or even that the same database will be open. If the code needs to use a window or database, it should make sure itself that that database or window is open before proceeding. Remember, it’s quite possible that the user could go into the notification center and click on a notification from days or weeks ago. Make sure your code can handle this.

#### Stealth

This option allows you to send a notification straight to the message center without ever displaying a bubble. Use this for information that isn’t critical, but that the user might want to look at later.

    nsnotify "Found "+pattern(info("selected","#, record~"),"Stealth","true"

#### Sound

Your computer normally plays a little “trill” sound whenever a notification appears. You can turn this off or play a different sound. This notification is silent:

    nsnotify "Ready","Sound",""

The notification can play any system sound (found in /System/Library/Sounds).

    nsnotify "Ready","Sound","Submarine"

If you want a notification to play a custom sound, put it in the ~/Library/Sounds folder. The sound file must endi with the `.aiff` extension (but the extension isn’t included in the parameter. So this example plays a custom sound named `Raindrop.aiff`.

    nsnotify "Ready","Sound","Raindrop"

See Also

- alert -- displays a modal alert window with a message and one or more buttons.
- alertcanceldelete -- displays a modal alert window with a message and two buttons: *Cancel* and *Delete*.
- alertcancelok -- displays a modal alert window with a message and two buttons: *Cancel* and *Ok*.
- alertdeletecancel -- displays a modal alert window with a message and two buttons: *Delete* and *Cancel*.
- alertmodal -- displays a modal alert sheet (not attached to any window) with a message and one or more buttons.
- alertnoyes -- displays a modal alert window with a message and two buttons: *No* and *Yes*.
- alertok -- displays a modal alert window with a message and one button: *Ok*
- alertokcancel -- displays a modal alert window with a message and two buttons: *Ok* and *Cancel*.
- alertoksmall -- displays a modal alert window with a message and one button: *Ok*
- alertrevertcancel -- displays a modal alert window with a message and two buttons: *Revert* and *Cancel*.
- alertsavecancel -- displays a modal alert window with a message and two buttons: *Save* and *Cancel*.
- alertsheet -- displays an alert sheet (attached to the current window) with a message and one or more buttons. Note: with the introduction of OS 11, Big Sur, sheets no longer appear to slide down from the title bar, but open a dialog centered on the active window.
- alertyesno -- displays a modal alert window with a message and two buttons: *Yes* and *No*.
- alertyesnocancel -- displays a modal alert window with a message and three buttons: *Yes*, *No* and *Cancel*.
- beep -- makes the computer speaker beep once.
- bigmessage -- displays a message alert.
- cancelok -- displays a modal alert window with a message and two buttons: *Cancel* and *Ok*.
- gettextokcancel -- displays a modal dialog that asks the user to enter an item of text.
- giantmessage -- displays a message alert.
- growl -- displays a notification.
- growlmessage -- displays a notification.
- message -- displays a modal alert window with a message.
- noyes -- displays a modal alert window with a message and two buttons: *No* and *Yes*.
- okcancel -- displays a modal alert window with a message and two buttons: *Ok* and *Cancel*.
- rudemessage -- displays a message alert.
- statusmessage -- displays a message in the status bar at the bottom of the procedure window.
- stopalert -- displays a modal alert window with a warning icon, a message and one or more buttons.
- tallmessage -- displays a message alert.
- yesno -- displays a modal alert window with a message and two buttons: *Yes* and *No*.

History

Version | Status | Notes
10.0 | New | New in this version.