XAppStatusIcon

XAppStatusIcon — Broadcasts status information over DBUS

Functions

Properties

GtkWidget * primary-menu Read / Write
GtkWidget * secondary-menu Read / Write

Signals

Types and Values

Object Hierarchy

    GEnum
    ╰── XAppStatusIconState
    GObject
    ╰── XAppStatusIcon

Description

The XAppStatusIcon allows applications to share status info about themselves. It replaces the obsolete and very similar Gtk.StatusIcon widget.

If used in an environment where no applet is handling XAppStatusIcons, the XAppStatusIcon delegates its calls to a Gtk.StatusIcon.

Functions

xapp_status_icon_new ()

XAppStatusIcon *
xapp_status_icon_new (void);

Creates a new XAppStatusIcon instance

Returns

a new XAppStatusIcon. Use g_object_unref when finished.

[transfer full]

Since: 1.6


xapp_status_icon_set_name ()

void
xapp_status_icon_set_name (XAppStatusIcon *icon,
                           const gchar *name);

Sets the status icon name. This is not shown to users.

Parameters

icon

a XAppStatusIcon

 

name

a name (this defaults to the name of the application, if not set)

 

Since: 1.6


xapp_status_icon_set_icon_name ()

void
xapp_status_icon_set_icon_name (XAppStatusIcon *icon,
                                const gchar *icon_name);

Sets the icon name or local path to use.

Parameters

icon

a XAppStatusIcon

 

icon_name

An icon name or absolute path to an icon.

 

Since: 1.6


xapp_status_icon_set_tooltip_text ()

void
xapp_status_icon_set_tooltip_text (XAppStatusIcon *icon,
                                   const gchar *tooltip_text);

Sets the tooltip text

Parameters

icon

a XAppStatusIcon

 

tooltip_text

the text to show in the tooltip

 

Since: 1.6


xapp_status_icon_set_label ()

void
xapp_status_icon_set_label (XAppStatusIcon *icon,
                            const gchar *label);

Sets a label, shown beside the icon

Parameters

icon

a XAppStatusIcon

 

label

some text

 

Since: 1.6


xapp_status_icon_set_visible ()

void
xapp_status_icon_set_visible (XAppStatusIcon *icon,
                              const gboolean visible);

Sets the visibility of the status icon

Parameters

icon

a XAppStatusIcon

 

visible

whether or not the status icon should be visible

 

Since: 1.6


xapp_status_icon_set_primary_menu ()

void
xapp_status_icon_set_primary_menu (XAppStatusIcon *icon,
                                   GtkMenu *menu);

See the “primary-menu” property for details

Parameters

icon

an XAppStatusIcon

 

menu

A GtkMenu to display when the primary mouse button is released.

[nullable]

Since: 1.6


xapp_status_icon_get_primary_menu ()

GtkWidget *
xapp_status_icon_get_primary_menu (XAppStatusIcon *icon);

Returns a pointer to a GtkMenu that was set previously for the primary mouse button. If no menu was set, this returns NULL.

Parameters

icon

an XAppStatusIcon

 

Returns

the GtkMenu or NULL if none was set.

[transfer none]

Since: 1.6


xapp_status_icon_set_secondary_menu ()

void
xapp_status_icon_set_secondary_menu (XAppStatusIcon *icon,
                                     GtkMenu *menu);

See the “secondary-menu” property for details

Parameters

icon

an XAppStatusIcon

 

menu

A GtkMenu to display when the primary mouse button is released.

[nullable]

Since: 1.6


xapp_status_icon_get_secondary_menu ()

GtkWidget *
xapp_status_icon_get_secondary_menu (XAppStatusIcon *icon);

Returns a pointer to a GtkMenu that was set previously for the secondary mouse button. If no menu was set, this returns NULL.

Parameters

icon

an XAppStatusIcon

 

Returns

the GtkMenu or NULL if none was set.

[transfer none]

Since: 1.6


xapp_status_icon_get_state ()

XAppStatusIconState
xapp_status_icon_get_state (XAppStatusIcon *icon);

Gets the current XAppStatusIconState of icon. The state is determined by whether the icon is being displayed by an XAppStatusMonitor client, a fallback tray icon, or not being displayed at all.

See XAppStatusIconState for more details.

Parameters

icon

an XAppStatusIcon

 

Returns

the icon's state.

Since: 1.6


