<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="xfconf-xfconf-binding">
<refmeta>
<refentrytitle role="top_of_page" id="xfconf-xfconf-binding.top_of_page">Xfconf-GObject Binding</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>XFCONF Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Xfconf-GObject Binding</refname>
<refpurpose>Functions to bind Xfconf properties to GObject properties</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="xfconf-xfconf-binding.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
<link linkend="gulong">gulong</link>              <link linkend="xfconf-g-property-bind">xfconf_g_property_bind</link>              (<link linkend="XfconfChannel">XfconfChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *xfconf_property,
                                                         <link linkend="GType">GType</link> xfconf_property_type,
                                                         <link linkend="gpointer">gpointer</link> object,
                                                         const <link linkend="gchar">gchar</link> *object_property);
<link linkend="gulong">gulong</link>              <link linkend="xfconf-g-property-bind-gdkcolor">xfconf_g_property_bind_gdkcolor</link>     (<link linkend="XfconfChannel">XfconfChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *xfconf_property,
                                                         <link linkend="gpointer">gpointer</link> object,
                                                         const <link linkend="gchar">gchar</link> *object_property);
<link linkend="void">void</link>                <link linkend="xfconf-g-property-unbind">xfconf_g_property_unbind</link>            (<link linkend="gulong">gulong</link> id);
<link linkend="void">void</link>                <link linkend="xfconf-g-property-unbind-by-property">xfconf_g_property_unbind_by_property</link>
                                                        (<link linkend="XfconfChannel">XfconfChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *xfconf_property,
                                                         <link linkend="gpointer">gpointer</link> object,
                                                         const <link linkend="gchar">gchar</link> *object_property);
<link linkend="void">void</link>                <link linkend="xfconf-g-property-unbind-all">xfconf_g_property_unbind_all</link>        (<link linkend="gpointer">gpointer</link> channel_or_object);
</synopsis>
</refsynopsisdiv>









<refsect1 id="xfconf-xfconf-binding.description" role="desc">
<title role="desc.title">Description</title>
<para>
Often it may be useful to bind an Xfconf property to a GObject property.
Settings dialogs often display the current value of an Xfconf property,
and a user may edit the value to change the value in the Xfconf store.
If the Xfconf property changes outside the settings dialog, the user will
usually want to see the settings dialog automatically update to reflect
the new value.

With a single line of code, Xfconf's binding functionality can automate
all this.
</para>
</refsect1>

<refsect1 id="xfconf-xfconf-binding.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="xfconf-g-property-bind" role="function">
<title>xfconf_g_property_bind ()</title>
<indexterm zone="xfconf-g-property-bind"><primary>xfconf_g_property_bind</primary></indexterm><programlisting><link linkend="gulong">gulong</link>              xfconf_g_property_bind              (<link linkend="XfconfChannel">XfconfChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *xfconf_property,
                                                         <link linkend="GType">GType</link> xfconf_property_type,
                                                         <link linkend="gpointer">gpointer</link> object,
                                                         const <link linkend="gchar">gchar</link> *object_property);</programlisting>
<para>
Binds an Xfconf property to a <link linkend="GObject"><type>GObject</type></link> property.  If the property
is changed via either the <link linkend="GObject"><type>GObject</type></link> or Xfconf, the corresponding
property will also be updated.
</para>
<para>
Note that <parameter>xfconf_property_type</parameter> is required since <parameter>xfconf_property</parameter>
may or may not already exist in the Xfconf store.  The type of
<parameter>object_property</parameter> will be determined automatically.  If the two
types do not match, a conversion will be attempted.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> An <link linkend="XfconfChannel"><type>XfconfChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xfconf_property</parameter>&nbsp;:</term>
<listitem><simpara> A property on <parameter>channel</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xfconf_property_type</parameter>&nbsp;:</term>
<listitem><simpara> The type of <parameter>xfconf_property</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object</parameter>&nbsp;:</term>
<listitem><simpara> A <link linkend="GObject"><type>GObject</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object_property</parameter>&nbsp;:</term>
<listitem><simpara> A valid property on <parameter>object</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> an ID number that can be used to later remove the
         binding.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="xfconf-g-property-bind-gdkcolor" role="function">
