Dbusmenu.Menuitem¶

Subclasses:: Dbusmenu.MenuitemProxy

Methods¶

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

class	`new` ()
class	`new_with_id` (id)
	`child_add_position` (child, position)
	`child_append` (child)
	`child_delete` (child)
	`child_find` (id)
	`child_prepend` (child)
	`child_reorder` (child, position)
	`find_id` (id)
	`foreach` (func, data)
	`get_children` ()
	`get_id` ()
	`get_parent` ()
	`get_position` (parent)
	`get_position_realized` (parent)
	`get_root` ()
	`handle_event` (name, variant, timestamp)
	`properties_copy` ()
	`properties_list` ()
	`property_exist` (property)
	`property_get` (property)
	`property_get_bool` (property)
	`property_get_byte_array` (property)
	`property_get_int` (property)
	`property_get_variant` (property)
	`property_remove` (property)
	`property_set` (property, value)
	`property_set_bool` (property, value)
	`property_set_byte_array` (property, value, nelements)
	`property_set_int` (property, value)
	`property_set_variant` (property, value)
	`send_about_to_show` (cb, cb_data)
	`set_parent` (parent)
	`set_root` (root)
	`show_to_user` (timestamp)
	`take_children` ()
	`unparent` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_child_added` (position)
	`do_child_moved` (newpos, oldpos)
	`do_child_removed` ()
	`do_handle_event` (name, variant, timestamp)
	`do_show_to_user` (timestamp, cb_data)

Properties¶

Name	Type	Flags	Short Description
`id`	`int`	r/w/co	This is a unique indentifier for the menu item.

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`about-to-show`	Emitted when the submenu for this item is about to be shown
`child-added`	Signaled when the child menuitem has been added to the parent.
`child-moved`	Signaled when the child menuitem has had its location in the list change.
`child-removed`	Signaled when the child menuitem has been requested to be removed from the parent.
`event`	Emitted when an event is passed through.
`item-activated`	Emitted on the objects on the server side when they are signaled on the client side.
`property-changed`	Emitted everytime a property on a menuitem is either updated or added.
`realized`	Emitted when the initial request for properties is complete on the item.
`show-to-user`	Signaled when the application would like the visualization of this menu item shown to the user.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r	Parent object
priv	`Dbusmenu.MenuitemPrivate`	r	Private data

Class Details¶

class Dbusmenu.Menuitem(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Dbusmenu.MenuitemClass

This is the GObject.Object based object that represents a menu item. It gets created the same on both the client and the server side and libdbusmenu-glib does the work of making this object model appear on both sides of DBus. Simple really, though through updates and people coming on and off the bus it can lead to lots of fun complex scenarios.

classmethod new()¶

Returns:: A newly allocated Dbusmenu.Menuitem.
Return type:: Dbusmenu.Menuitem

Create a new Dbusmenu.Menuitem with all default values.

classmethod new_with_id(id)¶

Parameters:: id (int) – ID to use for this menuitem
Returns:: A newly allocated Dbusmenu.Menuitem.
Return type:: Dbusmenu.Menuitem

This creates a blank Dbusmenu.Menuitem with a specific ID.

child_add_position(child, position)¶

Parameters:

child (Dbusmenu.Menuitem) – The Dbusmenu.Menuitem to make a child of self.
position (int) – Where in self object’s list of chidren child should be placed.

Returns:

Whether child was added successfully.

Return type:

bool

Puts child in the list of children for self at the location specified in position. If there is not enough entires available then child will be placed at the end of the list.

child_append(child)¶

Parameters:: child (Dbusmenu.Menuitem) – The #DbusmenMenuitem that will be a child
Returns:: Whether the child has been added successfully.
Return type:: bool

This function adds child to the list of children on self at the end of that list.

child_delete(child)¶

Parameters:: child (Dbusmenu.Menuitem) – The child Dbusmenu.Menuitem that you want to no longer be a child of self.
Returns:: If we were able to delete child.
Return type:: bool

This function removes child from the children list of self. It does not call GObject.Object.unref on child.

child_find(id)¶

Parameters:: id (int) – The ID of the child that we’re looking for.
Returns:: The menu item with the ID id or None if it can’t be found.
Return type:: Dbusmenu.Menuitem

Search the children of self to find one with the ID of id. If it doesn’t exist then we return None.

child_prepend(child)¶

Parameters:: child (Dbusmenu.Menuitem) – The #DbusmenMenuitem that will be a child
Returns:: Whether the child has been added successfully.
Return type:: bool

This function adds child to the list of children on self at the beginning of that list.

child_reorder(child, position)¶

Parameters:

child (Dbusmenu.Menuitem) – The Dbusmenu.Menuitem that is a child needing to be moved
position (int) – The position in the list to place it in

Returns:

Whether the move was successful.

Return type:

bool

This function moves a child on the list of children. It is for a child that is already in the list, but simply needs a new location.

find_id(id)¶

Parameters:: id (int) – ID of the Dbusmenu.Menuitem to search for
Returns:: The Dbusmenu.Menuitem with the ID of id or None if there isn’t such a menu item in the tree represented by self.
Return type:: Dbusmenu.Menuitem

This function searchs the whole tree of children that are attached to self. This could be quite a few nodes, all the way down the tree. It is a depth first search.

foreach(func, data)¶

Parameters:

func (object or None) – Function to call on every node in the tree
data (object or None) – User data to pass to the function

This calls the function func on this menu item and all of the children of this item. And their children. And their children. And… you get the point. It will get called on the whole tree.

get_children()¶

Returns:: A GLib.List of pointers to Dbusmenu.Menuitem objects.
Return type:: [Dbusmenu.Menuitem]

Returns simply the list of children that this menu item has. The list is valid until another child related function is called, where it might be changed.

get_id()¶

Returns:: The ID of the self.
Return type:: int

Gets the unique ID for self.

get_parent()¶

Returns:: The parent of this menu item
Return type:: Dbusmenu.Menuitem

This function looks up the parent of self

get_position(parent)¶

Parameters:: parent (Dbusmenu.Menuitem) – The Dbusmenu.Menuitem who’s children contain self
Returns:: The position of self in the children of parent.
Return type:: int

This function returns the position of the menu item self in the children of parent. It will return zero if the menu item can’t be found.

get_position_realized(parent)¶

Parameters:: parent (Dbusmenu.Menuitem) – The Dbusmenu.Menuitem who’s children contain self
Returns:: The position of self in the realized children of parent.
Return type:: int

This function is very similar to Dbusmenu.Menuitem.get_position except that it only counts in the children that have been realized.

get_root()¶

Returns:: True if this is a root node
Return type:: bool

This function returns the internal value of whether this is a root node or not.

handle_event(name, variant, timestamp)¶

Parameters:

name (str) – The name of the signal
variant (GLib.Variant) – A value that could be set for the event
timestamp (int) – The timestamp of when the event happened

This function is called to create an event. It is likely to be overrided by subclasses. The default menu item will respond to the activate signal and do:

Emits the Dbusmenu.Menuitem ::item-activate signal on this menu item. Called by server objects when they get the appropriate DBus signals from the client.

If you subclass this function you should really think about calling the parent function unless you have a good reason not to.

properties_copy()¶

Returns:: A brand new GLib.HashTable that contains all of theroperties that are on this Dbusmenu.Menuitem self.
Return type:: {object: object}

This function takes the properties of a Dbusmenu.Menuitem and puts them into a GLib.HashTable that is referenced by the key of a string and has the value of a string. The hash table may not have any entries if there aren’t any or there is an error in processing. It is the caller’s responsibility to destroy the created GLib.HashTable.

properties_list()¶

Returns:: A list of strings or None if there are none.
Return type:: [str]

This functiong gets a list of the names of all the properties that are set on this menu item. This data on the list is owned by the menuitem but the list is not and should be freed using g_list_free() when the calling function is done with it.

property_exist(property)¶

Parameters:: property (str) – The property to look for.
Returns:: A boolean checking to see if the property is available
Return type:: bool

Checkes to see if a particular property exists on self and returns True if so.

property_get(property)¶

Parameters:: property (str) – The property to grab.
Returns:: A string with the value of the property that shouldn’t be free’d. Or None if the property is not set or is not a string.
Return type:: str

Look up a property on self and return the value of it if it exits. None will be returned if the property doesn’t exist.

property_get_bool(property)¶

Parameters:: property (str) – The property to grab.
Returns:: The value of the property or False.
Return type:: bool

Look up a property on self and return the value of it if it exits. Returns False if the property doesn’t exist.

property_get_byte_array(property)¶

Parameters:: property (str) – The property to grab.
Returns:: A byte array with the value of the property that shouldn’t be free’d. Or None if the property is not set or is not a byte array.
Return type:: bytes

Look up a property on self and return the value of it if it exits. None will be returned if the property doesn’t exist.

property_get_int(property)¶

Parameters:: property (str) – The property to grab.
Returns:: The value of the property or zero.
Return type:: int

Look up a property on self and return the value of it if it exits. Returns zero if the property doesn’t exist.

property_get_variant(property)¶

Parameters:: property (str) – The property to grab.
Returns:: A GLib.Variant for the property.
Return type:: GLib.Variant

Look up a property on self and return the value of it if it exits. None will be returned if the property doesn’t exist.

property_remove(property)¶

Parameters:: property (str) – The property to look for.

Removes a property from the menuitem.

property_set(property, value)¶

Parameters:

property (str) – Name of the property to set.
value (str) – The value of the property.

Returns:

A boolean representing if the property value was set.

Return type:

bool

Takes the pair of property and value and places them as a property on self. If a property already exists by that name, then the value is set to the new value. If not, the property is added. If the value is changed or the property was previously unset then the signal Dbusmenu.Menuitem ::prop-changed will be emitted by this function.

property_set_bool(property, value)¶

Parameters:

property (str) – Name of the property to set.
value (bool) – The value of the property.

Returns:

A boolean representing if the property value was set.

Return type:

bool

Takes a boolean value and sets it on property as a property on self. If a property already exists by that name, then the value is set to the new value. If not, the property is added. If the value is changed or the property was previously unset then the signal Dbusmenu.Menuitem ::prop-changed will be emitted by this function.

property_set_byte_array(property, value, nelements)¶

Parameters:

property (str) – Name of the property to set.
value (int) – The byte array.
nelements (int) – The number of elements in the byte array.

Returns:

A boolean representing if the property value was set.

Return type:

bool

Takes a byte array value and sets it on property as a property on self. If a property already exists by that name, then the value is set to the new value. If not, the property is added. If the value is changed or the property was previously unset then the signal Dbusmenu.Menuitem ::prop-changed will be emitted by this function.

property_set_int(property, value)¶

Parameters:

property (str) – Name of the property to set.
value (int) – The value of the property.

Returns:

A boolean representing if the property value was set.

Return type:

bool

Takes a boolean value and sets it on property as a property on self. If a property already exists by that name, then the value is set to the new value. If not, the property is added. If the value is changed or the property was previously unset then the signal Dbusmenu.Menuitem ::prop-changed will be emitted by this function.

property_set_variant(property, value)¶

Parameters:

property (str) – Name of the property to set.
value (GLib.Variant) – The value of the property.

Returns:

A boolean representing if the property value was set.

Return type:

bool

Takes the pair of property and value and places them as a property on self. If a property already exists by that name, then the value is set to the new value. If not, the property is added. If the value is changed or the property was previously unset then the signal Dbusmenu.Menuitem ::prop-changed will be emitted by this function.

send_about_to_show(cb, cb_data)¶

Parameters:

cb (object or None) – Callback to call when the call has returned.
cb_data (object or None) – Data to pass to the callback.

This function is used to send the even that the submenu of this item is about to be shown. Callers to this event should delay showing the menu until their callback is called if possible.

set_parent(parent)¶

Parameters:: parent (Dbusmenu.Menuitem) – The new parent Dbusmenu.Menuitem
Returns:: Whether the parent was set successfully
Return type:: bool

Sets the parent of self to parent. If self already has a parent, then this call will fail. The parent will be set automatically when using the usual methods to add a child menuitem, so this function should not normally be called directly

set_root(root)¶

Parameters:: root (bool) – Whether self is a root node or not

This function sets the internal value of whether this is a root node or not.

show_to_user(timestamp)¶

Parameters:: timestamp (int) – The time that the user requested it to be shown

Signals that this menu item should be shown to the user. If this is server side the server will then take it and send it over the bus.

take_children()¶

Returns:: A GLib.List of pointers to Dbusmenu.Menuitem objects.
Return type:: [Dbusmenu.Menuitem]

While the name sounds devious that’s exactly what this function does. It takes the list of children from the self and clears the internal list. The calling function is now in charge of the ref’s on the children it has taken. A lot of responsibility involved in taking children.

unparent()¶

Returns:: Whether the menu item was unparented successfully
Return type:: bool

Unparents the menu item self. If self doesn’t have a parent, then this call will fail. The menuitem will be unparented automatically when using the usual methods to delete a child menuitem, so this function should not normally be called directly

do_child_added(position) virtual¶

Parameters:: position (int) –

do_child_moved(newpos, oldpos) virtual¶

Parameters:

newpos (int) –
oldpos (int) –

do_child_removed() virtual¶

do_handle_event(name, variant, timestamp) virtual¶

Parameters:

name (str) – The name of the signal
variant (GLib.Variant) – A value that could be set for the event
timestamp (int) – The timestamp of when the event happened

This function is called to create an event. It is likely to be overrided by subclasses. The default menu item will respond to the activate signal and do:

Emits the Dbusmenu.Menuitem ::item-activate signal on this menu item. Called by server objects when they get the appropriate DBus signals from the client.

If you subclass this function you should really think about calling the parent function unless you have a good reason not to.

do_show_to_user(timestamp, cb_data) virtual¶

Parameters:

timestamp (int) –
cb_data (object or None) –

Signal Details¶

Dbusmenu.Menuitem.signals.about_to_show(menuitem)¶

Signal Name:: about-to-show
Flags:: RUN_LAST
Parameters:: menuitem (Dbusmenu.Menuitem) – The object which received the signal
Return type:: bool

Emitted when the submenu for this item is about to be shown

Dbusmenu.Menuitem.signals.child_added(menuitem, arg1, arg2)¶

Signal Name:

child-added

Flags:

RUN_LAST

Parameters:

menuitem (Dbusmenu.Menuitem) – The object which received the signal
arg1 (GObject.Object) – The Dbusmenu.Menuitem which is the child.
arg2 (int) – The position that the child is being added in.

Signaled when the child menuitem has been added to the parent.

Dbusmenu.Menuitem.signals.child_moved(menuitem, arg1, arg2, arg3)¶

Signal Name:

child-moved

Flags:

RUN_LAST

Parameters:

menuitem (Dbusmenu.Menuitem) – The object which received the signal
arg1 (GObject.Object) – The Dbusmenu.Menuitem which is the child.
arg2 (int) – The position that the child is being moved to.
arg3 (int) – The position that the child is was in.

Signaled when the child menuitem has had its location in the list change.

Dbusmenu.Menuitem.signals.child_removed(menuitem, arg1)¶

Signal Name:

child-removed

Flags:

RUN_LAST

Parameters:

menuitem (Dbusmenu.Menuitem) – The object which received the signal
arg1 (GObject.Object) – The Dbusmenu.Menuitem which was the child.

Signaled when the child menuitem has been requested to be removed from the parent. This signal is called when it has been removed from the list but not yet had GObject.Object.unref called on it.

Dbusmenu.Menuitem.signals.event(menuitem, arg1, arg2, arg3)¶

Signal Name:

event

Flags:

RUN_LAST, DETAILED

Parameters:

menuitem (Dbusmenu.Menuitem) – The object which received the signal
arg1 (str) – Name of the event
arg2 (GLib.Variant) – Information passed along with the event
arg3 (int) – X11 timestamp of when the event happened

Return type:

bool

Emitted when an event is passed through. The event is signalled after handle_event is called.

Dbusmenu.Menuitem.signals.item_activated(menuitem, arg1)¶

Signal Name:

item-activated

Flags:

RUN_LAST

Parameters:

menuitem (Dbusmenu.Menuitem) – The object which received the signal
arg1 (int) – The timestamp of when it was activated

Emitted on the objects on the server side when they are signaled on the client side.

Dbusmenu.Menuitem.signals.property_changed(menuitem, arg1, arg2)¶

Signal Name:

property-changed

Flags:

RUN_LAST

Parameters:

menuitem (Dbusmenu.Menuitem) – The object which received the signal
arg1 (str) – The name of the property that changed
arg2 (GLib.Variant) – The new value of the property

Emitted everytime a property on a menuitem is either updated or added.

Dbusmenu.Menuitem.signals.realized(menuitem)¶

Signal Name:: realized
Flags:: RUN_LAST
Parameters:: menuitem (Dbusmenu.Menuitem) – The object which received the signal

Emitted when the initial request for properties is complete on the item. If there is a type handler configured for the “type” parameter that will be executed before this is signaled.

Dbusmenu.Menuitem.signals.show_to_user(menuitem, arg1)¶

Signal Name:

show-to-user

Flags:

RUN_LAST

Parameters:

menuitem (Dbusmenu.Menuitem) – The object which received the signal
arg1 (int) – Timestamp the event happened at

Signaled when the application would like the visualization of this menu item shown to the user. This usually requires going over the bus to get it done.

Property Details¶

Dbusmenu.Menuitem.props.id¶

Name:: id
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

This is a unique indentifier for the menu item.