DbusmenuGtkClient

3 LIBDBUSMENU-GTK Library

DbusmenuGtkClient

A subclass of `DbusmenuClient` adding GTK level features

## Stability Level

Unstable, unless otherwise indicated

# Synopsis

    #include <libdbusmenu-gtk/client.h>

    #define             DBUSMENU_GTKCLIENT_SIGNAL_ROOT_CHANGED
                        DbusmenuGtkClient;
    struct              DbusmenuGtkClientClass;
    DbusmenuGtkClient * dbusmenu_gtkclient_new              (gchar *dbus_name,
                                                             gchar *dbus_object);
    GtkMenuItem *       dbusmenu_gtkclient_menuitem_get     (DbusmenuGtkClient *client,
                                                             DbusmenuMenuitem *item);
    GtkMenu *           dbusmenu_gtkclient_menuitem_get_submenu
                                                            (DbusmenuGtkClient *client,
                                                             DbusmenuMenuitem *item);
    void                dbusmenu_gtkclient_set_accel_group  (DbusmenuGtkClient *client,
                                                             GtkAccelGroup *agroup);
    GtkAccelGroup *     dbusmenu_gtkclient_get_accel_group  (DbusmenuGtkClient *client);
    void                dbusmenu_gtkclient_newitem_base     (DbusmenuGtkClient *client,
                                                             DbusmenuMenuitem *item,
                                                             GtkMenuItem *gmi,
                                                             DbusmenuMenuitem *parent);

## Description

In general, this is just a `GtkMenu`, why else would you care? Oh, because this menu is created by someone else on a server that exists on the other side of DBus. You need a `DbusmenuServer` to be able push the data into this menu.

The first thing you need to know is how to find that `DbusmenuServer` on DBus. This involves both the DBus name and the DBus object that the menu interface can be found on. Those two value should be set when creating the object using `dbusmenu_gtkmenu_new()`. They are then stored on two properties `"dbus-name"` and `"dbus-object"`.

After creation the `DbusmenuGtkClient` it will continue to keep in synchronization with the `DbusmenuServer` object across Dbus. If the number of entries change, the menus change, if they change thier properties change, they update in the items. All of this should be handled transparently to the user of this object.

## Details

### DBUSMENU_GTKCLIENT_SIGNAL_ROOT_CHANGED

    #define DBUSMENU_GTKCLIENT_SIGNAL_ROOT_CHANGED  DBUSMENU_CLIENT_SIGNAL_ROOT_CHANGED

String to attach to signal `"root-changed"`

### DbusmenuGtkClient

    typedef struct _DbusmenuGtkClient DbusmenuGtkClient;

A subclass of `DbusmenuClient` to add functionality with regarding building GTK items out of the abstract tree.

### struct DbusmenuGtkClientClass

    struct DbusmenuGtkClientClass {
    	DbusmenuClientClass parent_class;

    	/* Signals */
    	void (*root_changed) (DbusmenuMenuitem * newroot);

    	/*< Private >*/
    	void (*reserved1) (void);
    	void (*reserved2) (void);
    	void (*reserved3) (void);
    	void (*reserved4) (void);
    	void (*reserved5) (void);
    	void (*reserved6) (void);
    };

Functions and signal slots for using a `DbusmenuGtkClient`

`DbusmenuClientClass` parent_class;

- `GtkMenuClass`

root_changed ()

- Slot for signal `"root-changed"`

reserved1 ()

- Reserved for future use.

reserved2 ()

- Reserved for future use.

reserved3 ()

- Reserved for future use.

reserved4 ()

- Reserved for future use.

reserved5 ()

- Reserved for future use.

reserved6 ()

- Reserved for future use.

### dbusmenu_gtkclient_new ()

    DbusmenuGtkClient * dbusmenu_gtkclient_new              (gchar *dbus_name,
                                                             gchar *dbus_object);

Creates a new `DbusmenuGtkClient` object and creates a `DbusmenuClient` that connects across DBus to a `DbusmenuServer`.

`dbus_name` :

- Name of the `DbusmenuServer` on DBus

`dbus_object` :

- Name of the object on the `DbusmenuServer`

Returns :

- A new `DbusmenuGtkClient` sync'd with a server

### dbusmenu_gtkclient_menuitem_get ()

    GtkMenuItem *       dbusmenu_gtkclient_menuitem_get     (DbusmenuGtkClient *client,
                                                             DbusmenuMenuitem *item);

This grabs the `GtkMenuItem` that is associated with the `DbusmenuMenuitem`.

`client` :

- A `DbusmenuGtkClient` with the item in it.

`item` :

- `DbusmenuMenuitem` to get associated `GtkMenuItem` on.

Returns :

- The `GtkMenuItem` that can be played with. [transfer none]

### dbusmenu_gtkclient_menuitem_get_submenu ()

    GtkMenu *           dbusmenu_gtkclient_menuitem_get_submenu
                                                            (DbusmenuGtkClient *client,
                                                             DbusmenuMenuitem *item);

This grabs the submenu associated with the menuitem.

`client` :

- A `DbusmenuGtkClient` with the item in it.

`item` :

- `DbusmenuMenuitem` to get associated `GtkMenu` on.

Returns :

- The `GtkMenu` if there is one. [transfer none]

### dbusmenu_gtkclient_set_accel_group ()

    void                dbusmenu_gtkclient_set_accel_group  (DbusmenuGtkClient *client,
                                                             GtkAccelGroup *agroup);

Sets the acceleration group for the menu items with accelerators on this client.

`client` :

- To set the group on

`agroup` :

- The new acceleration group

### dbusmenu_gtkclient_get_accel_group ()

    GtkAccelGroup *     dbusmenu_gtkclient_get_accel_group  (DbusmenuGtkClient *client);

Gets the accel group for this client.

`client` :

- Client to query for an accelerator group

Returns :

- Either a valid group or `NULL` on error or none set. [transfer none]

### dbusmenu_gtkclient_newitem_base ()

    void                dbusmenu_gtkclient_newitem_base     (DbusmenuGtkClient *client,
                                                             DbusmenuMenuitem *item,
                                                             GtkMenuItem *gmi,
                                                             DbusmenuMenuitem *parent);

This function provides some of the basic connectivity for being in the GTK world. Things like visibility and sensitivity of the item are handled here so that the subclasses don't have to. If you're building your on GTK menu item you can use this function to apply those basic attributes so that you don't have to deal with them either.

This also handles passing the "activate" signal back to the `DbusmenuMenuitem` side of thing.

`client` :

- The client handling everything on this connection

`item` :

- The `DbusmenuMenuitem` to attach the GTK-isms to

`gmi` :

- A `GtkMenuItem` representing the GTK world's view of this menuitem

`parent` :

- The parent `DbusmenuMenuitem`