DbusmenuClient

+ + +

DbusmenuClient

DbusmenuClient — The catcher of all the server traffic

Stability Level

+Unstable, unless otherwise indicated +

Synopsis

+#include <libdbusmenu-glib/client.h>
+
+#define             DBUSMENU_CLIENT_SIGNAL_LAYOUT_UPDATED
+#define             DBUSMENU_CLIENT_SIGNAL_ROOT_CHANGED
+#define             DBUSMENU_CLIENT_SIGNAL_NEW_MENUITEM
+#define             DBUSMENU_CLIENT_PROP_DBUS_NAME
+#define             DBUSMENU_CLIENT_PROP_DBUS_OBJECT
+#define             DBUSMENU_CLIENT_TYPES_DEFAULT
+#define             DBUSMENU_CLIENT_TYPES_SEPARATOR
+#define             DBUSMENU_CLIENT_TYPES_IMAGE
+                    DbusmenuClientClass;
+gboolean            (*DbusmenuClientTypeHandler)        (DbusmenuMenuitem *newitem,
+                                                         DbusmenuMenuitem *parent,
+                                                         DbusmenuClient *client);
+DbusmenuClient *    dbusmenu_client_new                 (const gchar *name,
+                                                         const gchar *object);
+DbusmenuMenuitem *  dbusmenu_client_get_root            (DbusmenuClient *client);
+gboolean            dbusmenu_client_add_type_handler    (DbusmenuClient *client,
+                                                         const gchar *type,
+                                                         DbusmenuClientTypeHandler newfunc);
+void                dbusmenu_client_send_event          (DbusmenuClient *client,
+                                                         gint id,
+                                                         const gchar *name,
+                                                         const GValue *value,
+                                                         guint timestamp);
+void                dbusmenu_client_send_about_to_show  (DbusmenuClient *client,
+                                                         gint id,
+                                                         void (cbgpointer user_data) (),
+                                                         gpointer cb_data);
+

Description

+The client exists as a mirror to the server. For most folks + all they will do with a client is set it up to connect to + a server and then watch as the menu items on their side + of the bus change. This is all they should need to know about + the client, that it magically makes their menuitems dance. +

+ It does this by setting up signal watchers and adjusting + the menuitems appropriately. Most users should watch the + menu items and the signal "layout-changed" for + larger events so that they can be optimized. It is possible + with that signal that even the root node would change. If + that doesn't happen the normal signals on the individual + nodes should be enough for most users. +

Details

DBUSMENU_CLIENT_SIGNAL_LAYOUT_UPDATED

#define DBUSMENU_CLIENT_SIGNAL_LAYOUT_UPDATED  "layout-updated"
+

DBUSMENU_CLIENT_SIGNAL_ROOT_CHANGED

#define DBUSMENU_CLIENT_SIGNAL_ROOT_CHANGED    "root-changed"
+

DBUSMENU_CLIENT_SIGNAL_NEW_MENUITEM

#define DBUSMENU_CLIENT_SIGNAL_NEW_MENUITEM    "new-menuitem"
+

DBUSMENU_CLIENT_PROP_DBUS_NAME

#define DBUSMENU_CLIENT_PROP_DBUS_NAME     "dbus-name"
+

DBUSMENU_CLIENT_PROP_DBUS_OBJECT

#define DBUSMENU_CLIENT_PROP_DBUS_OBJECT   "dbus-object"
+

DBUSMENU_CLIENT_TYPES_DEFAULT

#define DBUSMENU_CLIENT_TYPES_DEFAULT      "standard"
+

DBUSMENU_CLIENT_TYPES_SEPARATOR

#define DBUSMENU_CLIENT_TYPES_SEPARATOR    "separator"
+

DBUSMENU_CLIENT_TYPES_IMAGE

#define DBUSMENU_CLIENT_TYPES_IMAGE        "standard"
+

DbusmenuClientClass

