Notifications

The notifications module makes it possible to display non-interactive notifications.

Show

Shows a notification.

Parameter

• name the name of the notification, save this for future update invocations
• header the header text to show
• body the body text to show
• options is an object with the following additional options:
  • severity the severity of the notification, choose between “INFO”, “WARN” and “ERROR”. Default is “INFO”.
  • timeout seconds for the notification to show. Default is 30.
  • callback a javascript function to execute when the user clicks the notification. Default null.
  • embed defines whether the notification should be embedded in the current application or shown on the desktop (default is false = show on desktop)
  • sound a string (one of asterisk, beep, exclamation, hand, question) which indicates a system sound to play once the notification is shown.
  • boundsOffset (for embedded notifications) an object with x, y, w and h properties which define the a rectangle inside the current app which will be used to calculate the position of the notification
  • marginTop (for embedded notifications) an integer with the top margin for the topmost notification (can be used to move notifications a bit down or up)
  • markdown whether or not the body is formatted using markdown (default false)

Example

Show an INFO notification for 30 seconds.

Notification.show("hello", "Seasonal greetings!", "Felice navidad", {});

Show a WARN for 5 seconds.

Notification.show("warn", "Its complicated", "Something broke down", {
  severity: "WARN",
  timeout: 5,
});

Notifications with callbacks.

function RaiseTheAlarm() {
  Notification.show("error", "Oh no!", "You clicked the first notification", {
    severity: "ERROR",
  });
}

// Callback to previously defined function
Notification.show(
  "warn",
  "Its complicated",
  "Something broke down, click here",
  { severity: "WARN", timeout: 5, callback: RaiseTheAlarm },
);

// Callback to anonymous function
Notification.show(
  "warn",
  "Its complicated",
  "Something broke down, click here",
  {
    severity: "WARN",
    timeout: 5,
    callback: function () {
      Log.info("clicked", "Notification was clicked");
    },
  },
);

A note on boundsOffset

Setting a well-functioning boundsOffset can be tricky and should be done when the placement of the embedded notifications is off (partly outside the window etc). Generally speaking you’d probably only want to set either y or x and w or h. It determines how the boundary for the application is offset to allow us to place the notification. An example;

If no boundsOffset is given then the notification will generally be placed:

┌────────────────────────────────┐
│                          ┌────┐│
│                          └────┘│
│                                │
│                                │
│                                │
│                                │
│                                │
│                                │
│                                │
│                                │
│                                │
│                                │
└────────────────────────────────┘

However the bounds calculation of the window might be off for some reason – often when the window is a custom window that draws its own chrome.

If you’ve set boundsOffset: { y: 10, w: -10 } then a new rectangle will be calculated from the original window where its y position is moved down 10 pixes and its width is made 10 pixels less. This is illustrated below with the inner rectangle and the new placement of the notification:

┌────────────────────────────────┐
├──────────────────────────────┐ │
│                        ┌────┐│ │
│                        └────┘│ │
│                              │ │
│                              │ │
│                              │ │
│                              │ │
│                              │ │
│                              │ │
│                              │ │
│                              │ │
│                              │ │
└──────────────────────────────┴─┘

The best approach for finding a value for boundsOffset is simply to try a few variations and see how the placement of the notification is affected.

Update

Update the information in an already shown notification.

Parameter

• name the name of the notification
• header the header text to change
• body the body text to change
• options is same as for invoking show

Example

Update the notification named “hello”.

Notification.update("hello", "Seasonal greetings anew!", "Merry Christmas", {});

Close

Close an open notification. Notifications will automatically be hidden but this can force that action.

Parameter

• name the name of the notification

Example

Close the notification named “hello”.

Notification.close("hello");

Display a Progress

As described in the progress section you can display Progress object in a notification:

var options = { ... }; // see options in Notification.show
var pn = new Progress("My progress");
Notification.progress("Show a Progress", "In a notification", pn, options);
pn.complete(0.72);