Dbusmenu.Menuitem

g Dbusmenu.Menuitem Dbusmenu.Menuitem GObject.Object GObject.Object GObject.Object->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:
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:
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:

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:

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:

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:

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.