xapp_status_icon_any_monitors ()

gboolean
xapp_status_icon_any_monitors (void);

Looks for the existence of any active XAppStatusIconMonitors on the bus.

Returns

TRUE if at least one monitor was found.

Since: 1.6

Types and Values

XAPP_TYPE_STATUS_ICON

#define XAPP_TYPE_STATUS_ICON            (xapp_status_icon_get_type ())

enum XAppStatusIconState

Members

XAPP_STATUS_ICON_STATE_NATIVE

The XAppStatusIcon is currently being handled by an XAppStatusIconMonitor (usually in an applet).

 

XAPP_STATUS_ICON_STATE_FALLBACK

The XAppStatusIcon is currently being handled by a legacy system tray implementation (using GtkStatusIcon).

 

XAPP_STATUS_ICON_STATE_NO_SUPPORT

The XAppStatusIcon is not currently being handled by any kind of status icon implementation.

 

XAppStatusIcon

typedef struct _XAppStatusIcon XAppStatusIcon;

Property Details

The “primary-menu” property

  “primary-menu”             GtkWidget *

A GtkMenu to use when requested by the remote monitor via a left (or primary) click.

When this property is not NULL, the menu will be automatically positioned and displayed during a primary button release.

When this property IS NULL, the “activate” will be sent for primary button presses.

In both cases, the “button-press-event” and “button-release-events” will be fired like normal.

Setting this will remove any floating reference to the menu and assume ownership. As a result, it is not necessary to maintain a reference to it in the parent application (or unref it when finished with it - if you wish to replace the menu, simply call this method again with a new menu.

The same GtkMenu widget can be set as both the primary and secondary.

Flags: Read / Write


The “secondary-menu” property

  “secondary-menu”           GtkWidget *

A GtkMenu to use when requested by the remote monitor via a right (or secondary) click.

When this property is not NULL, the menu will be automatically positioned and displayed during a secondary button release.

When this property IS NULL, the “activate” will be sent for secondary button presses.

In both cases, the “button-press-event” and “button-release-events” will be fired like normal.

Setting this will remove any floating reference to the menu and assume ownership. As a result, it is not necessary to maintain a reference to it in the parent application (or unref it when finished with it - if you wish to replace the menu, simply call this method again with a new menu.

The same GtkMenu widget can be set as both the primary and secondary.

Flags: Read / Write

Signal Details

The “activate” signal

void
user_function (XAppStatusIcon *icon,
               guint           button,
               guint           time,
               gpointer        user_data)

Gets emitted when the user activates the status icon. If the XAppStatusIcon:primary-menu or XAppStatusIcon:secondary-menu is not NULL, this signal is skipped for the respective button presses. A middle button click will always send this signal when pressed.

Parameters

icon

The XAppStatusIcon

 

button

The button that was pressed

 

time

The time supplied by the event, or 0

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “button-press-event” signal

void
user_function (XAppStatusIcon *icon,
               gint            x,
               gint            y,
               guint           button,
               guint           time,
               gint            panel_position,
               gpointer        user_data)

Gets emitted when there is a button press received from an applet

Parameters

icon

The XAppStatusIcon

 

x

The absolute x position to use for menu positioning

 

y

The absolute y position to use for menu positioning

 

button

The button that was pressed

 

time

The time supplied by the event, or 0

 

panel_position

The GtkPositionType to use for menu positioning

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “button-release-event” signal

void
user_function (XAppStatusIcon *icon,
               gint            x,
               gint            y,
               guint           button,
               guint           time,
               gint            panel_position,
               gpointer        user_data)

Gets emitted when there is a button release received from an applet

Parameters

icon

The XAppStatusIcon

 

x

The absolute x position to use for menu positioning

 

y

The absolute y position to use for menu positioning

 

button

The button that was released

 

time

The time supplied by the event, or 0

 

panel_position

The GtkPositionType to use for menu positioning

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “state-changed” signal

void
user_function (XAppStatusIcon     *icon,
               XAppStatusIconState new_state,
               gpointer            user_data)

Gets emitted when the state of the icon changes. If you wish to react to changes in how the status icon is being handled (perhaps to alter the menu or other click behavior), you should connect to this - see XAppStatusIconState for more details.

Parameters

icon

The XAppStatusIcon

 

new_state

The new XAppStatusIconState of the icon

 

user_data

user data set when the signal handler was connected.

 

Flags: Action