HudAppMenuRegistrar

HudAppMenuRegistrar — client for the com.canonical.AppMenu.Registrar D-Bus service

Synopsis

                    HudAppMenuRegistrar;
void                (*HudAppMenuRegistrarObserverFunc)  (HudAppMenuRegistrar *registrar,
                                                         guint xid,
                                                         const gchar *bus_name,
                                                         const gchar *object_path,
                                                         gpointer user_data);
void                hud_app_menu_registrar_add_observer (HudAppMenuRegistrar *registrar,
                                                         guint xid,
                                                         HudAppMenuRegistrarObserverFunc callback,
                                                         gpointer user_data);
HudAppMenuRegistrar * hud_app_menu_registrar_get        (void);
void                hud_app_menu_registrar_remove_observer
                                                        (HudAppMenuRegistrar *registrar,
                                                         guint xid,
                                                         HudAppMenuRegistrarObserverFunc callback,
                                                         gpointer user_data);

Object Hierarchy

  GObject
   +----HudAppMenuRegistrar

Description

The HudAppMenuRegistrar is a singleton object that monitors the com.canonical.AppMenu.Registrar D-Bus service.

On instantiation, a D-Bus name watch is setup for the registrar. When the registrar is found to exist, a local copy is made of the windows and menus that the registrar knows about. Change notifications are also monitored to keep the local cache in sync.

After that point, all queries for information from the registrar are satisfied from the local cache, without blocking.

Information is acquired from HudAppMenuRegistrar by using hud_app_menu_registrar_add_observer(). This immediately calls a callback with the initial information and makes future calls to the same callback if the information is found to have changed.

If the registrar is offline or the information is not yet available at the time of the original query, the window will initially be reported as having no menu but a change notification will arrive when the proper information becomes available.

Details

HudAppMenuRegistrar

typedef struct _HudAppMenuRegistrar HudAppMenuRegistrar;

This is an opaque structure type.


HudAppMenuRegistrarObserverFunc ()

void                (*HudAppMenuRegistrarObserverFunc)  (HudAppMenuRegistrar *registrar,
                                                         guint xid,
                                                         const gchar *bus_name,
                                                         const gchar *object_path,
                                                         gpointer user_data);

Notifies about the initial values for or changes to the bus name and object path at which to find the dbusmenu for xid.

You should pass the values of bus_name and object_path to dbusmenu_client_new() to get started.

If no menu is available then bus_name and object_path will both be given as NULL.

registrar :

the HudAppMenuRegistrar

xid :

the xid that we are notifying about

bus_name :

the bus name for the dbusmenu, or NULL

object_path :

the object path for the dbusmenu, or NULL

user_data :

the data pointer

hud_app_menu_registrar_add_observer ()

void                hud_app_menu_registrar_add_observer (HudAppMenuRegistrar *registrar,
                                                         guint xid,
                                                         HudAppMenuRegistrarObserverFunc callback,
                                                         gpointer user_data);

Begins observing xid.

callback will be called exactly once before the function returns with a set of initial values (the bus name and object path at which to find the menu for the window).

If the location of the menu for xid changes (including being created or destroyed) then callback will be called each time an update is required.

It is possible that the values are not initially known because they have not yet been retreived from the registrar or because the registrar is not running. In this case, NULL values will be provided initially and callback will be invoked again when the real values are known.

Call hud_app_menu_registrar_remove_observer() to when you are no longer interested in xid.

registrar :

the HudAppMenuRegistrar

xid :

the xid to begin observing

callback :

a HudAppMenuRegistrarObserverFunc

user_data :

user data for callback

hud_app_menu_registrar_get ()

HudAppMenuRegistrar * hud_app_menu_registrar_get        (void);

Gets the singleton instance of HudAppMenuRegistrar.

Returns :

the instance. [transfer none]

hud_app_menu_registrar_remove_observer ()

void                hud_app_menu_registrar_remove_observer
                                                        (HudAppMenuRegistrar *registrar,
                                                         guint xid,
                                                         HudAppMenuRegistrarObserverFunc callback,
                                                         gpointer user_data);

Reverses the effect of a previous call to hud_app_menu_registrar_add_observer().

callback and user_data must be exactly equal to the values passed to that function.

One call does not remove all instances of callback and user_data. You need to call this function the same number of times that you called hud_app_menu_registrar_add_observer().

registrar :

the HudAppMenuRegistrar

xid :

the xid to begin observing

callback :

a HudAppMenuRegistrarObserverFunc

user_data :

user data for callback