Description
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.
Functions
gtk_status_icon_new ()
GtkStatusIcon *
gtk_status_icon_new (void);
gtk_status_icon_new has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications
Creates an empty status icon object.
Since: 2.10
gtk_status_icon_new_from_pixbuf ()
GtkStatusIcon *
gtk_status_icon_new_from_pixbuf (GdkPixbuf *pixbuf);
gtk_status_icon_new_from_pixbuf has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications
Creates a status icon displaying pixbuf
.
The image will be scaled down to fit in the available
space in the notification area, if necessary.
Since: 2.10
gtk_status_icon_new_from_file ()
GtkStatusIcon *
gtk_status_icon_new_from_file (const gchar *filename);
gtk_status_icon_new_from_file has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications
Creates a status icon displaying the file filename
.
The image will be scaled down to fit in the available
space in the notification area, if necessary.
Since: 2.10
gtk_status_icon_new_from_icon_name ()
GtkStatusIcon *
gtk_status_icon_new_from_icon_name (const gchar *icon_name);
gtk_status_icon_new_from_icon_name has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications
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.
Since: 2.10
gtk_status_icon_new_from_gicon ()
GtkStatusIcon *
gtk_status_icon_new_from_gicon (GIcon *icon);
gtk_status_icon_new_from_gicon has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications
Creates a status icon displaying a GIcon. If the icon is a
themed icon, it will be updated when the theme changes.
Since: 2.14
gtk_status_icon_set_from_icon_name ()
void
gtk_status_icon_set_from_icon_name (GtkStatusIcon *status_icon,
const gchar *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.
Since: 2.10
gtk_status_icon_get_storage_type ()
GtkImageType
gtk_status_icon_get_storage_type (GtkStatusIcon *status_icon);
gtk_status_icon_get_storage_type has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function, and GNotification only supports GIcon
instances
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.
Returns
the image representation being used
Since: 2.10
gtk_status_icon_get_pixbuf ()
GdkPixbuf *
gtk_status_icon_get_pixbuf (GtkStatusIcon *status_icon);
gtk_status_icon_get_pixbuf has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
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.
Returns
the displayed pixbuf,
or NULL if the image is empty.
[nullable][transfer none]
Since: 2.10
gtk_status_icon_get_gicon ()
GIcon *
gtk_status_icon_get_gicon (GtkStatusIcon *status_icon);
gtk_status_icon_get_gicon has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
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.
If this function fails, icon
is left unchanged;
Returns
the displayed icon, or NULL if the image is empty.
[nullable][transfer none]
Since: 2.14
gtk_status_icon_get_size ()
gint
gtk_status_icon_get_size (GtkStatusIcon *status_icon);
gtk_status_icon_get_size has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function, as the representation of a notification
is left to the platform
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.
Note that the returned size is only meaningful while the
status icon is embedded (see gtk_status_icon_is_embedded()).
Returns
the size that is available for the image
Since: 2.10
gtk_status_icon_set_screen ()
void
gtk_status_icon_set_screen (GtkStatusIcon *status_icon,
GdkScreen *screen);
gtk_status_icon_set_screen has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function, as GTK typically only has one GdkScreen
and notifications are managed by the platform
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.
Since: 2.12
gtk_status_icon_get_screen ()
GdkScreen *
gtk_status_icon_get_screen (GtkStatusIcon *status_icon);
gtk_status_icon_get_screen has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function, as notifications are managed by the platform
Returns the GdkScreen associated with status_icon
.
Since: 2.12
gtk_status_icon_set_tooltip_text ()
void
gtk_status_icon_set_tooltip_text (GtkStatusIcon *status_icon,
const gchar *text);
gtk_status_icon_set_tooltip_text has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
Sets text
as the contents of the tooltip.
This function will take care of setting “has-tooltip” to
TRUE and of the default handler for the “query-tooltip”
signal.
See also the “tooltip-text” property and
gtk_tooltip_set_text().
Since: 2.16
gtk_status_icon_get_tooltip_text ()
gchar *
gtk_status_icon_get_tooltip_text (GtkStatusIcon *status_icon);
gtk_status_icon_get_tooltip_text has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
Gets the contents of the tooltip for status_icon
.
Returns
the tooltip text, or NULL. You should free the
returned string with g_free() when done.
[nullable]
Since: 2.16
gtk_status_icon_set_tooltip_markup ()
void
gtk_status_icon_set_tooltip_markup (GtkStatusIcon *status_icon,
const gchar *markup);
gtk_status_icon_set_tooltip_markup has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
Sets markup
as the contents of the tooltip, which is marked up with
the Pango text markup language.
This function will take care of setting “has-tooltip” to TRUE
and of the default handler for the “query-tooltip” signal.
See also the “tooltip-markup” property and
gtk_tooltip_set_markup().
Since: 2.16
gtk_status_icon_get_tooltip_markup ()
gchar *
gtk_status_icon_get_tooltip_markup (GtkStatusIcon *status_icon);
gtk_status_icon_get_tooltip_markup has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
Gets the contents of the tooltip for status_icon
.
Returns
the tooltip text, or NULL. You should free the
returned string with g_free() when done.
[nullable]
Since: 2.16
gtk_status_icon_set_has_tooltip ()
void
gtk_status_icon_set_has_tooltip (GtkStatusIcon *status_icon,
gboolean has_tooltip);
gtk_status_icon_set_has_tooltip has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function, but notifications can display an arbitrary
amount of text using g_notification_set_body()
Sets the has-tooltip property on status_icon
to has_tooltip
.
See “has-tooltip” for more information.
Since: 2.16
gtk_status_icon_get_has_tooltip ()
gboolean
gtk_status_icon_get_has_tooltip (GtkStatusIcon *status_icon);
gtk_status_icon_get_has_tooltip has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
Returns the current value of the has-tooltip property.
See “has-tooltip” for more information.
Returns
current value of has-tooltip on status_icon
.
Since: 2.16
gtk_status_icon_set_title ()
void
gtk_status_icon_set_title (GtkStatusIcon *status_icon,
const gchar *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.
Since: 2.18
gtk_status_icon_get_title ()
const gchar *
gtk_status_icon_get_title (GtkStatusIcon *status_icon);
gtk_status_icon_get_title has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
Gets the title of this tray icon. See gtk_status_icon_set_title().
Returns
the title of the status icon
Since: 2.18
gtk_status_icon_set_name ()
void
gtk_status_icon_set_name (GtkStatusIcon *status_icon,
const gchar *name);
gtk_status_icon_set_name has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function, as notifications are associated with a
unique application identifier by GApplication
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.
Since: 2.20
gtk_status_icon_set_visible ()
void
gtk_status_icon_set_visible (GtkStatusIcon *status_icon,
gboolean visible);
gtk_status_icon_set_visible has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function, as notifications are managed by the platform
Shows or hides a status icon.
Since: 2.10
gtk_status_icon_get_visible ()
gboolean
gtk_status_icon_get_visible (GtkStatusIcon *status_icon);
gtk_status_icon_get_visible has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
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().
Returns
TRUE if the status icon is visible
Since: 2.10
gtk_status_icon_is_embedded ()
gboolean
gtk_status_icon_is_embedded (GtkStatusIcon *status_icon);
gtk_status_icon_is_embedded has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
Returns whether the status icon is embedded in a notification
area.
Returns
TRUE if the status icon is embedded in
a notification area.
Since: 2.10
gtk_status_icon_position_menu ()
void
gtk_status_icon_position_menu (GtkMenu *menu,
gint *x,
gint *y,
gboolean *push_in,
gpointer user_data);
gtk_status_icon_position_menu has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; notifications do not have menus,
but can have buttons, and actions associated with each button
Menu positioning function to use with gtk_menu_popup()
to position menu
aligned to the status icon user_data
.
Since: 2.10
gtk_status_icon_get_geometry ()
gboolean
gtk_status_icon_get_geometry (GtkStatusIcon *status_icon,
GdkScreen **screen,
GdkRectangle *area,
GtkOrientation *orientation);
gtk_status_icon_get_geometry has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function, as the platform is responsible for the
presentation of notifications
Obtains information about the location of the status icon
on screen. This information can be used to e.g. position
popups like notification bubbles.
See gtk_status_icon_position_menu() for a more convenient
alternative for positioning menus.
Note that some platforms do not allow GTK+ to provide
this information, and even on platforms that do allow it,
the information is not reliable unless the status icon
is embedded in a notification area, see
gtk_status_icon_is_embedded().
Returns
TRUE if the location information has
been filled in
Since: 2.10
gtk_status_icon_get_x11_window_id ()
guint32
gtk_status_icon_get_x11_window_id (GtkStatusIcon *status_icon);
gtk_status_icon_get_x11_window_id has been deprecated since version 3.14 and should not be used in newly-written code.
Use GNotification and GtkApplication to
provide status notifications; there is no direct replacement
for this function
This function is only useful on the X11/freedesktop.org platform.
It returns a window ID for the widget in the underlying
status icon implementation. This is useful for the Galago
notification service, which can send a window ID in the protocol
in order for the server to position notification windows
pointing to a status icon reliably.
This function is not intended for other use cases which are
more likely to be met by one of the non-X11 specific methods, such
as gtk_status_icon_position_menu().
Returns
An 32 bit unsigned integer identifier for the
underlying X11 Window
Since: 2.14
Property Details
The “embedded” property
“embedded” gboolean
TRUE if the statusicon is embedded in a notification area.
Owner: GtkStatusIcon
Flags: Read
Default value: FALSE
Since: 2.12
The “file” property
“file” gchar *
Filename to load and display.
Owner: GtkStatusIcon
Flags: Write
Default value: NULL
The “gicon” property
“gicon” GIcon *
The GIcon displayed in the GtkStatusIcon. For themed icons,
the image will be updated automatically if the theme changes.
Owner: GtkStatusIcon
Flags: Read / Write
Since: 2.14
The “has-tooltip” property
“has-tooltip” gboolean
Enables or disables the emission of “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
“query-tooltip” to determine whether it will provide a
tooltip or not.
Note that setting this property to TRUE for the first time will change
the event masks of the windows of this status icon to include leave-notify
and motion-notify events. This will not be undone when the property is set
to FALSE again.
Whether this property is respected is platform dependent.
For plain text tooltips, use “tooltip-text” in preference.
Owner: GtkStatusIcon
Flags: Read / Write
Default value: FALSE
Since: 2.16
The “icon-name” property
“icon-name” gchar *
The name of the icon from the icon theme.
Owner: GtkStatusIcon
Flags: Read / Write
Default value: NULL
The “orientation” property
“orientation” GtkOrientation
The orientation of the tray in which the statusicon
is embedded.
Owner: GtkStatusIcon
Flags: Read
Default value: GTK_ORIENTATION_HORIZONTAL
Since: 2.12
The “pixbuf” property
“pixbuf” GdkPixbuf *
A GdkPixbuf to display.
Owner: GtkStatusIcon
Flags: Read / Write
The “screen” property
“screen” GdkScreen *
The screen where this status icon will be displayed.
Owner: GtkStatusIcon
Flags: Read / Write
The “size” property
“size” gint
The size of the icon.
Owner: GtkStatusIcon
Flags: Read
Allowed values: >= 0
Default value: 0
The “stock” property
“stock” gchar *
Stock ID for a stock image to display.
GtkStatusIcon:stock has been deprecated since version 3.10 and should not be used in newly-written code.
Use “icon-name” instead.
Owner: GtkStatusIcon
Flags: Read / Write
Default value: NULL
The “storage-type” property
“storage-type” GtkImageType
The representation being used for image data.
Owner: GtkStatusIcon
Flags: Read
Default value: GTK_IMAGE_EMPTY
The “title” property
“title” gchar *
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.
Owner: GtkStatusIcon
Flags: Read / Write
Default value: NULL
Since: 2.18
The “tooltip-markup” property
“tooltip-markup” gchar *
Sets the text of tooltip to be the given string, which is marked up
with the Pango text markup language.
Also see gtk_tooltip_set_markup().
This is a convenience property which will take care of getting the
tooltip shown if the given string is not NULL.
“has-tooltip” will automatically be set to TRUE and
the default handler for the “query-tooltip” signal
will take care of displaying the tooltip.
On some platforms, embedded markup will be ignored.
Owner: GtkStatusIcon
Flags: Read / Write
Default value: NULL
Since: 2.16
The “tooltip-text” property
“tooltip-text” gchar *
Sets the text of tooltip to be the given string.
Also see gtk_tooltip_set_text().
This is a convenience property which will take care of getting the
tooltip shown if the given string is not NULL.
“has-tooltip” will automatically be set to TRUE and
the default handler for the “query-tooltip” signal
will take care of displaying the tooltip.
Note that some platforms have limitations on the length of tooltips
that they allow on status icons, e.g. Windows only shows the first
64 characters.
Owner: GtkStatusIcon
Flags: Read / Write
Default value: NULL
Since: 2.16
The “visible” property
“visible” gboolean
Whether the status icon is visible.
Owner: GtkStatusIcon
Flags: Read / Write
Default value: TRUE
Signal Details
The “activate” signal
void
user_function (GtkStatusIcon *status_icon,
gpointer user_data)
Gets emitted when the user activates the status icon.
If and how status icons can activated is platform-dependent.
Unlike most G_SIGNAL_ACTION signals, this signal is meant to
be used by applications and should be wrapped by language bindings.
Flags: Action
Since: 2.10
The “button-press-event” signal
gboolean
user_function (GtkStatusIcon *status_icon,
GdkEvent *event,
gpointer user_data)
The ::button-press-event signal will be emitted when a button
(typically from a mouse) is pressed.
Whether this event is emitted is platform-dependent. Use the ::activate
and ::popup-menu signals in preference.
Returns
TRUE to stop other handlers from being invoked
for the event. FALSE to propagate the event further.
Flags: Run Last
Since: 2.14
The “button-release-event” signal
gboolean
user_function (GtkStatusIcon *status_icon,
GdkEvent *event,
gpointer user_data)
The ::button-release-event signal will be emitted when a button
(typically from a mouse) is released.
Whether this event is emitted is platform-dependent. Use the ::activate
and ::popup-menu signals in preference.
Returns
TRUE to stop other handlers from being invoked
for the event. FALSE to propagate the event further.
Flags: Run Last
Since: 2.14
The “popup-menu” signal
void
user_function (GtkStatusIcon *status_icon,
guint button,
guint activate_time,
gpointer user_data)
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.
The button
and activate_time
parameters should be
passed as the last to arguments to gtk_menu_popup().
Unlike most G_SIGNAL_ACTION signals, this signal is meant to
be used by applications and should be wrapped by language bindings.
Flags: Action
Since: 2.10
The “query-tooltip” signal
gboolean
user_function (GtkStatusIcon *status_icon,
gint x,
gint y,
gboolean keyboard_mode,
GtkTooltip *tooltip,
gpointer user_data)
Emitted when the hover timeout has expired with the
cursor hovering above status_icon
; or emitted when status_icon
got
focus in keyboard mode.
Using the given coordinates, the signal handler should determine
whether a tooltip should be shown for status_icon
. If this is
the case TRUE should be returned, FALSE otherwise. Note that if
keyboard_mode
is TRUE, the values of x
and y
are undefined and
should not be used.
The signal handler is free to manipulate tooltip
with the therefore
destined function calls.
Whether this signal is emitted is platform-dependent.
For plain text tooltips, use “tooltip-text” in preference.
Returns
TRUE if tooltip
should be shown right now, FALSE otherwise.
Flags: Run Last
Since: 2.16
The “scroll-event” signal
gboolean
user_function (GtkStatusIcon *status_icon,
GdkEvent *event,
gpointer user_data)
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.
Whether this event is emitted is platform-dependent.
Returns
TRUE to stop other handlers from being invoked for the event.
FALSE to propagate the event further.
Flags: Run Last
Since: 2.16
The “size-changed” signal
gboolean
user_function (GtkStatusIcon *status_icon,
gint size,
gpointer user_data)
Gets emitted when the size available for the image
changes, e.g. because the notification area got resized.
Returns
TRUE if the icon was updated for the new
size. Otherwise, GTK+ will scale the icon as necessary.
Flags: Run Last
Since: 2.10