gtk.status_icon
Module for [StatusIcon] class
Types 3
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.StatusIcon.isEmbedded], 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.
Methods
StatusIcon self()Returns `this`, for use in `with` statements.StatusIconGidBuilder builder()Get builder for [gtk.status_icon.StatusIcon] Returns: New builder objectbool embedded() @propertyGet `embedded` property. Returns: true if the statusicon is embedded in a notification area.void file(string propval) @propertygio.icon.Icon gicon() @propertyGet `gicon` property. Returns: The #GIcon displayed in the #GtkStatusIcon. For themed icons, the image will be updated automatically if the theme changes.void gicon(gio.icon.Icon propval) @propertySet `gicon` property. Params: propval = The #GIcon displayed in the #GtkStatusIcon. For themed icons, the image will be updated automatically if the theme changes.bool hasTooltip() @propertyGet `hasTooltip` property. Returns: Enables or disables the emission of #GtkStatusIcon::query-tooltip on @statusicon. A value of true indicates that @statusicon can have a tooltip, in this case th...void hasTooltip(bool propval) @propertySet `hasTooltip` property. Params: propval = Enables or disables the emission of #GtkStatusIcon::query-tooltip on @statusicon. A value of true indicates that @statusicon can have a tooltip, in thi...string iconName() @propertyvoid iconName(string propval) @propertygtk.types.Orientation orientation() @propertyGet `orientation` property. Returns: The orientation of the tray in which the statusicon is embedded.gdkpixbuf.pixbuf.Pixbuf pixbuf() @propertyvoid pixbuf(gdkpixbuf.pixbuf.Pixbuf propval) @propertygdk.screen.Screen screen() @propertyvoid screen(gdk.screen.Screen propval) @propertyint size() @propertystring stock() @propertyvoid stock(string propval) @propertygtk.types.ImageType storageType() @propertystring title() @propertyGet `title` property. Returns: 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 ...void title(string propval) @propertySet `title` property. Params: propval = 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 t...string tooltipMarkup() @propertyGet `tooltipMarkup` property. Returns: 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.Tooltip.se...void tooltipMarkup(string propval) @propertySet `tooltipMarkup` property. Params: propval = 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.T...string tooltipText() @propertyGet `tooltipText` property. Returns: Sets the text of tooltip to be the given string.void tooltipText(string propval) @propertySet `tooltipText` property. Params: propval = Sets the text of tooltip to be the given string.bool visible() @propertyvoid visible(bool propval) @propertygtk.status_icon.StatusIcon newFromFile(string filename)Creates a status icon displaying the file filename.gtk.status_icon.StatusIcon newFromGicon(gio.icon.Icon icon)Creates a status icon displaying a #GIcon. If the icon is a themed icon, it will be updated when the theme changes.gtk.status_icon.StatusIcon newFromIconName(string iconName)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.gtk.status_icon.StatusIcon newFromPixbuf(gdkpixbuf.pixbuf.Pixbuf pixbuf)Creates a status icon displaying pixbuf.gtk.status_icon.StatusIcon newFromStock(string stockId)Creates a status icon displaying a stock icon. Sample stock icon names are #GTKSTOCKOPEN, #GTKSTOCKQUIT. You can register your own stock icon names, see [gtk.iconfactory.IconFactory.addDefault] and...void positionMenu(gtk.menu.Menu menu, ref int x, ref int y, out bool pushIn, gtk.status_icon.StatusIcon userData)Menu positioning function to use with [gtk.menu.Menu.popup] to position menu aligned to the status icon user_data.bool getGeometry(out gdk.screen.Screen screen, out gdk.rectangle.Rectangle area, out gtk.types.Orientation orientation)Obtains information about the location of the status icon on screen. This information can be used to e.g. position popups like notification bubbles.gio.icon.Icon getGicon()Retrieves the #GIcon being displayed by the #GtkStatusIcon. The storage type of the status icon must be [gtk.types.ImageType.Empty] or [gtk.types.ImageType.Gicon] (see [gtk.status_icon.StatusIcon.g...bool getHasTooltip()Returns the current value of the has-tooltip property. See #GtkStatusIcon:has-tooltip for more information. Returns: current value of has-tooltip on status_icon.string getIconName()Gets the name of the icon being displayed by the #GtkStatusIcon. The storage type of the status icon must be [gtk.types.ImageType.Empty] or [gtk.types.ImageType.IconName] (see [gtk.status_icon.Stat...gdkpixbuf.pixbuf.Pixbuf getPixbuf()Gets the #GdkPixbuf being displayed by the #GtkStatusIcon. The storage type of the status icon must be [gtk.types.ImageType.Empty] or [gtk.types.ImageType.Pixbuf] (see [gtk.status_icon.StatusIcon.g...gdk.screen.Screen getScreen()Returns the #GdkScreen associated with status_icon. Returns: a #GdkScreen.int getSize()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-c...string getStock()Gets the id of the stock icon being displayed by the #GtkStatusIcon. The storage type of the status icon must be [gtk.types.ImageType.Empty] or [gtk.types.ImageType.Stock] (see [gtk.status_icon.Sta...gtk.types.ImageType getStorageType()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.types.ImageType.Empty]. Returns: the ima...string getTitle()Gets the title of this tray icon. See [gtk.status_icon.StatusIcon.setTitle]. Returns: the title of the status iconstring getTooltipMarkup()Gets the contents of the tooltip for status_icon. Returns: the tooltip text, or null. You should free the returned string with [glib.global.gfree] when done.string getTooltipText()Gets the contents of the tooltip for status_icon. Returns: the tooltip text, or null. You should free the returned string with [glib.global.gfree] when done.bool getVisible()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.StatusIcon.isEmbedded]. Returns: tru...uint getX11WindowId()This function is only useful on the X11/freedesktop.org platform.bool isEmbedded()Returns whether the status icon is embedded in a notification area. Returns: true if the status icon is embedded in a notification area.void setFromFile(string filename)Makes statusicon display the file filename. See [gtk.statusicon.StatusIcon.newFromFile] for details.void setFromGicon(gio.icon.Icon icon)Makes statusicon display the #GIcon. See [gtk.statusicon.StatusIcon.newFromGicon] for details.void setFromIconName(string iconName)Makes statusicon display the icon named iconname from the current icon theme. See [gtk.status_icon.StatusIcon.newFromIconName] for details.void setFromPixbuf(gdkpixbuf.pixbuf.Pixbuf pixbuf = null)Makes statusicon display pixbuf. See [gtk.statusicon.StatusIcon.newFromPixbuf] for details.void setFromStock(string stockId)Makes statusicon display the stock icon with the id stockid. See [gtk.status_icon.StatusIcon.newFromStock] for details.void setHasTooltip(bool hasTooltip)Sets the has-tooltip property on statusicon to hastooltip. See #GtkStatusIcon:has-tooltip for more information.void setName(string 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.void setScreen(gdk.screen.Screen 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.void setTitle(string 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.void setTooltipMarkup(string markup = null)Sets markup as the contents of the tooltip, which is marked up with the [Pango text markup language][PangoMarkupFormat].void setTooltipText(string text)Sets text as the contents of the tooltip.void setVisible(bool visible)Shows or hides a status icon.gulong connectActivate(T)(T callback, Flag!"After" after = No.After) if (isCallable!T
&& is(ReturnType!T == void)
&& (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] : gtk.status_icon.StatusIcon)))
&& Parameters!T.length < 2)Connect to `Activate` signal.gulong connectButtonPressEvent(T)(T callback, Flag!"After" after = No.After) if (isCallable!T
&& is(ReturnType!T == bool)
&& (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == gdk.event_button.EventButton)))
&& (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] : gtk.status_icon.StatusIcon)))
&& Parameters!T.length < 3)Connect to `ButtonPressEvent` signal.gulong connectButtonReleaseEvent(T)(T callback, Flag!"After" after = No.After) if (isCallable!T
&& is(ReturnType!T == bool)
&& (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == gdk.event_button.EventButton)))
&& (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] : gtk.status_icon.StatusIcon)))
&& Parameters!T.length < 3)Connect to `ButtonReleaseEvent` signal.gulong connectPopupMenu(T)(T callback, Flag!"After" after = No.After) if (isCallable!T
&& is(ReturnType!T == void)
&& (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == uint)))
&& (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] == uint)))
&& (Parameters!T.length < 3 || (ParameterStorageClassTuple!T[2] == ParameterStorageClass.none && is(Parameters!T[2] : gtk.status_icon.StatusIcon)))
&& Parameters!T.length < 4)Connect to `PopupMenu` signal.gulong connectQueryTooltip(T)(T callback, Flag!"After" after = No.After) if (isCallable!T
&& is(ReturnType!T == bool)
&& (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == int)))
&& (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] == int)))
&& (Parameters!T.length < 3 || (ParameterStorageClassTuple!T[2] == ParameterStorageClass.none && is(Parameters!T[2] == bool)))
&& (Parameters!T.length < 4 || (ParameterStorageClassTuple!T[3] == ParameterStorageClass.none && is(Parameters!T[3] : gtk.tooltip.Tooltip)))
&& (Parameters!T.length < 5 || (ParameterStorageClassTuple!T[4] == ParameterStorageClass.none && is(Parameters!T[4] : gtk.status_icon.StatusIcon)))
&& Parameters!T.length < 6)Connect to `QueryTooltip` signal.gulong connectScrollEvent(T)(T callback, Flag!"After" after = No.After) if (isCallable!T
&& is(ReturnType!T == bool)
&& (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == gdk.event_scroll.EventScroll)))
&& (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] : gtk.status_icon.StatusIcon)))
&& Parameters!T.length < 3)Connect to `ScrollEvent` signal.gulong connectSizeChanged(T)(T callback, Flag!"After" after = No.After) if (isCallable!T
&& is(ReturnType!T == bool)
&& (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == int)))
&& (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] : gtk.status_icon.StatusIcon)))
&& Parameters!T.length < 3)Connect to `SizeChanged` signal.Methods
T file(string propval)T gicon(gio.icon.Icon propval)Set `gicon` property. Params: propval = The #GIcon displayed in the #GtkStatusIcon. For themed icons, the image will be updated automatically if the theme changes. Returns: Builder instance for flu...T hasTooltip(bool propval)Set `hasTooltip` property. Params: propval = Enables or disables the emission of #GtkStatusIcon::query-tooltip on @statusicon. A value of true indicates that @statusicon can have a tooltip, in thi...T iconName(string propval)T pixbuf(gdkpixbuf.pixbuf.Pixbuf propval)T screen(gdk.screen.Screen propval)T stock(string propval)T title(string propval)Set `title` property. Params: propval = 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 t...T tooltipMarkup(string propval)Set `tooltipMarkup` property. Params: propval = 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.T...T tooltipText(string propval)Set `tooltipText` property. Params: propval = Sets the text of tooltip to be the given string.T visible(bool propval)Fluent builder for [gtk.status_icon.StatusIcon]
Methods