<title>xfconf_g_property_bind_gdkcolor ()</title>
<indexterm zone="xfconf-g-property-bind-gdkcolor"><primary>xfconf_g_property_bind_gdkcolor</primary></indexterm><programlisting><link linkend="gulong">gulong</link>              xfconf_g_property_bind_gdkcolor     (<link linkend="XfconfChannel">XfconfChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *xfconf_property,
                                                         <link linkend="gpointer">gpointer</link> object,
                                                         const <link linkend="gchar">gchar</link> *object_property);</programlisting>
<para>
Binds an Xfconf property to a <link linkend="GObject"><type>GObject</type></link> property of type
GDK_TYPE_COLOR (aka a <link linkend="GdkColor"><type>GdkColor</type></link> struct).  If the property
is changed via either the <link linkend="GObject"><type>GObject</type></link> or Xfconf, the corresponding
property will also be updated.
</para>
<para>
This is a special-case binding; the GdkColor struct is not
ideal as-is for binding to a property, so it is stored in the
Xfconf store as four 16-bit unsigned ints (red, green, blue, alpha).
Since GdkColor (currently) only supports RGB and not RGBA,
the last value will always be set to 0xFFFF.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> An <link linkend="XfconfChannel"><type>XfconfChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xfconf_property</parameter>&nbsp;:</term>
<listitem><simpara> A property on <parameter>channel</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object</parameter>&nbsp;:</term>
<listitem><simpara> A <link linkend="GObject"><type>GObject</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object_property</parameter>&nbsp;:</term>
<listitem><simpara> A valid property on <parameter>object</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> an ID number that can be used to later remove the
         binding.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="xfconf-g-property-unbind" role="function">
<title>xfconf_g_property_unbind ()</title>
<indexterm zone="xfconf-g-property-unbind"><primary>xfconf_g_property_unbind</primary></indexterm><programlisting><link linkend="void">void</link>                xfconf_g_property_unbind            (<link linkend="gulong">gulong</link> id);</programlisting>
<para>
Removes an Xfconf/GObject property binding based on the binding
ID number.  See <link linkend="xfconf-g-property-bind"><function>xfconf_g_property_bind()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>id</parameter>&nbsp;:</term>
<listitem><simpara> A binding ID number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="xfconf-g-property-unbind-by-property" role="function">
<title>xfconf_g_property_unbind_by_property ()</title>
<indexterm zone="xfconf-g-property-unbind-by-property"><primary>xfconf_g_property_unbind_by_property</primary></indexterm><programlisting><link linkend="void">void</link>                xfconf_g_property_unbind_by_property
                                                        (<link linkend="XfconfChannel">XfconfChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *xfconf_property,
                                                         <link linkend="gpointer">gpointer</link> object,
                                                         const <link linkend="gchar">gchar</link> *object_property);</programlisting>
<para>
Causes an Xfconf channel previously bound to a <link linkend="GObject"><type>GObject</type></link> property
(see <link linkend="xfconf-g-property-bind"><function>xfconf_g_property_bind()</function></link>) to no longer be bound.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> An <link linkend="XfconfChannel"><type>XfconfChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xfconf_property</parameter>&nbsp;:</term>
<listitem><simpara> A bound property on <parameter>channel</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object</parameter>&nbsp;:</term>
<listitem><simpara> A <link linkend="GObject"><type>GObject</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object_property</parameter>&nbsp;:</term>
<listitem><simpara> A bound property on <parameter>object</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="xfconf-g-property-unbind-all" role="function">
<title>xfconf_g_property_unbind_all ()</title>
<indexterm zone="xfconf-g-property-unbind-all"><primary>xfconf_g_property_unbind_all</primary></indexterm><programlisting><link linkend="void">void</link>                xfconf_g_property_unbind_all        (<link linkend="gpointer">gpointer</link> channel_or_object);</programlisting>
<para>
Unbinds all Xfconf channel bindings (see <link linkend="xfconf-g-property-bind"><function>xfconf_g_property_bind()</function></link>)
to <parameter>object</parameter>.  If <parameter>object</parameter> is an <link linkend="XfconfChannel"><type>XfconfChannel</type></link>, it will unbind all
xfconf properties on that channel.  If <parameter>object</parameter> is a regular <link linkend="GObject"><type>GObject</type></link>
with properties bound to a channel, all those bindings will be
removed.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel_or_object</parameter>&nbsp;:</term>
<listitem><simpara> A <link linkend="GObject"><type>GObject</type></link> or <link linkend="XfconfChannel"><type>XfconfChannel</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
