path: root/docs/libdbusmenu-glib/reference/xml/client.xml

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<refentry id="libdbusmenu-glib-DbusmenuClient">
<refmeta>
<refentrytitle role="top_of_page" id="libdbusmenu-glib-DbusmenuClient.top_of_page">DbusmenuClient</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  LIBDBUSMENU-GLIB Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>DbusmenuClient</refname>
<refpurpose>The catcher of all the server traffic</refpurpose>
</refnamediv>
<refsect1 id="libdbusmenu-glib-DbusmenuClient.stability-level">
<title>Stability Level</title>
Unstable, unless otherwise indicated
</refsect1>

<refsynopsisdiv id="libdbusmenu-glib-DbusmenuClient.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
#include &lt;libdbusmenu-glib/client.h&gt;

#define             <link linkend="DBUSMENU-CLIENT-SIGNAL-LAYOUT-UPDATED:CAPS">DBUSMENU_CLIENT_SIGNAL_LAYOUT_UPDATED</link>
#define             <link linkend="DBUSMENU-CLIENT-SIGNAL-ROOT-CHANGED:CAPS">DBUSMENU_CLIENT_SIGNAL_ROOT_CHANGED</link>
#define             <link linkend="DBUSMENU-CLIENT-SIGNAL-NEW-MENUITEM:CAPS">DBUSMENU_CLIENT_SIGNAL_NEW_MENUITEM</link>
#define             <link linkend="DBUSMENU-CLIENT-SIGNAL-EVENT-RESULT:CAPS">DBUSMENU_CLIENT_SIGNAL_EVENT_RESULT</link>
#define             <link linkend="DBUSMENU-CLIENT-SIGNAL-ITEM-ACTIVATE:CAPS">DBUSMENU_CLIENT_SIGNAL_ITEM_ACTIVATE</link>
#define             <link linkend="DBUSMENU-CLIENT-SIGNAL-ICON-THEME-DIRS-CHANGED:CAPS">DBUSMENU_CLIENT_SIGNAL_ICON_THEME_DIRS_CHANGED</link>
#define             <link linkend="DBUSMENU-CLIENT-PROP-DBUS-NAME:CAPS">DBUSMENU_CLIENT_PROP_DBUS_NAME</link>
#define             <link linkend="DBUSMENU-CLIENT-PROP-DBUS-OBJECT:CAPS">DBUSMENU_CLIENT_PROP_DBUS_OBJECT</link>
#define             <link linkend="DBUSMENU-CLIENT-PROP-STATUS:CAPS">DBUSMENU_CLIENT_PROP_STATUS</link>
#define             <link linkend="DBUSMENU-CLIENT-PROP-TEXT-DIRECTION:CAPS">DBUSMENU_CLIENT_PROP_TEXT_DIRECTION</link>
#define             <link linkend="DBUSMENU-CLIENT-TYPES-DEFAULT:CAPS">DBUSMENU_CLIENT_TYPES_DEFAULT</link>
#define             <link linkend="DBUSMENU-CLIENT-TYPES-SEPARATOR:CAPS">DBUSMENU_CLIENT_TYPES_SEPARATOR</link>
#define             <link linkend="DBUSMENU-CLIENT-TYPES-IMAGE:CAPS">DBUSMENU_CLIENT_TYPES_IMAGE</link>
                    <link linkend="DbusmenuClient">DbusmenuClient</link>;
struct              <link linkend="DbusmenuClientClass">DbusmenuClientClass</link>;
<link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            (<link linkend="DbusmenuClientTypeHandler">*DbusmenuClientTypeHandler</link>)        (<parameter><link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link> *newitem</parameter>,
                                                         <parameter><link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link> *parent</parameter>,
                                                         <parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>,
                                                         <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);
