XAppStatusIcon: XApp Reference Manual

## XAppStatusIcon XAppStatusIcon — Broadcasts status information over DBUS |

## Functions

XAppStatusIcon * | xapp_status_icon_new ()
void | xapp_status_icon_set_name ()
void | xapp_status_icon_set_icon_name ()
void | xapp_status_icon_set_tooltip_text ()
void | xapp_status_icon_set_label ()
void | xapp_status_icon_set_visible ()
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 ()
gboolean | xapp_status_icon_any_monitors ()

## Properties

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 | state-changed | Action

## Types and Values

#define | XAPP_TYPE_STATUS_ICON
enum | XAppStatusIconState
| XAppStatusIcon

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