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.

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

## 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