Class
GtkStatusIcon
Description [src]
class Gtk.StatusIcon : GObject.Object
{
GtkStatusIconPrivate* priv
}The “system tray” or notification area is normally used for transient icons that indicate some special state. For example, a system tray icon might appear to tell the user that they have new mail, or have an incoming instant message, or something along those lines. The basic idea is that creating an icon in the notification area is less annoying than popping up a dialog.
A GtkStatusIcon object can be used to display an icon in a “system tray”.
The icon can have a tooltip, and the user can interact with it by
activating it or popping up a context menu.
It is very important to notice that status icons depend on the existence
of a notification area being available to the user; you should not use status
icons as the only way to convey critical information regarding your application,
as the notification area may not exist on the user’s environment, or may have
been removed. You should always check that a status icon has been embedded into
a notification area by using gtk_status_icon_is_embedded(), and gracefully
recover if the function returns FALSE.
On X11, the implementation follows the FreeDesktop System Tray Specification. Implementations of the “tray” side of this specification can be found e.g. in the GNOME 2 and KDE panel applications.
Note that a GtkStatusIcon is not a widget, but just a GObject. Making it a
widget would be impractical, since the system tray on Windows doesn’t allow
to embed arbitrary widgets.
GtkStatusIcon has been deprecated in 3.14. You should consider using
notifications or more modern platform-specific APIs instead. GLib provides
the GNotification API which works well with GtkApplication on multiple
platforms and environments, and should be the preferred mechanism to notify
the users of transient status updates. See this HowDoI
for code examples.
Constructors
gtk_status_icon_new_from_file
Creates a status icon displaying the file filename.
deprecated: 3.14 since: 2.10
gtk_status_icon_new_from_gicon
Creates a status icon displaying a GIcon. If the icon is a
themed icon, it will be updated when the theme changes.
deprecated: 3.14 since: 2.14
gtk_status_icon_new_from_icon_name
Creates a status icon displaying an icon from the current icon theme. If the current icon theme is changed, the icon will be updated appropriately.
deprecated: 3.14 since: 2.10
gtk_status_icon_new_from_pixbuf
Creates a status icon displaying pixbuf.
deprecated: 3.14 since: 2.10
gtk_status_icon_new_from_stock
Creates a status icon displaying a stock icon. Sample stock icon
names are #GTK_STOCK_OPEN, #GTK_STOCK_QUIT. You can register your
own stock icon names, see gtk_icon_factory_add_default() and gtk_icon_factory_add().
deprecated: 3.14 since: 2.10
Functions
gtk_status_icon_position_menu
Menu positioning function to use with gtk_menu_popup()
to position menu aligned to the status icon user_data.
deprecated: 3.14 since: 2.10
Instance methods
gtk_status_icon_get_geometry
Obtains information about the location of the status icon on screen. This information can be used to e.g. position popups like notification bubbles.
deprecated: 3.14 since: 2.10
gtk_status_icon_get_gicon
Retrieves the GIcon being displayed by the GtkStatusIcon.
The storage type of the status icon must be GTK_IMAGE_EMPTY or
GTK_IMAGE_GICON (see gtk_status_icon_get_storage_type()).
The caller of this function does not own a reference to the
returned GIcon.
deprecated: 3.14 since: 2.14
gtk_status_icon_get_has_tooltip
Returns the current value of the has-tooltip property.
See GtkStatusIcon:has-tooltip for more information.
deprecated: 3.14 since: 2.16
gtk_status_icon_get_icon_name
Gets the name of the icon being displayed by the GtkStatusIcon.
The storage type of the status icon must be GTK_IMAGE_EMPTY or
GTK_IMAGE_ICON_NAME (see gtk_status_icon_get_storage_type()).
The returned string is owned by the GtkStatusIcon and should not
be freed or modified.
deprecated: 3.14 since: 2.10
gtk_status_icon_get_pixbuf
Gets the GdkPixbuf being displayed by the GtkStatusIcon.
The storage type of the status icon must be GTK_IMAGE_EMPTY or
GTK_IMAGE_PIXBUF (see gtk_status_icon_get_storage_type()).
The caller of this function does not own a reference to the
returned pixbuf.
deprecated: 3.14 since: 2.10
gtk_status_icon_get_screen
Returns the GdkScreen associated with status_icon.
deprecated: 3.14 since: 2.12
gtk_status_icon_get_size
Gets the size in pixels that is available for the image. Stock icons and named icons adapt their size automatically if the size of the notification area changes. For other storage types, the size-changed signal can be used to react to size changes.
deprecated: 3.14 since: 2.10
gtk_status_icon_get_stock
Gets the id of the stock icon being displayed by the GtkStatusIcon.
The storage type of the status icon must be GTK_IMAGE_EMPTY or
GTK_IMAGE_STOCK (see gtk_status_icon_get_storage_type()).
The returned string is owned by the GtkStatusIcon and should not
be freed or modified.
deprecated: 3.10 since: 2.10
gtk_status_icon_get_storage_type
Gets the type of representation being used by the GtkStatusIcon
to store image data. If the GtkStatusIcon has no image data,
the return value will be GTK_IMAGE_EMPTY.
deprecated: 3.14 since: 2.10
gtk_status_icon_get_title
Gets the title of this tray icon. See gtk_status_icon_set_title().
deprecated: 3.14 since: 2.18
gtk_status_icon_get_tooltip_markup
Gets the contents of the tooltip for status_icon.
deprecated: 3.14 since: 2.16
gtk_status_icon_get_tooltip_text
Gets the contents of the tooltip for status_icon.
deprecated: 3.14 since: 2.16
gtk_status_icon_get_visible
Returns whether the status icon is visible or not. Note that being visible does not guarantee that the user can actually see the icon, see also gtk_status_icon_is_embedded().
deprecated: 3.14 since: 2.10
gtk_status_icon_get_x11_window_id
This function is only useful on the X11/freedesktop.org platform.
deprecated: 3.14 since: 2.14
gtk_status_icon_is_embedded
Returns whether the status icon is embedded in a notification area.
deprecated: 3.14 since: 2.10
gtk_status_icon_set_from_file
Makes status_icon display the file filename.
See gtk_status_icon_new_from_file() for details.
deprecated: 3.14 since: 2.10
gtk_status_icon_set_from_gicon
Makes status_icon display the GIcon.
See gtk_status_icon_new_from_gicon() for details.
deprecated: 3.14 since: 2.14
gtk_status_icon_set_from_icon_name
Makes status_icon display the icon named icon_name from the
current icon theme.
See gtk_status_icon_new_from_icon_name() for details.
deprecated: 3.14 since: 2.10
gtk_status_icon_set_from_pixbuf
Makes status_icon display pixbuf.
See gtk_status_icon_new_from_pixbuf() for details.
deprecated: 3.14 since: 2.10
gtk_status_icon_set_from_stock
Makes status_icon display the stock icon with the id stock_id.
See gtk_status_icon_new_from_stock() for details.
deprecated: 3.10 since: 2.10
gtk_status_icon_set_has_tooltip
Sets the has-tooltip property on status_icon to has_tooltip.
See GtkStatusIcon:has-tooltip for more information.
deprecated: 3.14 since: 2.16
gtk_status_icon_set_name
Sets the name of this tray icon. This should be a string identifying this icon. It is may be used for sorting the icons in the tray and will not be shown to the user.
deprecated: 3.14 since: 2.20
gtk_status_icon_set_screen
Sets the GdkScreen where status_icon is displayed; if
the icon is already mapped, it will be unmapped, and
then remapped on the new screen.
deprecated: 3.14 since: 2.12
gtk_status_icon_set_title
Sets the title of this tray icon. This should be a short, human-readable, localized string describing the tray icon. It may be used by tools like screen readers to render the tray icon.
deprecated: 3.14 since: 2.18
gtk_status_icon_set_tooltip_markup
Sets markup as the contents of the tooltip, which is marked up with
the [Pango text markup language][PangoMarkupFormat].
deprecated: 3.14 since: 2.16
gtk_status_icon_set_tooltip_text
Sets text as the contents of the tooltip.
deprecated: 3.14 since: 2.16
Properties
Gtk.StatusIcon:gicon
The GIcon displayed in the GtkStatusIcon. For themed icons,
the image will be updated automatically if the theme changes.
since: 2.14
Gtk.StatusIcon:has-tooltip
Enables or disables the emission of GtkStatusIcon::query-tooltip on
status_icon. A value of TRUE indicates that status_icon can have a
tooltip, in this case the status icon will be queried using
GtkStatusIcon::query-tooltip to determine whether it will provide a
tooltip or not.
since: 2.16
Gtk.StatusIcon:orientation
The orientation of the tray in which the statusicon is embedded.
since: 2.12
Gtk.StatusIcon:title
The title of this tray icon. This should be a short, human-readable, localized string describing the tray icon. It may be used by tools like screen readers to render the tray icon.
since: 2.18
Gtk.StatusIcon:tooltip-markup
Sets the text of tooltip to be the given string, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_tooltip_set_markup().
since: 2.16
Signals
Gtk.StatusIcon::activate
Gets emitted when the user activates the status icon. If and how status icons can activated is platform-dependent.
since: 2.10
Gtk.StatusIcon::button-press-event
The ::button-press-event signal will be emitted when a button (typically from a mouse) is pressed.
since: 2.14
Gtk.StatusIcon::button-release-event
The ::button-release-event signal will be emitted when a button (typically from a mouse) is released.
since: 2.14
Gtk.StatusIcon::popup-menu
Gets emitted when the user brings up the context menu of the status icon. Whether status icons can have context menus and how these are activated is platform-dependent.
since: 2.10
Gtk.StatusIcon::query-tooltip
Emitted when the hover timeout has expired with the
cursor hovering above status_icon; or emitted when status_icon got
focus in keyboard mode.
since: 2.16
Gtk.StatusIcon::scroll-event
The ::scroll-event signal is emitted when a button in the 4 to 7 range is pressed. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned.
since: 2.16
Gtk.StatusIcon::size-changed
Gets emitted when the size available for the image changes, e.g. because the notification area got resized.
since: 2.10
Signals inherited from GObject (1)
GObject::notify
The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.
Class structure
struct GtkStatusIconClass {
GObjectClass parent_class;
void (* activate) (
GtkStatusIcon* status_icon
);
void (* popup_menu) (
GtkStatusIcon* status_icon,
guint button,
guint32 activate_time
);
gboolean (* size_changed) (
GtkStatusIcon* status_icon,
gint size
);
gboolean (* button_press_event) (
GtkStatusIcon* status_icon,
GdkEventButton* event
);
gboolean (* button_release_event) (
GtkStatusIcon* status_icon,
GdkEventButton* event
);
gboolean (* scroll_event) (
GtkStatusIcon* status_icon,
GdkEventScroll* event
);
gboolean (* query_tooltip) (
GtkStatusIcon* status_icon,
gint x,
gint y,
gboolean keyboard_mode,
GtkTooltip* tooltip
);
void (* __gtk_reserved1) (
void
);
void (* __gtk_reserved2) (
void
);
void (* __gtk_reserved3) (
void
);
void (* __gtk_reserved4) (
void
);
}No description available.
Class members
parent_class: GObjectClassNo description available.
activate: void (* activate) ( GtkStatusIcon* status_icon )No description available.
popup_menu: void (* popup_menu) ( GtkStatusIcon* status_icon, guint button, guint32 activate_time )No description available.
size_changed: gboolean (* size_changed) ( GtkStatusIcon* status_icon, gint size )No description available.
button_press_event: gboolean (* button_press_event) ( GtkStatusIcon* status_icon, GdkEventButton* event )No description available.
button_release_event: gboolean (* button_release_event) ( GtkStatusIcon* status_icon, GdkEventButton* event )No description available.
scroll_event: gboolean (* scroll_event) ( GtkStatusIcon* status_icon, GdkEventScroll* event )No description available.
query_tooltip: gboolean (* query_tooltip) ( GtkStatusIcon* status_icon, gint x, gint y, gboolean keyboard_mode, GtkTooltip* tooltip )No description available.
__gtk_reserved1: void (* __gtk_reserved1) ( void )No description available.
__gtk_reserved2: void (* __gtk_reserved2) ( void )No description available.
__gtk_reserved3: void (* __gtk_reserved3) ( void )No description available.
__gtk_reserved4: void (* __gtk_reserved4) ( void )No description available.