A DBus interface to expose menus on DBus. More...

#include <mainpage.h>

Signals
void	ItemsPropertiesUpdated (Array< Struct< Int32, Dict< String, Variant >>> updatedProps, Array< Struct< Int32, Array< String >>> removedProps)

void	LayoutUpdated (UInt32 revision, Int32 parent)

void	ItemActivationRequested (Int32 id, UInt32 timestamp)

Public Member Functions
void	GetLayout (Int32 parentId, Int32 recursionDepth, Array< String > propertyNames, UInt32 revision, Struct< Int32, Dict< String, Variant >, Array< Variant >> layout)

void	GetGroupProperties (Array< Int32 > ids, Array< String > propertyNames, Array< Struct< Int32, Dict< String, Variant >>> properties)

void	GetProperty (Int32 id, String name, Variant value)

void	Event (Int32 id, String eventId, Variant data, UInt32 timestamp)

void	AboutToShow (Int32 id, Boolean needUpdate)

Properties
UInt32	Version

String	Status

Detailed Description

A DBus interface to expose menus on DBus.

Menu items are represented with a unique numeric id and a dictionary of properties.

To reduce the amount of DBus traffic, a property should only be returned if its value is not the default value.

Available properties are:

Name	Type	Description	Default Value
type	String	Can be one of: "standard": an item which can be clicked to trigger an action or show another menu "separator": a separator Vendor specific types can be added by prefixing them with "x-<vendor>-".	"standard"
label	string	Text of the item, except that: two consecutive underscore characters "__" are displayed as a single underscore, any remaining underscore characters are not displayed at all, the first of those remaining underscore characters (unless it is the last character in the string) indicates that the following character is the access key.	""
enabled	boolean	Whether the item can be activated or not.	true
visible	boolean	True if the item is visible in the menu.	true
icon-name	string	Icon name of the item, following the freedesktop.org icon spec.	""
icon-data	binary	PNG data of the icon.	Empty
shortcut	array of arrays of strings	The shortcut of the item. Each array represents the key press in the list of keypresses. Each list of strings contains a list of modifiers and then the key that is used. The modifier strings allowed are: "Control", "Alt", "Shift" and "Super". A simple shortcut like Ctrl+S is represented as: [["Control", "S"]] A complex shortcut like Ctrl+Q, Alt+X is represented as: [["Control", "Q"], ["Alt", "X"]]	Empty
toggle-type	string	If the item can be toggled, this property should be set to: "checkmark": Item is an independent togglable item "radio": Item is part of a group where only one item can be toggled at a time "": Item cannot be toggled	""
toggle-state	int	Describe the current state of a "togglable" item. Can be one of: 0 = off 1 = on anything else = indeterminate Note: The implementation does not itself handle ensuring that only one item in a radio group is set to "on", or that a group does not have "on" and "indeterminate" items simultaneously; maintaining this policy is up to the toolkit wrappers.	-1
children-display	string	If the menu item has children this property should be set to "submenu".	""

Vendor specific properties can be added by prefixing them with "x-<vendor>-".

Member Function Documentation

◆ AboutToShow()

void com::canonical::dbusmenu::AboutToShow	(	Int32	id,
		Boolean	needUpdate
	)

     This is called by the applet to notify the application that it is about
     to show the menu under the specified item.

Parameters

[in]	id	Which menu item represents the parent of the item about to be shown.
[out]	needUpdate	Whether this AboutToShow event should result in the menu being updated.

◆ Event()

void com::canonical::dbusmenu::Event	(	Int32	id,
		String	eventId,
		Variant	data,
		UInt32	timestamp
	)

     This is called by the applet to notify the application an event happened on a
     menu item.

     @a type can be one of the following:

     @li "clicked"
     @li "hovered"

     Vendor specific events can be added by prefixing them with "x-<vendor>-"

Parameters

[in]	id	the id of the item which received the event
[in]	eventId	the type of event
[in]	data	event-specific data
[in]	timestamp	The time that the event occured if available or the time the message was sent if not

◆ GetGroupProperties()

void com::canonical::dbusmenu::GetGroupProperties	(	Array< Int32 >	ids,
		Array< String >	propertyNames,
		Array< Struct< Int32, Dict< String, Variant >>>	properties
	)

     Returns the list of items which are children of @a parentId.