<link linkend="DbusmenuClient"><returnvalue>DbusmenuClient</returnvalue></link> *    <link linkend="dbusmenu-client-new">dbusmenu_client_new</link>                 (<parameter>const <link linkend="gchar"><type>gchar</type></link> *name</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *object</parameter>);
<link linkend="GStrv"><returnvalue>GStrv</returnvalue></link>               <link linkend="dbusmenu-client-get-icon-paths">dbusmenu_client_get_icon_paths</link>      (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>);
<link linkend="DbusmenuMenuitem"><returnvalue>DbusmenuMenuitem</returnvalue></link> *  <link linkend="dbusmenu-client-get-root">dbusmenu_client_get_root</link>            (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>);
<link linkend="DbusmenuStatus"><returnvalue>DbusmenuStatus</returnvalue></link>      <link linkend="dbusmenu-client-get-status">dbusmenu_client_get_status</link>          (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>);
<link linkend="DbusmenuTextDirection"><returnvalue>DbusmenuTextDirection</returnvalue></link> <link linkend="dbusmenu-client-get-text-direction">dbusmenu_client_get_text_direction</link>
                                                        (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>);
<link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            <link linkend="dbusmenu-client-add-type-handler">dbusmenu_client_add_type_handler</link>    (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *type</parameter>,
                                                         <parameter><link linkend="DbusmenuClientTypeHandler"><type>DbusmenuClientTypeHandler</type></link> newfunc</parameter>);
