StatusNotifier

StatusNotifier — A StatusNotifierItem as per KDE's specifications

Functions

Properties

char * attention-icon-name Read / Write
GdkPixbuf * attention-icon-pixbuf Read / Write
char * attention-movie-name Read / Write
StatusNotifierCategory category Read / Write / Construct Only
char * id Read / Write / Construct Only
gboolean item-is-menu Read / Write
char * main-icon-name Read / Write
GdkPixbuf * main-icon-pixbuf Read / Write
GObject * menu Read / Write
char * overlay-icon-name Read / Write
GdkPixbuf * overlay-icon-pixbuf Read / Write
StatusNotifierState state Read
StatusNotifierStatus status Read / Write
char * title Read / Write
char * tooltip-body Read / Write
char * tooltip-icon-name Read / Write
GdkPixbuf * tooltip-icon-pixbuf Read / Write
char * tooltip-title Read / Write
guint window-id Read / Write

Signals

Types and Values

Object Hierarchy

    GEnum
    ├── StatusNotifierCategory
    ├── StatusNotifierError
    ├── StatusNotifierIcon
    ├── StatusNotifierScrollOrientation
    ├── StatusNotifierState
    ╰── StatusNotifierStatus
    GObject
    ╰── StatusNotifierItem

Description

Starting with Plasma Next, KDE doesn't support the XEmbed systray in favor of their own Status Notifier Specification.

A StatusNotifierItem is a GObject that can be used to represent a StatusNotifierItem, handling all the DBus implementation and leaving you simply dealing with regular properties and signals.

You can simply create a new StatusNotifierItem using one of the helper function, e.g. status_notifier_item_new_from_icon_name(), or simply creating an object as usual - you then just need to make sure to specify “id” :

sn = (StatusNotifierItem *) g_object_new (STATUS_NOTIFIER_TYPE_ITEM,
     "id",                       "app-id",
     "status",                   STATUS_NOTIFIER_STATUS_NEEDS_ATTENTION,
     "main-icon-name",           "app-icon",
     "attention-icon-pixbuf",    pixbuf,
     "tooltip-title",            "My tooltip",
     "tooltip-body",             "This is an item about <b>app</b>",
     NULL);

You can also set properties (other than id) after creation. Once ready, call status_notifier_item_register() to register the item on the session bus and to the StatusNotifierWatcher.

If an error occurs, signal “registration-failed” will be emitted. On success, “state” will be STATUS_NOTIFIER_STATE_REGISTERED. See status_notifier_item_register() for more.

Once registered, you can change properties as needed, and the proper DBus signal will be emitted to let visualizations (hosts) know, and connect to the signals (such as “context-menu”) which will be emitted when the corresponding DBus method was called.

For reference, the specifications can be found at https://freedesktop.org/wiki/Specifications/StatusNotifierItem/