Parameters

[in]	ids	A list of ids that we should be finding the properties on. If the list is empty, all menu items should be sent.
[in]	propertyNames	The list of item properties we are interested in. If there are no entries in the list all of the properties will be sent.
[out]	properties	An array of property values. An item in this area is represented as a struct following this format: id unsigned the item id properties map(string => variant) the requested item properties

◆ GetLayout()

void com::canonical::dbusmenu::GetLayout	(	Int32	parentId,
		Int32	recursionDepth,
		Array< String >	propertyNames,
		UInt32	revision,
		Struct< Int32, Dict< String, Variant >, Array< Variant >>	layout
	)

       Provides the layout and propertiers that are attached to the entries
       that are in the layout.  It only gives the items that are children
       of the item that is specified in @a parentId.  It will return all of the
       properties or specific ones depending of the value in @a propertyNames.

       The format is recursive, where the second 'v' is in the same format
       as the original 'a(ia{sv}av)'.  Its content depends on the value
       of @a recursionDepth.

Parameters

[in]	parentId	The ID of the parent node for the layout. For grabbing the layout from the root node use zero.
[in]	recursionDepth	The amount of levels of recursion to use. This affects the content of the second variant array. -1: deliver all the items under the parentId. 0: no recursion, the array will be empty. n: array will contains items up to 'n' level depth.
[in]	propertyNames	The list of item properties we are interested in. If there are no entries in the list all of the properties will be sent.
[out]	revision	The revision number of the layout. For matching with layoutUpdated signals.
[out]	layout	The layout, as a recursive structure.

◆ GetProperty()

void com::canonical::dbusmenu::GetProperty	(	Int32	id,
		String	name,
		Variant	value
	)

       Get a signal property on a single item.  This is not useful if you're
       going to implement this interface, it should only be used if you're
       debugging via a commandline tool.

Parameters

[in]	id	the id of the item which received the event
[in]	name	the name of the property to get
[out]	value	the value of the property

◆ ItemActivationRequested

void com::canonical::dbusmenu::ItemActivationRequested	(	Int32	id,
		UInt32	timestamp
	)

signal

       The server is requesting that all clients displaying this
       menu open it to the user.  This would be for things like
       hotkeys that when the user presses them the menu should
       open and display itself to the user.

Parameters

[out]	id	ID of the menu that should be activated
[out]	timestamp	The time that the event occured

◆ ItemsPropertiesUpdated

void com::canonical::dbusmenu::ItemsPropertiesUpdated	(	Array< Struct< Int32, Dict< String, Variant >>>	updatedProps,
		Array< Struct< Int32, Array< String >>>	removedProps
	)

signal

     Triggered when there are lots of property updates across many items
     so they all get grouped into a single dbus message.  The format is
     the ID of the item with a hashtable of names and values for those
     properties.

Parameters

[out]	updatedProps
[out]	removedProps

◆ LayoutUpdated

void com::canonical::dbusmenu::LayoutUpdated	(	UInt32	revision,
		Int32	parent
	)

signal

     Triggered by the application to notify display of a layout update, up to
     revision

Parameters

[out]	revision	The revision of the layout that we're currently on
[out]	parent	If the layout update is only of a subtree, this is the parent item for the entries that have changed. It is zero if the whole layout should be considered invalid.

Property Documentation

◆ Status

com::canonical::dbusmenu::Status

read

        Tells if the menus are in a normal state or they believe that they
        could use some attention.  Cases for showing them would be if help
        were referring to them or they accessors were being highlighted.
        This property can have two values: "normal" in almost all cases and
        "notice" when they should have a higher priority to be shown.

Access: read

◆ Version

com::canonical::dbusmenu::Version

read

        Provides the version of the DBusmenu API that this API is
        implementing.

Access: read

Signals

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ AboutToShow()

◆ Event()

◆ GetGroupProperties()

◆ GetLayout()

◆ GetProperty()

◆ ItemActivationRequested

◆ ItemsPropertiesUpdated

◆ LayoutUpdated

Property Documentation

◆ Status

◆ Version