<link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            <link linkend="dbusmenu-client-add-type-handler-full">dbusmenu_client_add_type_handler_full</link>
                                                        (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *type</parameter>,
                                                         <parameter><link linkend="DbusmenuClientTypeHandler"><type>DbusmenuClientTypeHandler</type></link> newfunc</parameter>,
                                                         <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>,
                                                         <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> destroy_func</parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="libdbusmenu-glib-DbusmenuClient.description" role="desc">
<title role="desc.title">Description</title>
<para>
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.
</para>
<para>
	It does this by setting up signal watchers and adjusting
	the menuitems appropriately.  Most users should watch the
	menu items and the signal <link linkend="DbusmenuClient-layout-changed"><type>"layout-changed"</type></link> 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.
</para>
</refsect1>
<refsect1 id="libdbusmenu-glib-DbusmenuClient.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="DBUSMENU-CLIENT-SIGNAL-LAYOUT-UPDATED:CAPS" role="macro">
<title>DBUSMENU_CLIENT_SIGNAL_LAYOUT_UPDATED</title>
<indexterm zone="DBUSMENU-CLIENT-SIGNAL-LAYOUT-UPDATED:CAPS"><primary>DBUSMENU_CLIENT_SIGNAL_LAYOUT_UPDATED</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_SIGNAL_LAYOUT_UPDATED  "layout-updated"
</programlisting>
<para>
String to attach to signal <link linkend="DbusmenuClient-layout-updated"><type>"layout-updated"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-SIGNAL-ROOT-CHANGED:CAPS" role="macro">
<title>DBUSMENU_CLIENT_SIGNAL_ROOT_CHANGED</title>
<indexterm zone="DBUSMENU-CLIENT-SIGNAL-ROOT-CHANGED:CAPS"><primary>DBUSMENU_CLIENT_SIGNAL_ROOT_CHANGED</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_SIGNAL_ROOT_CHANGED    "root-changed"
</programlisting>
<para>
String to attach to signal <link linkend="DbusmenuClient-root-changed"><type>"root-changed"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-SIGNAL-NEW-MENUITEM:CAPS" role="macro">
<title>DBUSMENU_CLIENT_SIGNAL_NEW_MENUITEM</title>
<indexterm zone="DBUSMENU-CLIENT-SIGNAL-NEW-MENUITEM:CAPS"><primary>DBUSMENU_CLIENT_SIGNAL_NEW_MENUITEM</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_SIGNAL_NEW_MENUITEM    "new-menuitem"
</programlisting>
<para>
String to attach to signal <link linkend="DbusmenuClient-new-menuitem"><type>"new-menuitem"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-SIGNAL-EVENT-RESULT:CAPS" role="macro">
<title>DBUSMENU_CLIENT_SIGNAL_EVENT_RESULT</title>
<indexterm zone="DBUSMENU-CLIENT-SIGNAL-EVENT-RESULT:CAPS"><primary>DBUSMENU_CLIENT_SIGNAL_EVENT_RESULT</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_SIGNAL_EVENT_RESULT    "event-result"
</programlisting>
<para>
String to attach to signal <link linkend="DbusmenuClient-event-result"><type>"event-result"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-SIGNAL-ITEM-ACTIVATE:CAPS" role="macro">
<title>DBUSMENU_CLIENT_SIGNAL_ITEM_ACTIVATE</title>
<indexterm zone="DBUSMENU-CLIENT-SIGNAL-ITEM-ACTIVATE:CAPS"><primary>DBUSMENU_CLIENT_SIGNAL_ITEM_ACTIVATE</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_SIGNAL_ITEM_ACTIVATE   "item-activate"
</programlisting>
<para>
String to attach to signal <link linkend="DbusmenuClient-item-activate"><type>"item-activate"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-SIGNAL-ICON-THEME-DIRS-CHANGED:CAPS" role="macro">
<title>DBUSMENU_CLIENT_SIGNAL_ICON_THEME_DIRS_CHANGED</title>
<indexterm zone="DBUSMENU-CLIENT-SIGNAL-ICON-THEME-DIRS-CHANGED:CAPS"><primary>DBUSMENU_CLIENT_SIGNAL_ICON_THEME_DIRS_CHANGED</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_SIGNAL_ICON_THEME_DIRS_CHANGED    "icon-theme-dirs-changed"
</programlisting>
<para>
String to attach to signal <link linkend="DbusmenuClient-icon-theme-dirs-changed"><type>"icon-theme-dirs-changed"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-PROP-DBUS-NAME:CAPS" role="macro">
<title>DBUSMENU_CLIENT_PROP_DBUS_NAME</title>
<indexterm zone="DBUSMENU-CLIENT-PROP-DBUS-NAME:CAPS"><primary>DBUSMENU_CLIENT_PROP_DBUS_NAME</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_PROP_DBUS_NAME     "dbus-name"
</programlisting>
<para>
String to access property <link linkend="DbusmenuClient--dbus-name"><type>"dbus-name"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-PROP-DBUS-OBJECT:CAPS" role="macro">
<title>DBUSMENU_CLIENT_PROP_DBUS_OBJECT</title>
<indexterm zone="DBUSMENU-CLIENT-PROP-DBUS-OBJECT:CAPS"><primary>DBUSMENU_CLIENT_PROP_DBUS_OBJECT</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_PROP_DBUS_OBJECT   "dbus-object"
</programlisting>
<para>
String to access property <link linkend="DbusmenuClient--dbus-object"><type>"dbus-object"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-PROP-STATUS:CAPS" role="macro">
<title>DBUSMENU_CLIENT_PROP_STATUS</title>
<indexterm zone="DBUSMENU-CLIENT-PROP-STATUS:CAPS"><primary>DBUSMENU_CLIENT_PROP_STATUS</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_PROP_STATUS        "status"
</programlisting>
<para>
String to access property <link linkend="DbusmenuClient--status"><type>"status"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-PROP-TEXT-DIRECTION:CAPS" role="macro">
<title>DBUSMENU_CLIENT_PROP_TEXT_DIRECTION</title>
<indexterm zone="DBUSMENU-CLIENT-PROP-TEXT-DIRECTION:CAPS"><primary>DBUSMENU_CLIENT_PROP_TEXT_DIRECTION</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_PROP_TEXT_DIRECTION "text-direction"
</programlisting>
<para>
String to access property <link linkend="DbusmenuClient--text-direction"><type>"text-direction"</type></link>
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-TYPES-DEFAULT:CAPS" role="macro">
<title>DBUSMENU_CLIENT_TYPES_DEFAULT</title>
<indexterm zone="DBUSMENU-CLIENT-TYPES-DEFAULT:CAPS"><primary>DBUSMENU_CLIENT_TYPES_DEFAULT</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_TYPES_DEFAULT      "standard"
</programlisting>
<para>
Used to set the 'type' property on a menu item to create
a standard menu item.
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-TYPES-SEPARATOR:CAPS" role="macro">
<title>DBUSMENU_CLIENT_TYPES_SEPARATOR</title>
<indexterm zone="DBUSMENU-CLIENT-TYPES-SEPARATOR:CAPS"><primary>DBUSMENU_CLIENT_TYPES_SEPARATOR</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_TYPES_SEPARATOR    "separator"
</programlisting>
<para>
Used to set the 'type' property on a menu item to create
a separator menu item.
</para></refsect2>
<refsect2 id="DBUSMENU-CLIENT-TYPES-IMAGE:CAPS" role="macro">
<title>DBUSMENU_CLIENT_TYPES_IMAGE</title>
<indexterm zone="DBUSMENU-CLIENT-TYPES-IMAGE:CAPS"><primary>DBUSMENU_CLIENT_TYPES_IMAGE</primary></indexterm>
<programlisting>#define DBUSMENU_CLIENT_TYPES_IMAGE        "standard"
</programlisting>
<para>
Used to set the 'type' property on a menu item to create
an image menu item.  Deprecated as standard menu items now
support images as well.
</para></refsect2>
<refsect2 id="DbusmenuClient" role="struct">
<title>DbusmenuClient</title>
<indexterm zone="DbusmenuClient"><primary>DbusmenuClient</primary></indexterm>
<programlisting>typedef struct _DbusmenuClient DbusmenuClient;</programlisting>
<para>
The client for a <link linkend="DbusmenuServer"><type>DbusmenuServer</type></link> creating a shared
	object set of <link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link> objects.
</para></refsect2>
<refsect2 id="DbusmenuClientClass" role="struct">
<title>struct DbusmenuClientClass</title>
<indexterm zone="DbusmenuClientClass"><primary>DbusmenuClientClass</primary></indexterm>
<programlisting>struct DbusmenuClientClass {
	GObjectClass parent_class;

	void (*layout_updated)(void);
	void (*root_changed) (DbusmenuMenuitem * newroot);
	void (*new_menuitem) (DbusmenuMenuitem * newitem);
	void (*item_activate) (DbusmenuMenuitem * item, guint timestamp);
	void (*event_result) (DbusmenuMenuitem * item, gchar * event, GVariant * data, guint timestamp, GError * error);
	void (*icon_theme_dirs) (DbusmenuMenuitem * item, gpointer theme_dirs, GError * error);

	/*&lt; Private &gt;*/
	void (*reserved1) (void);
	void (*reserved2) (void);
	void (*reserved3) (void);
	void (*reserved4) (void);
	void (*reserved5) (void);
};
</programlisting>
<para>
A simple class that takes all of the information from a
	<link linkend="DbusmenuServer"><type>DbusmenuServer</type></link> over DBus and makes the same set of 
	<link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link> objects appear on the other side.
</para><variablelist role="struct">
<varlistentry><term><link linkend="GObjectClass"><type>GObjectClass</type></link>&#160;<structfield id="DbusmenuClientClass.parent-class">parent_class</structfield>;</term>
<listitem><simpara><link linkend="GObjectClass"><type>GObjectClass</type></link></simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.layout-updated">layout_updated</structfield>&#160;()</term>
<listitem><simpara>Slot for <link linkend="DbusmenuClient-layout-updated"><type>"layout-updated"</type></link>.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.root-changed">root_changed</structfield>&#160;()</term>
<listitem><simpara>Slot for <link linkend="DbusmenuClient-root-changed"><type>"root-changed"</type></link>.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.new-menuitem">new_menuitem</structfield>&#160;()</term>
<listitem><simpara>Slot for <link linkend="DbusmenuClient-new-menuitem"><type>"new-menuitem"</type></link>.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.item-activate">item_activate</structfield>&#160;()</term>
<listitem><simpara>Slot for <link linkend="DbusmenuClient-item-activate"><type>"item-activate"</type></link>.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.event-result">event_result</structfield>&#160;()</term>
<listitem><simpara>Slot for <link linkend="DbusmenuClient-event-error"><type>"event-error"</type></link>.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.icon-theme-dirs">icon_theme_dirs</structfield>&#160;()</term>
<listitem><simpara>Slot for <link linkend="DbusmenuClient-icon-theme-dirs-changed"><type>"icon-theme-dirs-changed"</type></link>.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.reserved1">reserved1</structfield>&#160;()</term>
<listitem><simpara>Reserved for future use.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.reserved2">reserved2</structfield>&#160;()</term>
<listitem><simpara>Reserved for future use.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.reserved3">reserved3</structfield>&#160;()</term>
<listitem><simpara>Reserved for future use.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.reserved4">reserved4</structfield>&#160;()</term>
<listitem><simpara>Reserved for future use.</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="DbusmenuClientClass.reserved5">reserved5</structfield>&#160;()</term>
<listitem><simpara>Reserved for future use.</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="DbusmenuClientTypeHandler" role="function">
<title>DbusmenuClientTypeHandler ()</title>
<indexterm zone="DbusmenuClientTypeHandler"><primary>DbusmenuClientTypeHandler</primary></indexterm>
<programlisting><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            (*DbusmenuClientTypeHandler)        (<parameter><link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link> *newitem</parameter>,
                                                         <parameter><link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link> *parent</parameter>,
                                                         <parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>,
                                                         <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</programlisting>
<para>
The type handler is called when a dbusmenu item is created
	with a matching type as setup in <link linkend="dbusmenu-client-add-type-handler"><type>dbusmenu_client_add_type_handler</type></link>
</para><variablelist role="params">
<varlistentry><term><parameter>newitem</parameter>&#160;:</term>
<listitem><simpara>The <link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link> that was created</simpara></listitem></varlistentry>
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara>The parent of <parameter>newitem</parameter> or <link linkend="NULL:CAPS"><type>NULL</type></link> if none</simpara></listitem></varlistentry>
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>A pointer to the <link linkend="DbusmenuClient"><type>DbusmenuClient</type></link></simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>The data you gave us</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><link linkend="TRUE:CAPS"><type>TRUE</type></link> if the type has been handled.  <link linkend="FALSE:CAPS"><type>FALSE</type></link> if this
function was somehow unable to handle it.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="dbusmenu-client-new" role="function">
<title>dbusmenu_client_new ()</title>
<indexterm zone="dbusmenu-client-new"><primary>dbusmenu_client_new</primary></indexterm>
<programlisting><link linkend="DbusmenuClient"><returnvalue>DbusmenuClient</returnvalue></link> *    dbusmenu_client_new                 (<parameter>const <link linkend="gchar"><type>gchar</type></link> *name</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *object</parameter>);</programlisting>
<para>
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.
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>The DBus name for the server to connect to</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>The object on the server to monitor</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A brand new <link linkend="DbusmenuClient"><type>DbusmenuClient</type></link></simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="dbusmenu-client-get-icon-paths" role="function">
<title>dbusmenu_client_get_icon_paths ()</title>
<indexterm zone="dbusmenu-client-get-icon-paths"><primary>dbusmenu_client_get_icon_paths</primary></indexterm>
<programlisting><link linkend="GStrv"><returnvalue>GStrv</returnvalue></link>               dbusmenu_client_get_icon_paths      (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>);</programlisting>
<para>
Gets the stored and exported icon paths from the client.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>The <link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> to get the icon paths from</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A NULL-terminated list of icon paths with
memory managed by the client.  Duplicate if you want
to keep them. <emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="dbusmenu-client-get-root" role="function">
<title>dbusmenu_client_get_root ()</title>
<indexterm zone="dbusmenu-client-get-root"><primary>dbusmenu_client_get_root</primary></indexterm>
<programlisting><link linkend="DbusmenuMenuitem"><returnvalue>DbusmenuMenuitem</returnvalue></link> *  dbusmenu_client_get_root            (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>);</programlisting>
<para>
Grabs the root node for the specified client <parameter>client</parameter>.  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.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>The <link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> to get the root node from</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A <link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link> representing the root of
menu on the server.  If there is no server or there is
an error receiving its layout it'll return <link linkend="NULL:CAPS"><type>NULL</type></link>. <emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="dbusmenu-client-get-status" role="function">
<title>dbusmenu_client_get_status ()</title>
<indexterm zone="dbusmenu-client-get-status"><primary>dbusmenu_client_get_status</primary></indexterm>
<programlisting><link linkend="DbusmenuStatus"><returnvalue>DbusmenuStatus</returnvalue></link>      dbusmenu_client_get_status          (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>);</programlisting>
<para>
Gets the recommended current status that the server
	is exporting for the menus.  In situtations where the
	value is <link linkend="DBUSMENU-STATUS-NOTICE:CAPS"><type>DBUSMENU_STATUS_NOTICE</type></link> it is recommended that
	the client show the menus to the user an a more noticible
	way.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> to check the status on</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Status being exported.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="dbusmenu-client-get-text-direction" role="function">
<title>dbusmenu_client_get_text_direction ()</title>
<indexterm zone="dbusmenu-client-get-text-direction"><primary>dbusmenu_client_get_text_direction</primary></indexterm>
<programlisting><link linkend="DbusmenuTextDirection"><returnvalue>DbusmenuTextDirection</returnvalue></link> dbusmenu_client_get_text_direction
                                                        (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>);</programlisting>
<para>
Gets the text direction that the server is exporting.  If
	the server is not exporting a direction then the value
	<link linkend="DBUSMENU-TEXT-DIRECTION-NONE:CAPS"><type>DBUSMENU_TEXT_DIRECTION_NONE</type></link> will be returned.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> to check the text direction on</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Text direction being exported.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="dbusmenu-client-add-type-handler" role="function">
<title>dbusmenu_client_add_type_handler ()</title>
<indexterm zone="dbusmenu-client-add-type-handler"><primary>dbusmenu_client_add_type_handler</primary></indexterm>
<programlisting><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            dbusmenu_client_add_type_handler    (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *type</parameter>,
                                                         <parameter><link linkend="DbusmenuClientTypeHandler"><type>DbusmenuClientTypeHandler</type></link> newfunc</parameter>);</programlisting>
<para>
This function connects into the type handling of the <link linkend="DbusmenuClient"><type>DbusmenuClient</type></link>.
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 <parameter>newfunc</parameter> function is executed on that
<link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link>.  If not, then the DbusmenuClient::new-menuitem
signal is sent.
</para>
<para>
In the future the known types will be sent to the server so that it
can make choices about the menu item types availble.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>Client where we're getting types coming in</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara>A text string that will be matched with the 'type'
property on incoming menu items</simpara></listitem></varlistentry>
<varlistentry><term><parameter>newfunc</parameter>&#160;:</term>
<listitem><simpara>The function that will be executed with those new
items when they come in. <emphasis role="annotation">[<acronym>scope notified</acronym>]</emphasis></simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>If registering the new type was successful.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="dbusmenu-client-add-type-handler-full" role="function">
<title>dbusmenu_client_add_type_handler_full ()</title>
<indexterm zone="dbusmenu-client-add-type-handler-full"><primary>dbusmenu_client_add_type_handler_full</primary></indexterm>
<programlisting><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            dbusmenu_client_add_type_handler_full
                                                        (<parameter><link linkend="DbusmenuClient"><type>DbusmenuClient</type></link> *client</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *type</parameter>,
                                                         <parameter><link linkend="DbusmenuClientTypeHandler"><type>DbusmenuClientTypeHandler</type></link> newfunc</parameter>,
                                                         <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>,
                                                         <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> destroy_func</parameter>);</programlisting>
<para>
This function connects into the type handling of the <link linkend="DbusmenuClient"><type>DbusmenuClient</type></link>.
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 <parameter>newfunc</parameter> function is executed on that
<link linkend="DbusmenuMenuitem"><type>DbusmenuMenuitem</type></link>.  If not, then the DbusmenuClient::new-menuitem
signal is sent.
</para>
<para>
In the future the known types will be sent to the server so that it
can make choices about the menu item types availble.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>Client where we're getting types coming in</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara>A text string that will be matched with the 'type'
property on incoming menu items</simpara></listitem></varlistentry>
<varlistentry><term><parameter>newfunc</parameter>&#160;:</term>
<listitem><simpara>The function that will be executed with those new
items when they come in. <emphasis role="annotation">[<acronym>scope notified</acronym>]</emphasis></simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>Data passed to <parameter>newfunc</parameter> when it is called</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_func</parameter>&#160;:</term>
<listitem><simpara>A function that is called when the type handler is
removed (usually on client destruction) which will free
the resources in <parameter>user_data</parameter>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>If registering the new type was successful.</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>

</refentry>