Note that statusnotifier uses org.kde.* instead of the mentionned org.freedesktop.* as the former was in the original specifications (still available at http://www.notmart.org/misc/statusnotifieritem/index.html) and seem to be the one actually in use.

Functions

status_notifier_item_new_from_pixbuf ()

StatusNotifierItem *
status_notifier_item_new_from_pixbuf (const gchar *id,
                                      StatusNotifierCategory category,
                                      GdkPixbuf *pixbuf);

Creates a new item

Parameters

id

The application id

 

category

The category for the item

 

pixbuf

The icon to use as main icon

 

Returns

A new StatusNotifierItem.

[transfer full]


status_notifier_item_new_from_icon_name ()

StatusNotifierItem *
status_notifier_item_new_from_icon_name
                               (const gchar *id,
                                StatusNotifierCategory category,
                                const gchar *icon_name);

Creates a new item

Parameters

id

The application id

 

category

The category for the item

 

icon_name

The name of the icon to use as main icon

 

Returns

A new StatusNotifierItem.

[transfer full]


status_notifier_item_get_id ()

const gchar *
status_notifier_item_get_id (StatusNotifierItem *sn);

Returns the application id of sn

Parameters

Returns

The application id of sn . The string is owned by sn , you should not free it


status_notifier_item_get_category ()

StatusNotifierCategory
status_notifier_item_get_category (StatusNotifierItem *sn);

Returns the category of sn

Parameters

Returns

The category of sn


status_notifier_item_set_from_pixbuf ()

void
status_notifier_item_set_from_pixbuf (StatusNotifierItem *sn,
                                      StatusNotifierIcon icon,
                                      GdkPixbuf *pixbuf);

Sets the icon icon to pixbuf .

An icon can either be identified by its Freedesktop-compliant icon name, or by the icon data itself (via GdkPixbuf).

It is currently not possible to set both, as setting one will unset the other.

Parameters

sn

A StatusNotifierItem

 

icon

Which icon to set

 

pixbuf

A GdkPixbuf to use for icon

 

status_notifier_item_set_from_icon_name ()

void
status_notifier_item_set_from_icon_name
                               (StatusNotifierItem *sn,
                                StatusNotifierIcon icon,
                                const gchar *icon_name);

Sets the icon icon to be icon_name .

An icon can either be identified by its Freedesktop-compliant icon name, or by the icon data itself (via GdkPixbuf).

It is currently not possible to set both, as setting one will unset the other.

Parameters

sn

A StatusNotifierItem

 

icon

Which icon to set

 

icon_name

Name of an icon to use for icon

 

status_notifier_item_has_pixbuf ()

gboolean
status_notifier_item_has_pixbuf (StatusNotifierItem *sn,
                                 StatusNotifierIcon icon);

Returns whether icon icon currently has a GdkPixbuf set or not. If so, the icon data will be sent via DBus, else the icon name (if any) will be used.

Parameters

sn

A StatusNotifierItem

 

icon

Which icon

 

Returns

TRUE is a GdkPixbuf is set for icon , else FALSE


status_notifier_item_get_pixbuf ()

GdkPixbuf *
status_notifier_item_get_pixbuf (StatusNotifierItem *sn,
                                 StatusNotifierIcon icon);

Returns the GdkPixbuf set for icon , if there's one. Not that it will return NULL if an icon name is set.

Parameters

sn

A StatusNotifierItem

 

icon

The icon to get

 

Returns

The GdkPixbuf set for icon , or NULL.

[transfer full]


status_notifier_item_get_icon_name ()

gchar *
status_notifier_item_get_icon_name (StatusNotifierItem *sn,
                                    StatusNotifierIcon icon);

Returns the icon name set for icon , if there's one. Not that it will return NULL if a GdkPixbuf is set.

Parameters

sn

A StatusNotifierItem

 

icon

The icon to get

 

Returns

A newly allocated string of the icon name set for icon , free using g_free().

[transfer full]


status_notifier_item_set_attention_movie_name ()

void
status_notifier_item_set_attention_movie_name
                               (StatusNotifierItem *sn,
                                const gchar *movie_name);

In addition to the icon, the item can also specify an animation associated to the STATUS_NOTIFIER_STATUS_NEEDS_ATTENTION status.

This should be either a Freedesktop-compliant icon name or a full path. The visualization can chose between the movie or icon (or using neither of those) at its discretion.

Parameters

sn

A StatusNotifierItem

 

movie_name

The name of the movie

 

status_notifier_item_get_attention_movie_name ()

gchar *
status_notifier_item_get_attention_movie_name
                               (StatusNotifierItem *sn);

Returns the movie name set for animation associated with the STATUS_NOTIFIER_STATUS_NEEDS_ATTENTION status

Parameters

Returns

A newly allocated string with the movie name, free using g_free() when done


status_notifier_item_set_title ()

void
status_notifier_item_set_title (StatusNotifierItem *sn,
                                const gchar *title);

Sets the title of the item (might be used by visualization e.g. in menu of hidden items when STATUS_NOTIFIER_STATUS_PASSIVE)

Parameters

sn

A StatusNotifierItem

 

title

The title

 

status_notifier_item_get_title ()

gchar *
status_notifier_item_get_title (StatusNotifierItem *sn);

Returns the title of the item

Parameters

Returns

A newly allocated string, free with g_free() when done


status_notifier_item_set_status ()

void
status_notifier_item_set_status (StatusNotifierItem *sn,
                                 StatusNotifierStatus status);

Sets the item status to status , describing the status of this item or of the associated application.

Parameters

sn

A StatusNotifierItem

 

status

The new status

 

status_notifier_item_get_status ()

StatusNotifierStatus
status_notifier_item_get_status (StatusNotifierItem *sn);

Returns the status of sn

Parameters

Returns

Current status of sn


status_notifier_item_set_window_id ()

void
status_notifier_item_set_window_id (StatusNotifierItem *sn,
                                    guint32 window_id);

Sets the window ID for sn

It's the windowing-system dependent identifier for a window, the application can chose one of its windows to be available trough this property or just set 0 if it's not interested.

Parameters

sn

A StatusNotifierItem

 

window_id

The window ID

 

status_notifier_item_get_window_id ()

guint32
status_notifier_item_get_window_id (StatusNotifierItem *sn);

Returns the windowing-system dependent idnetifier for a window associated with sn

Parameters

Returns

The window ID associated with sn


status_notifier_item_freeze_tooltip ()

void
status_notifier_item_freeze_tooltip (StatusNotifierItem *sn);

Increases the freeze count for tooltip on sn . If the freeze count is non-zero, the emission of a DBus signal for StatusNotifierHost to refresh the ToolTip property will be blocked until the freeze count drops back to zero (via status_notifier_item_thaw_tooltip())

This is to allow to set the different properties forming the tooltip (title, body and icon) without triggering a refresh afetr each change (as there is a single property ToolTip on the DBus item, with all data).

Every call to status_notifier_item_freeze_tooltip() should later be followed by a call to status_notifier_item_thaw_tooltip()

Parameters


status_notifier_item_thaw_tooltip ()

void
status_notifier_item_thaw_tooltip (StatusNotifierItem *sn);

Reverts the effect of a previous call to status_notifier_item_freeze_tooltip(). If the freeze count drops back to zero, a signal NewToolTip will be emitted on the DBus object for sn , for StatusNotifierHost to refresh its ToolTip property.

It is an error to call this function when the freeze count is zero.

Parameters


status_notifier_item_set_tooltip ()

void
status_notifier_item_set_tooltip (StatusNotifierItem *sn,
                                  const gchar *icon_name,
                                  const gchar *title,
                                  const gchar *body);

This is an helper function that allows to set icon name, title and body of the tooltip and then emit one DBus signal NewToolTip.

It is equivalent to the following code, and similar code can be used e.g. to set the icon from a GdkPixbuf instead:

status_notifier_item_freeze_tooltip (sn);
status_notifier_item_set_from_icon_name (sn, STATUS_NOTIFIER_TOOLTIP_ICON, icon_name);
status_notifier_item_set_tooltip_title (sn, title);
status_notifier_item_set_tooltip_body (sn, body);
status_notifier_item_thaw_tooltip (sn);

Parameters

sn

A StatusNotifierItem

 

icon_name

The icon name to be used for STATUS_NOTIFIER_TOOLTIP_ICON

 

title

The title of the tooltip

 

body

The body of the tooltip

 

status_notifier_item_set_tooltip_title ()

void
status_notifier_item_set_tooltip_title
                               (StatusNotifierItem *sn,
                                const gchar *title);

Sets the title of the tooltip

The tooltip is composed of a title, a body, and an icon. Note that changing any of these will trigger a DBus signal NewToolTip (for hosts to refresh DBus property ToolTip), see status_notifier_item_freeze_tooltip() for changing more than one and only emitting one DBus signal at the end.

Parameters

sn

A StatusNotifierItem

 

title

The tooltip title

 

status_notifier_item_get_tooltip_title ()

gchar *
status_notifier_item_get_tooltip_title
                               (StatusNotifierItem *sn);

Returns the tooltip title

Parameters

Returns

A newly allocated string of the tooltip title, use g_free() when done


status_notifier_item_set_tooltip_body ()

void
status_notifier_item_set_tooltip_body (StatusNotifierItem *sn,
                                       const gchar *body);

Sets the body of the tooltip

This body can contain some markup, which consists of a small subset of XHTML. See http://www.notmart.org/misc/statusnotifieritem/markup.html for more.

The tooltip is composed of a title, a body, and an icon. Note that changing any of these will trigger a DBus signal NewToolTip (for hosts to refresh DBus property ToolTip), see status_notifier_item_freeze_tooltip() for changing more than one and only emitting one DBus signal at the end.

Parameters

sn

A StatusNotifierItem

 

body

The tooltip body

 

status_notifier_item_get_tooltip_body ()

gchar *
status_notifier_item_get_tooltip_body (StatusNotifierItem *sn);

Returns the tooltip body

Parameters

Returns

A newly allocated string of the tooltip body, use g_free() when done


status_notifier_item_set_item_is_menu ()

void
status_notifier_item_set_item_is_menu (StatusNotifierItem *sn,
                                       gboolean is_menu);

This is only an indication for the visualization (i.e. the StatusNotifierHost) as to how to handle user interactions.

Specifically, if TRUE it should prefer showing the menu (when set via “menu” or status_notifier_item_set_context_menu()) or trigger “context-menu” instead of “activate”

Parameters

sn

A StatusNotifierItem

 

is_menu

Whether or not sn only supports context menu

 

Since: 1.0.0


status_notifier_item_get_item_is_menu ()

gboolean
status_notifier_item_get_item_is_menu (StatusNotifierItem *sn);

Returns whether or not sn only supports context menu. See status_notifier_item_set_item_is_menu() for more.

Parameters

Returns

Whether or not sn only supports context menu

Since: 1.0.0


status_notifier_item_set_context_menu ()

gboolean
status_notifier_item_set_context_menu (StatusNotifierItem *sn,
                                       GObject *menu);

Exports specified context menu via dbus. If menu is set, g_object_ref_sink() will be used to take ownership. Also note that no “context_menu” signals will be emitted when a context menu is set/shared via DBus. If menu is NULL any current menu will be unset (and “context_menu” signals will be emitted as needed again).

Note that is dbusmenu support wasn't enabled during compilation, this function does nothing but returning FALSE, thus allowing you to fallback on handling the “context_menu” signal.

Parameters

sn

A StatusNotifierItem

 

menu

A GtkWidget of the menu to set as context menu or NULL.

[allow-none]

Returns

TRUE is dbusmenu support is available, else FALSE

Since: 1.0.0


status_notifier_item_get_context_menu ()

GObject *
status_notifier_item_get_context_menu (StatusNotifierItem *sn);

Returns the GtkWidget set as context menu, or NULL

Note that if dbusmenu support wasn't enabled during compilation it will always return NULL. See status_notifier_item_set_context_menu() for how to check.

Parameters

Returns

GtkWidget or NULL (no menu set, or no support compiled in).

[transfer none]

Since: 1.0.0


status_notifier_item_register ()

void
status_notifier_item_register (StatusNotifierItem *sn);

Registers sn to the StatusNotifierWatcher over DBus.

Once you have created your StatusNotifierItem you need to register it, so any host/visualization can use it and update their GUI as needed.

This function will connect to the StatusNotifierWatcher and make sure at least one StatusNotifierHost is registered. Then, it will register a new StatusNotifierItem on the session bus and register it with the watcher.

When done, property “state” will change to STATUS_NOTIFIER_STATE_REGISTERED. If something fails, signal “registration-failed” will be emitted, at which point you should fallback to using the systray.

However there are two possible types of failures: fatal and non-fatal ones. Fatal error means that “state” will be STATUS_NOTIFIER_STATE_FAILED and you can unref sn .

Non-fatal error means it will still be STATUS_NOTIFIER_STATE_REGISTERING as the registration process could still eventually succeed. For example, if there was no host registered on the watcher, as soon as signal StatusNotifierHostRegistered is emitted on the watcher, the registration process for sn will complete and “state” set to STATUS_NOTIFIER_STATE_REGISTERED, at which point you should stop using the systray.

This also means it is possible to have multiple signals “registration-failed” emitted on the same StatusNotifierItem.

Note that you can call status_notifier_item_register() after a fatal error occured, to try again. You can also unref sn while it is STATUS_NOTIFIER_STATE_REGISTERING safely.

Parameters


status_notifier_item_get_state ()

StatusNotifierState
status_notifier_item_get_state (StatusNotifierItem *sn);

Returns the DBus registration state of sn . See status_notifier_item_register() for more.

Parameters

Returns

The DBus registration state of sn

Types and Values

STATUS_NOTIFIER_ERROR

#define STATUS_NOTIFIER_ERROR               g_quark_from_static_string ("StatusNotifier error")

enum StatusNotifierError

Errors that can occur while trying to register the item. Note that errors other the StatusNotifierError might be returned.

Members

STATUS_NOTIFIER_ERROR_NO_CONNECTION

Failed to establish connection to register service on session bus

 

STATUS_NOTIFIER_ERROR_NO_NAME

Failed to acquire name for the item on the session bus

 

STATUS_NOTIFIER_ERROR_NO_WATCHER

No StatusNotifierWatcher found on the session bus

 

STATUS_NOTIFIER_ERROR_NO_HOST

No StatusNotifierHost registered with the StatusNotifierWatcher

 

enum StatusNotifierState

State in which a StatusNotifierItem can be. See status_notifier_item_register() for more

Members

STATUS_NOTIFIER_STATE_NOT_REGISTERED

Item hasn't yet been asked to register, i.e. no call to status_notifier_item_register() have been made yet

 

STATUS_NOTIFIER_STATE_REGISTERING

Item is in the process of registering. This state is also valid after “registration-failed” was emitted, if the item is waiting for possible "recovery" (e.g. if no host was registered on watcher, waiting for one to do so)

 

STATUS_NOTIFIER_STATE_REGISTERED

Item was sucessfully registered on DBus and StatusNotifierWatcher

 

STATUS_NOTIFIER_STATE_FAILED

Registration failed, with no possible pending recovery

 

enum StatusNotifierIcon

Possible icons that can be used on a status notifier item.

Members

STATUS_NOTIFIER_ICON

The icon that can be used by the visualization to identify the item.

 

STATUS_NOTIFIER_ATTENTION_ICON

The icon that can be used by the visualization when the item's status is STATUS_NOTIFIER_STATUS_NEEDS_ATTENTION.

 

STATUS_NOTIFIER_OVERLAY_ICON

This can be used by the visualization to indicate extra state information, for instance as an overlay for the main icon.

 

STATUS_NOTIFIER_TOOLTIP_ICON

The icon that can be used be the visualization in the tooltip of the item.

 

enum StatusNotifierCategory

The category of the status notifier item.

Members

STATUS_NOTIFIER_CATEGORY_APPLICATION_STATUS

The item describes the status of a generic application, for instance the current state of a media player. In the case where the category of the item can not be known, such as when the item is being proxied from another incompatible or emulated system, this can be used a sensible default fallback.

 

STATUS_NOTIFIER_CATEGORY_COMMUNICATIONS

The item describes the status of communication oriented applications, like an instant messenger or an email client.

 

STATUS_NOTIFIER_CATEGORY_SYSTEM_SERVICES

The item describes services of the system not seen as a stand alone application by the user, such as an indicator for the activity of a disk indexing service.

 

STATUS_NOTIFIER_CATEGORY_HARDWARE

The item describes the state and control of a particular hardware, such as an indicator of the battery charge or sound card volume control.

 

enum StatusNotifierStatus

The status of the status notifier item or its associated application.

Members

STATUS_NOTIFIER_STATUS_PASSIVE

The item doesn't convey important information to the user, it can be considered an "idle" status and is likely that visualizations will chose to hide it.

 

STATUS_NOTIFIER_STATUS_ACTIVE

The item is active, is more important that the item will be shown in some way to the user.

 

STATUS_NOTIFIER_STATUS_NEEDS_ATTENTION

The item carries really important information for the user, such as battery charge running out and is wants to incentive the direct user intervention. Visualizations should emphasize in some way the items with this status.

 

enum StatusNotifierScrollOrientation

The orientation of a scroll request performed on the representation of the item in the visualization.

Members

STATUS_NOTIFIER_SCROLL_ORIENTATION_HORIZONTAL

Scroll request was horizontal.

 

STATUS_NOTIFIER_SCROLL_ORIENTATION_VERTICAL

Scroll request was vertical.

 

struct StatusNotifierItem

struct StatusNotifierItem;

struct StatusNotifierItemClass

struct StatusNotifierItemClass {
    GObjectClass parent_class;

    /* signals */
    void            (*registration_failed)  (StatusNotifierItem     *sn,
                                             GError                 *error);

    gboolean        (*context_menu)         (StatusNotifierItem     *sn,
                                             gint                    x,
                                             gint                    y);
    gboolean        (*activate)             (StatusNotifierItem     *sn,
                                             gint                    x,
                                             gint                    y);
    gboolean        (*secondary_activate)   (StatusNotifierItem     *sn,
                                             gint                    x,
                                             gint                    y);
    gboolean        (*scroll)               (StatusNotifierItem     *sn,
                                             gint                    delta,
                                             StatusNotifierScrollOrientation orientation);
};

Members

registration_failed ()

When registering the item failed, e.g. because there's no StatusNotifierHost registered (yet); If this occurs, you should fallback to using the systray

 

context_menu ()

Item should show a context menu, this is typically a consequence of user input, such as mouse right click over the graphical representation of the item.

 

activate ()

Activation of the item was requested, this is typically a consequence of user input, such as mouse left click over the graphical representation of the item.

 

secondary_activate ()

Secondary and less important form of activation (compared to activate ) of the item was requested. This is typically a consequence of user input, such as mouse middle click over the graphical representation of the item.

 

scroll ()

The user asked for a scroll action. This is caused from input such as mouse wheel over the graphical representation of the item.

 

Property Details

The “attention-icon-name” property

  “attention-icon-name”      char *

This can be used by the visualization to indicate that the item is in STATUS_NOTIFIER_STATUS_NEEDS_ATTENTION status.

An icon can either be identified by its Freedesktop-compliant icon name, set by this property, or by the icon data itself, set by property “attention-icon-pixbuf”.

It is currently not possible to set both, as setting one will unset the other.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: NULL


The “attention-icon-pixbuf” property

  “attention-icon-pixbuf”    GdkPixbuf *

This can be used by the visualization to indicate that the item is in STATUS_NOTIFIER_STATUS_NEEDS_ATTENTION status.

An icon can either be identified by its Freedesktop-compliant icon name, set by property “attention-icon-name”, or by the icon data itself, set by this property.

It is currently not possible to set both, as setting one will unset the other.

Owner: StatusNotifierItem

Flags: Read / Write


The “attention-movie-name” property

  “attention-movie-name”     char *

In addition to the icon, the item can also specify an animation associated to the STATUS_NOTIFIER_STATUS_NEEDS_ATTENTION status.

This should be either a Freedesktop-compliant icon name or a full path. The visualization can chose between the movie or icon (or using neither of those) at its discretion.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: NULL


The “category” property

  “category”                 StatusNotifierCategory

Describes the category of this item.

Owner: StatusNotifierItem

Flags: Read / Write / Construct Only

Default value: STATUS_NOTIFIER_CATEGORY_APPLICATION_STATUS


The “id” property

  “id”                       char *

It's a name that should be unique for this application and consistent between sessions, such as the application name itself.

Owner: StatusNotifierItem

Flags: Read / Write / Construct Only

Default value: NULL


The “item-is-menu” property

  “item-is-menu”             gboolean

Whether or not this StatusNotifierItem only supports a context menu or not. See status_notifier_item_set_item_is_menu() for more.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: FALSE

Since: 1.0.0


The “main-icon-name” property

  “main-icon-name”           char *

The item can carry an icon that can be used by the visualization to identify the item.

An icon can either be identified by its Freedesktop-compliant icon name, set by this property, or by the icon data itself, set by the property “main-icon-pixbuf”.

It is currently not possible to set both, as setting one will unset the other.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: NULL


The “main-icon-pixbuf” property

  “main-icon-pixbuf”         GdkPixbuf *

The item can carry an icon that can be used by the visualization to identify the item.

An icon can either be identified by its Freedesktop-compliant icon name, set by property “main-icon-name”, or by the icon data itself, set by this property.

It is currently not possible to set both, as setting one will unset the other.

Owner: StatusNotifierItem

Flags: Read / Write


The “menu” property

  “menu”                     GObject *

A GtkMenu can be exposed via DBusMenu protocol to have native Look&Feel. When menu is exposed, no "context-menu" signals will be received.

Only writable if dbusmenu support was enabled during compilation. See status_notifier_item_set_context_menu() for how to check whether it is available or not.

Owner: StatusNotifierItem

Flags: Read / Write

Since: 1.0.0


The “overlay-icon-name” property

  “overlay-icon-name”        char *

This can be used by the visualization to indicate extra state information, for instance as an overlay for the main icon.

An icon can either be identified by its Freedesktop-compliant icon name, set by this property, or by the icon data itself, set by property “overlay-icon-pixbuf”.

It is currently not possible to set both, as setting one will unset the other.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: NULL


The “overlay-icon-pixbuf” property

  “overlay-icon-pixbuf”      GdkPixbuf *

This can be used by the visualization to indicate extra state information, for instance as an overlay for the main icon.

An icon can either be identified by its Freedesktop-compliant icon name, set by property “overlay-icon-name”, or by the icon data itself, set by this property.

It is currently not possible to set both, as setting one will unset the other.

Owner: StatusNotifierItem

Flags: Read / Write


The “state” property

  “state”                    StatusNotifierState

The state of the item, regarding its DBus registration on the StatusNotifierWatcher. After you've created the item, you need to call status_notifier_item_register() to have it registered via DBus on the watcher.

See status_notifier_item_register() for more.

Owner: StatusNotifierItem

Flags: Read

Default value: STATUS_NOTIFIER_STATE_NOT_REGISTERED


The “status” property

  “status”                   StatusNotifierStatus

Describes the status of this item or of the associated application.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: STATUS_NOTIFIER_STATUS_PASSIVE


The “title” property

  “title”                    char *

It's a name that describes the application, it can be more descriptive than “id”.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: NULL


The “tooltip-body” property

  “tooltip-body”             char *

A tooltip can be defined on the item; It can be used by the visualization to show as a tooltip (or by any other mean it considers appropriate).

The tooltip is composed of a title, a body, and an icon. Note that changing any of these will trigger a DBus signal NewToolTip (for hosts to refresh DBus property ToolTip), see status_notifier_item_freeze_tooltip() for changing more than one and only emitting one DBus signal at the end.

This body can contain some markup, which consists of a small subset of XHTML. See https://freedesktop.org/wiki/Specifications/StatusNotifierItem/Markup/ for more.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: NULL


The “tooltip-icon-name” property

  “tooltip-icon-name”        char *

A tooltip can be defined on the item; It can be used by the visualization to show as a tooltip (or by any other mean it considers appropriate).

The tooltip is composed of a title, a body, and an icon. Note that changing any of these will trigger a DBus signal NewToolTip (for hosts to refresh DBus property ToolTip), see status_notifier_item_freeze_tooltip() for changing more than one and only emitting one DBus signal at the end.

The icon can either be identified by its Freedesktop-compliant icon name, set by this property, or by the icon data itself, set by property “tooltip-icon-pixbuf”.

It is currently not possible to set both, as setting one will unset the other.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: NULL


The “tooltip-icon-pixbuf” property

  “tooltip-icon-pixbuf”      GdkPixbuf *

A tooltip can be defined on the item; It can be used by the visualization to show as a tooltip (or by any other mean it considers appropriate).

The tooltip is composed of a title, a body, and an icon. Note that changing any of these will trigger a DBus signal NewToolTip (for hosts to refresh DBus property ToolTip), see status_notifier_item_freeze_tooltip() for changing more than one and only emitting one DBus signal at the end.

The icon can either be identified by its Freedesktop-compliant icon name, set by property “tooltip-icon-name”, or by the icon data itself, set by this property.

It is currently not possible to set both, as setting one will unset the other.

Owner: StatusNotifierItem

Flags: Read / Write


The “tooltip-title” property

  “tooltip-title”            char *

A tooltip can be defined on the item; It can be used by the visualization to show as a tooltip (or by any other mean it considers appropriate).

The tooltip is composed of a title, a body, and an icon. Note that changing any of these will trigger a DBus signal NewToolTip (for hosts to refresh DBus property ToolTip), see status_notifier_item_freeze_tooltip() for changing more than one and only emitting one DBus signal at the end.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: NULL


The “window-id” property

  “window-id”                guint

It's the windowing-system dependent identifier for a window, the application can chose one of its windows to be available trough this property or just set 0 if it's not interested.

Owner: StatusNotifierItem

Flags: Read / Write

Default value: 0

Signal Details

The “activate” signal

gboolean
user_function (StatusNotifierItem *sn,
               int                 x,
               int                 y,
               gpointer            user_data)

Emitted when the Activate method was called on the item. Activation of the item was requested, this is typically a consequence of user input, such as mouse left click over the graphical representation of the item.

x and y are to be considered an hint to the item about where to show the context menu.

Parameters

sn

The StatusNotifierItem

 

x

screen coordinates X

 

y

screen coordinates Y

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “context-menu” signal

gboolean
user_function (StatusNotifierItem *sn,
               int                 x,
               int                 y,
               gpointer            user_data)

Emitted when the ContextMenu method was called on the item. Item should then show a context menu, this is typically a consequence of user input, such as mouse right click over the graphical representation of the item.

x and y are to be considered an hint to the item about where to show the context menu.

Parameters

sn

The StatusNotifierItem

 

x

screen coordinates X

 

y

screen coordinates Y

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “registration-failed” signal

void
user_function (StatusNotifierItem *sn,
               GError             *error,
               gpointer            user_data)

This signal is emited after a call to status_notifier_item_register() when registering the item eventually failed (e.g. if there wasn't (yet) any StatusNotifierHost registered.)

When this happens, you should fallback to using the systray. You should also check “state” as it might still be STATUS_NOTIFIER_STATE_REGISTERING if the registration remains eventually possible (e.g. waiting for a StatusNotifierHost to register)

See status_notifier_item_register() for more.

Parameters

sn

The StatusNotifierItem

 

error

A GError with the reason of failure

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “scroll” signal

gboolean
user_function (StatusNotifierItem             *sn,
               int                             delta,
               StatusNotifierScrollOrientation orientation,
               gpointer                        user_data)

Emitted when the Scroll method was called on the item. The user asked for a scroll action. This is caused from input such as mouse wheel over the graphical representation of the item.

Parameters

sn

The StatusNotifierItem

 

delta

the amount of scroll

 

orientation

orientation of the scroll request

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “secondary-activate” signal

gboolean
user_function (StatusNotifierItem *sn,
               int                 x,
               int                 y,
               gpointer            user_data)

Emitted when the SecondaryActivate method was called on the item. Secondary and less important form of activation (compared to “activate”) of the item was requested. This is typically a consequence of user input, such as mouse middle click over the graphical representation of the item.

x and y are to be considered an hint to the item about where to show the context menu.

Parameters

sn

The StatusNotifierItem

 

x

screen coordinates X

 

y

screen coordinates Y

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last