Hints are a way to provide extra data to a notification server that the server may be able to make use of.
Neither clients nor notification servers are required to support any hints. Both sides should assume that hints are not passed, and should ignore any hints they do not understand.
Third parties, when defining their own hints, should discuss the
possibility of standardizing on the hint with other parties, preferably
in a place such as the
xdg
mailing list at
freedesktop.org. If it
warrants a standard, it will be added to the table above. If no
consensus is reached, the hint name should be in the form of
"x-
vendor-name."
The value type for the hint dictionary in D-BUS is of the
DBUS_TYPE_VARIANT container type. This allows different
data types (string, integer, boolean, etc.) to be used for hints. When
adding a dictionary of hints, this type must be used, rather than putting
the actual hint value in as the dictionary value.
The following table lists the standard hints as defined by this specification. Future hints may be proposed and added to this list over time. Once again, implementations are not required to support these.
Table 4. Standard Hints
| Name | Value Type | Description | Spec Version |
|---|---|---|---|
"action-icons" | BOOLEAN | When set, a server that has the "action-icons" capability will attempt to interpret any action identifier as a named icon. The localized display name will be used to annotate the icon for accessibility purposes. The icon name should be compliant with the Freedesktop.org Icon Naming Specification. | >= 1.2 |
"category" | STRING | The type of notification this is. | |
"desktop-entry" | STRING | This specifies the name of the desktop filename representing the calling program. This should be the same as the prefix used for the application's .desktop file. An example would be "rhythmbox" from "rhythmbox.desktop". This can be used by the daemon to retrieve the correct icon for the application, for logging purposes, etc. | |
"image-data" | (iiibiiay) | This is a raw data image format which describes the width, height, rowstride, has alpha, bits per sample, channels and image data respectively. | >= 1.2 |
"image_data" | (iiibiiay) | Deprecated. Use image-data instead. | = 1.1 |
"image-path" | STRING | Alternative way to define the notification image. See Icons and Images. | >= 1.2 |
"image_path" | STRING | Deprecated. Use image-path instead. | = 1.1 |
"icon_data" | (iiibiiay) | Deprecated. Use image-data instead. | < 1.1 |
"resident" | BOOLEAN | When set the server will not automatically remove the notification when an action has been invoked. The notification will remain resident in the server until it is explicitly removed by the user or by the sender. This hint is likely only useful when the server has the "persistence" capability. | >= 1.2 |
"sound-file" | STRING | The path to a sound file to play when the notification pops up. | |
"sound-name" | STRING | A themeable named sound from the freedesktop.org sound naming specification to play when the notification pops up. Similar to icon-name, only for sounds. An example would be "message-new-instant". | |
"suppress-sound" | BOOLEAN | Causes the server to suppress playing any sounds, if it has that ability. This is usually set when the client itself is going to play its own sound. | |
"transient" | BOOLEAN | When set the server will treat the notification as transient and by-pass the server's persistence capability, if it should exist. | >= 1.2 |
"x" | INT32 |
Specifies the X location on the screen that the notification should
point to. The "y" hint must also be specified.
| |
"y" | INT32 |
Specifies the Y location on the screen that the notification should
point to. The "x" hint must also be specified.
| |
"urgency" | BYTE | The urgency level. |