XAppStatusIcon: XApp Reference Manual

XAppStatusIcon

XAppStatusIcon — Broadcasts status information over DBUS

Functions

XAppStatusIcon *	xapp_status_icon_new ()
XAppStatusIcon *	xapp_status_icon_new_with_name ()
void	xapp_status_icon_set_name ()
void	xapp_status_icon_set_icon_name ()
gint	xapp_status_icon_get_icon_size ()
void	xapp_status_icon_set_tooltip_text ()
void	xapp_status_icon_set_label ()
void	xapp_status_icon_set_visible ()
gboolean	xapp_status_icon_get_visible ()
void	xapp_status_icon_popup_menu ()
void	xapp_status_icon_set_primary_menu ()
GtkWidget *	xapp_status_icon_get_primary_menu ()
void	xapp_status_icon_set_secondary_menu ()
GtkWidget *	xapp_status_icon_get_secondary_menu ()
XAppStatusIconState	xapp_status_icon_get_state ()
void	xapp_status_icon_set_metadata ()
gboolean	xapp_status_icon_any_monitors ()

Properties

int	icon-size	Read / Write
char *	name	Read / Write / Construct
GtkWidget *	primary-menu	Read / Write
GtkWidget *	secondary-menu	Read / Write

Signals

void	activate	Action
void	button-press-event	Action
void	button-release-event	Action
void	scroll-event	Action
void	state-changed	Action

Types and Values

#define	XAPP_TYPE_STATUS_ICON
enum	XAppStatusIconState
enum	XAppScrollDirection
	XAppStatusIcon

Object Hierarchy

    GEnum
    ├── XAppScrollDirection
    ╰── 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_new_with_name ()

XAppStatusIcon *
xapp_status_icon_new_with_name (const gchar *name);

Creates a new XAppStatusIcon instance and sets its name to name.

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_get_icon_size ()

gint
xapp_status_icon_get_icon_size (XAppStatusIcon *icon);

Parameters

icon

a XAppStatusIcon

Returns

The desired icon size - usually set by the host based on panel size. This is not what it's guaranteed to get, and this is really only useful when receiving absolute icon paths from the client app.

Since: 1.8

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_get_visible ()

gboolean
xapp_status_icon_get_visible (XAppStatusIcon *icon);

Returns whether or not the icon should currently be visible.

Parameters

icon

an XAppStatusIcon

Returns

the current visibility state.

Since: 1.8.5

xapp_status_icon_popup_menu ()

void
xapp_status_icon_popup_menu (XAppStatusIcon *icon,
                             GtkMenu *menu,
                             gint x,
                             gint y,
                             guint button,
                             guint _time,
                             gint panel_position);

Pop up menu using the positioning arguments. These arguments should be those provided by a “button-release-event”.

Parameters

icon	an XAppStatusIcon
menu	A GtkMenu to display when the primary mouse button is released.	[nullable]
x	The x anchor position for the menu.
y	The y anchor position for the menu.
button	The button used to initiate this action (or 0)
_time	The event time (or 0)
panel_position	The GtkPositionType for the position of the icon.

Since: 1.8.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_set_metadata ()

void
xapp_status_icon_set_metadata (XAppStatusIcon *icon,
                               const gchar *metadata);

Sets metadata to pass to the icon proxy for an applet's use. Right now this is only so xapp-sn-watcher can tell the applets when the icon is originating from appindicator so panel button 'highlighting' can behave correctly.

Parameters

icon	an XAppStatusIcon
metadata	A json-formatted string of key:values.	[nullable]

Since: 1.8.7

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.

enum XAppScrollDirection

Represents the direction of icon scroll events.

Members

XAPP_SCROLL_UP	Scroll theoretical content up.
XAPP_SCROLL_DOWN	Scroll theoretical content down.
XAPP_SCROLL_LEFT	Scroll theoretical content left.
XAPP_SCROLL_RIGHT	Scroll theoretical content right.

XAppStatusIcon

typedef struct _XAppStatusIcon XAppStatusIcon;

Property Details

The `“icon-size”` property

  “icon-size”                int

The icon size that is preferred by icon monitor/host - this is usually a product of some calculation based on the panel size. It can be used by the client to size an icon to be saved as a file and its path sent to the host.

If this value is 0 it has not been set, and its value can be unreliable if the host has multiple XAppStatusIconMonitors active.

Owner: XAppStatusIcon

Flags: Read / Write

Allowed values: [0,96]

Default value: 0

The `“name”` property

  “name”                     char *

The name of the icon for sorting purposes. If this is in the form of 'org.x.StatusIcon.foo` and set immediately upon creation of the icon, it will also attempt to own this dbus name; this can be useful in sandboxed environments where a well-defined name is required. If additional icons are created, only the name given to the initial one will be used for dbus, though different names can still affect the sort order. This is set to the value of g_get_prgname() if no other name is provided.

Owner: XAppStatusIcon

Flags: Read / Write / Construct

Default value: NULL

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.

Owner: XAppStatusIcon

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.

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

Owner: XAppStatusIcon

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,
               int             x,
               int             y,
               guint           button,
               guint           time,
               int             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,
               int             x,
               int             y,
               guint           button,
               guint           time,
               int             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 `“scroll-event”` signal

void
user_function (XAppStatusIcon     *icon,
               int                 amount,
               XAppScrollDirection direction,
               guint               time,
               gpointer            user_data)

Gets emitted when the user uses the mouse scroll wheel over the status icon. For the most part, amounts will always be 1, unless an applet supports smooth scrolling. Generally the direction value is most important.

Parameters

icon	The XAppStatusIcon
amount	The amount of movement for the scroll event
direction	the XAppScrollDirection of the scroll event
time	The time supplied by the event, or 0
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

XAppStatusIcon

Functions

Properties

Signals

Types and Values

Object Hierarchy

Description

Functions

xapp_status_icon_new ()

Returns

xapp_status_icon_new_with_name ()

Returns

xapp_status_icon_set_name ()

Parameters

xapp_status_icon_set_icon_name ()

Parameters

xapp_status_icon_get_icon_size ()

Parameters

Returns

xapp_status_icon_set_tooltip_text ()

Parameters

xapp_status_icon_set_label ()

Parameters

xapp_status_icon_set_visible ()

Parameters

xapp_status_icon_get_visible ()

Parameters

Returns

xapp_status_icon_popup_menu ()

Parameters

xapp_status_icon_set_primary_menu ()

Parameters

xapp_status_icon_get_primary_menu ()

Parameters

Returns

xapp_status_icon_set_secondary_menu ()

Parameters

xapp_status_icon_get_secondary_menu ()

Parameters

Returns

xapp_status_icon_get_state ()

Parameters

Returns

xapp_status_icon_set_metadata ()

Parameters

xapp_status_icon_any_monitors ()

Returns

Types and Values

XAPP_TYPE_STATUS_ICON

enum XAppStatusIconState

Members

enum XAppScrollDirection

Members

XAppStatusIcon

Property Details

The “icon-size” property

The “name” property

The “primary-menu” property

The “secondary-menu” property

Signal Details

The “activate” signal

Parameters

The “button-press-event” signal

Parameters

The “button-release-event” signal

Parameters

The “scroll-event” signal

Parameters

The “state-changed” signal

Parameters

The `“icon-size”` property

The `“name”` property

The `“primary-menu”` property

The `“secondary-menu”` property

The `“activate”` signal

The `“button-press-event”` signal

The `“button-release-event”` signal

The `“scroll-event”` signal

The `“state-changed”` signal