XApp.StatusIcon¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`any_monitors` ()
class	`new` ()
class	`new_with_name` (name)
	`get_icon_size` ()
	`get_primary_menu` ()
	`get_secondary_menu` ()
	`get_state` ()
	`get_visible` ()
	`popup_menu` (menu, x, y, button, _time, panel_position)
	`set_icon_name` (icon_name)
	`set_label` (label)
	`set_metadata` (metadata)
	`set_name` (name)
	`set_primary_menu` (menu)
	`set_secondary_menu` (menu)
	`set_tooltip_text` (tooltip_text)
	`set_visible` (visible)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`icon-size`	`int`	r/w	The icon size that should be used, if the client is supplying absolute icon paths
`name`	`str`	r/w/c
`primary-menu`	`Gtk.Widget`	r/w	A menu to bring up when the status icon is left-clicked
`secondary-menu`	`Gtk.Widget`	r/w	A menu to bring up when the status icon is right-clicked

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`activate`	Gets emitted when the user activates the status icon.
`button-press-event`	Gets emitted when there is a button press received from an applet
`button-release-event`	Gets emitted when there is a button release received from an applet
`scroll-event`	Gets emitted when the user uses the mouse scroll wheel over the status icon.
`state-changed`	Gets emitted when the state of the icon changes.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class XApp.StatusIcon(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: XApp.StatusIconClass

classmethod any_monitors()¶

Returns:: True if at least one monitor was found.
Return type:: bool

Looks for the existence of any active XApp.StatusIconMonitors on the bus.

New in version 1.6.

classmethod new()¶

Returns:: a new XApp.StatusIcon. Use GObject.Object.unref when finished.
Return type:: XApp.StatusIcon

Creates a new XApp.StatusIcon instance

New in version 1.6.

classmethod new_with_name(name)¶

Parameters:: name (str) –
Returns:: a new XApp.StatusIcon. Use GObject.Object.unref when finished.
Return type:: XApp.StatusIcon

Creates a new XApp.StatusIcon instance and sets its name to %name.

New in version 1.6.

get_icon_size()¶

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.
Return type:: int

New in version 1.8.

get_primary_menu()¶

Returns:: the Gtk.Menu or None if none was set.
Return type:: Gtk.Widget

Returns a pointer to a Gtk.Menu that was set previously for the primary mouse button. If no menu was set, this returns None.

New in version 1.6.

get_secondary_menu()¶

Returns:: the Gtk.Menu or None if none was set.
Return type:: Gtk.Widget

Returns a pointer to a Gtk.Menu that was set previously for the secondary mouse button. If no menu was set, this returns None.

New in version 1.6.

get_state()¶

Returns:: the icon’s state.
Return type:: XApp.StatusIconState

Gets the current XApp.StatusIconState 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 XApp.StatusIconState for more details.

New in version 1.6.

get_visible()¶

Returns:: the current visibility state.
Return type:: bool

Returns whether or not the icon should currently be visible.

New in version 1.8.5.

popup_menu(menu, x, y, button, _time, panel_position)¶

Parameters:

menu (Gtk.Menu or None) – A Gtk.Menu to display when the primary mouse button is released.
x (int) – The x anchor position for the menu.
y (int) – The y anchor position for the menu.
button (int) – The button used to initiate this action (or 0)
_time (int) – The event time (or 0)
panel_position (int) – The Gtk.PositionType for the position of the icon.

Pop up menu using the positioning arguments. These arguments should be those provided by a XApp.StatusIcon ::button-release-event.

New in version 1.8.6.

set_icon_name(icon_name)¶

Parameters:: icon_name (str) – An icon name or absolute path to an icon.

Sets the icon name or local path to use.

New in version 1.6.

set_label(label)¶

Parameters:: label (str) – some text

Sets a label, shown beside the icon

New in version 1.6.

set_metadata(metadata)¶

Parameters:: metadata (str or None) – A json-formatted string of key:values.

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.

New in version 1.8.7.

set_name(name)¶

Parameters:: name (str) – a name (this defaults to the name of the application, if not set)

Sets the status icon name. This is not shown to users.

New in version 1.6.

set_primary_menu(menu)¶

Parameters:: menu (Gtk.Menu or None) – A Gtk.Menu to display when the primary mouse button is released.

See the XApp.StatusIcon :primary-menu property for details

New in version 1.6.

set_secondary_menu(menu)¶

Parameters:: menu (Gtk.Menu or None) – A Gtk.Menu to display when the primary mouse button is released.

See the XApp.StatusIcon :secondary-menu property for details

New in version 1.6.

set_tooltip_text(tooltip_text)¶

Parameters:: tooltip_text (str) – the text to show in the tooltip

Sets the tooltip text

New in version 1.6.

set_visible(visible)¶

Parameters:: visible (bool) – whether or not the status icon should be visible

Sets the visibility of the status icon

New in version 1.6.

Signal Details¶

XApp.StatusIcon.signals.activate(status_icon, button, time)¶

Signal Name:

activate

Flags:

RUN_FIRST, ACTION

Parameters:

status_icon (XApp.StatusIcon) – The object which received the signal
button (int) – The button that was pressed
time (int) – The time supplied by the event, or 0

Gets emitted when the user activates the status icon. If the XApp.StatusIcon :primary-menu or XApp.StatusIcon :secondary-menu is not None, this signal is skipped for the respective button presses. A middle button click will always send this signal when pressed.

XApp.StatusIcon.signals.button_press_event(status_icon, x, y, button, time, panel_position)¶

Signal Name:

button-press-event

Flags:

RUN_LAST, ACTION

Parameters:

status_icon (XApp.StatusIcon) – The object which received the signal
x (int) – The absolute x position to use for menu positioning
y (int) – The absolute y position to use for menu positioning
button (int) – The button that was pressed
time (int) – The time supplied by the event, or 0
panel_position (int) – The Gtk.PositionType to use for menu positioning

Gets emitted when there is a button press received from an applet

XApp.StatusIcon.signals.button_release_event(status_icon, x, y, button, time, panel_position)¶

Signal Name:

button-release-event

Flags:

RUN_LAST, ACTION

Parameters:

status_icon (XApp.StatusIcon) – The object which received the signal
x (int) – The absolute x position to use for menu positioning
y (int) – The absolute y position to use for menu positioning
button (int) – The button that was released
time (int) – The time supplied by the event, or 0
panel_position (int) – The Gtk.PositionType to use for menu positioning

Gets emitted when there is a button release received from an applet

XApp.StatusIcon.signals.scroll_event(status_icon, amount, direction, time)¶

Signal Name:

scroll-event

Flags:

RUN_FIRST, ACTION

Parameters:

status_icon (XApp.StatusIcon) – The object which received the signal
amount (int) – The amount of movement for the scroll event
direction (XApp.ScrollDirection) – the XApp.ScrollDirection of the scroll event
time (int) – The time supplied by the event, or 0

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.

XApp.StatusIcon.signals.state_changed(status_icon, new_state)¶

Signal Name:

state-changed

Flags:

RUN_FIRST, ACTION

Parameters:

status_icon (XApp.StatusIcon) – The object which received the signal
new_state (XApp.StatusIconState) – The new XApp.StatusIconState of the icon

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 XApp.StatusIconState for more details.

Property Details¶

XApp.StatusIcon.props.icon_size¶

Name:: icon-size
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

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 XApp.StatusIconMonitors active.

XApp.StatusIcon.props.name¶

Name:: name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT

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 GLib.get_prgname() if no other name is provided.

XApp.StatusIcon.props.primary_menu¶

Name:: primary-menu
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE

A Gtk.Menu to use when requested by the remote monitor via a left (or primary) click.

When this property is not None, the menu will be automatically positioned and displayed during a primary button release.

When this property IS None, the XApp.StatusIcon ::activate will be sent for primary button presses.

In both cases, the XApp.StatusIcon ::button-press-event and XApp.StatusIcon ::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 Gtk.Menu widget can be set as both the primary and secondary.

XApp.StatusIcon.props.secondary_menu¶

Name:: secondary-menu
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE

A Gtk.Menu to use when requested by the remote monitor via a right (or secondary) click.

When this property is not None, the menu will be automatically positioned and displayed during a secondary button release.

When this property IS None, the XApp.StatusIcon ::activate will be sent for secondary button presses.

In both cases, the XApp.StatusIcon ::button-press-event and XApp.StatusIcon ::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 Gtk.Menu widget can be set as both the primary and secondary.