typedef struct {
+	GObjectClass parent_class;
+
+	void (*layout_updated)(void);
+	void (*root_changed) (DbusmenuMenuitem * newroot);
+	void (*new_menuitem) (DbusmenuMenuitem * newitem);
+
+	/* Reserved for future use */
+	void (*reserved1) (void);
+	void (*reserved2) (void);
+	void (*reserved3) (void);
+	void (*reserved4) (void);
+} DbusmenuClientClass;
+

+A simple class that takes all of the information from a + DbusmenuServer over DBus and makes the same set of + DbusmenuMenuitem objects appear on the other side. +

++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

GObjectClass `parent_class`;	+GObjectClass +
`layout_updated` ()	Slot for "layout-updated". +
`root_changed` ()	+
`new_menuitem` ()	Slot for "new-menuitem". +
`reserved1` ()	Reserved for future use. +
`reserved2` ()	Reserved for future use. +
`reserved3` ()	Reserved for future use. +
`reserved4` ()	Reserved for future use. +

DbusmenuClientTypeHandler ()

gboolean            (*DbusmenuClientTypeHandler)        (DbusmenuMenuitem *newitem,
+                                                         DbusmenuMenuitem *parent,
+                                                         DbusmenuClient *client);

++ + + + + + + + + + + + + + + + + + +

`newitem` :	+
`parent` :	+
`client` :	+
Returns :	+

dbusmenu_client_new ()

DbusmenuClient *    dbusmenu_client_new                 (const gchar *name,
+                                                         const gchar *object);

+This function creates a new client that connects to a specific + server on DBus. That server is at a specific location sharing + a known object. The interface is assumed by the code to be + the DBus menu interface. The newly created client will start + sending out events as it syncs up with the server. +

++ + + + + + + + + + + + + + +

`name` :	The DBus name for the server to connect to +
`object` :	The object on the server to monitor +
Returns :	A brand new DbusmenuClient +

dbusmenu_client_get_root ()

DbusmenuMenuitem *  dbusmenu_client_get_root            (DbusmenuClient *client);

+Grabs the root node for the specified client client. This + function may block. It will block if there is currently a + call to update the layout, it will block on that layout + updated and then return the newly updated layout. Chances + are that this update is in the queue for the mainloop as + it would have been requested some time ago, but in theory + it could block longer. +

++ + + + + + + + + + +

`client` :	The DbusmenuClient to get the root node from +
Returns :	A DbusmenuMenuitem representing the root of + menu on the server. If there is no server or there is + an error receiving its layout it'll return NULL. +

dbusmenu_client_add_type_handler ()

gboolean            dbusmenu_client_add_type_handler    (DbusmenuClient *client,
+                                                         const gchar *type,
+                                                         DbusmenuClientTypeHandler newfunc);

+This function connects into the type handling of the DbusmenuClient. + Every new menuitem that comes in immediately gets asked for it's + properties. When we get those properties we check the 'type' + property and look to see if it matches a handler that is known + by the client. If so, the newfunc function is executed on that + DbusmenuMenuitem. If not, then the DbusmenuClient::new-menuitem + signal is sent. +

+ In the future the known types will be sent to the server so that it + can make choices about the menu item types availble. +

++ + + + + + + + + + + + + + + + + + +

`client` :	Client where we're getting types coming in +
`type` :	A text string that will be matched with the 'type' + property on incoming menu items +
`newfunc` :	The function that will be executed with those new + items when they come in. +
Returns :	If registering the new type was successful. +

dbusmenu_client_send_event ()

void                dbusmenu_client_send_event          (DbusmenuClient *client,
+                                                         gint id,
+                                                         const gchar *name,
+                                                         const GValue *value,
+                                                         guint timestamp);

++ + + + + + + + + + + + + + + + + + + + + + +

`client` :	+
`id` :	+
`name` :	+
`value` :	+
`timestamp` :	+

dbusmenu_client_send_about_to_show ()

void                dbusmenu_client_send_about_to_show  (DbusmenuClient *client,
+                                                         gint id,
+                                                         void (cbgpointer user_data) (),
+                                                         gpointer cb_data);

++ + + + + + + + + + + + + + +

`client` :	+
`id` :	+`gpointer` user_data: +
`cb_data` :	+

			libdbusmenu-glib Reference Manual
+Top + \| + Description +