<?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'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="gdk-Properties-and-Atoms">
<refmeta>
<refentrytitle role="top_of_page" id="gdk-Properties-and-Atoms.top_of_page">Properties and Atoms</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Properties and Atoms</refname>
<refpurpose>Functions to manipulate properties on windows</refpurpose>
</refnamediv>

<refsynopsisdiv id="gdk-Properties-and-Atoms.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gdk/gdk.h&gt;

                    <link linkend="GdkAtom">GdkAtom</link>;
#define             <link linkend="GDK-ATOM-TO-POINTER--CAPS">GDK_ATOM_TO_POINTER</link>                 (atom)
#define             <link linkend="GDK-POINTER-TO-ATOM--CAPS">GDK_POINTER_TO_ATOM</link>                 (ptr)
#define             <link linkend="GDK-NONE--CAPS">GDK_NONE</link>
<link linkend="gint">gint</link>                <link linkend="gdk-text-property-to-text-list">gdk_text_property_to_text_list</link>      (<link linkend="GdkAtom">GdkAtom</link> encoding,
                                                         <link linkend="gint">gint</link> format,
                                                         const <link linkend="guchar">guchar</link> *text,
                                                         <link linkend="gint">gint</link> length,
                                                         <link linkend="gchar">gchar</link> ***list);
<link linkend="gint">gint</link>                <link linkend="gdk-text-property-to-text-list-for-display">gdk_text_property_to_text_list_for_display</link>
                                                        (<link linkend="GdkDisplay">GdkDisplay</link> *display,
                                                         <link linkend="GdkAtom">GdkAtom</link> encoding,
                                                         <link linkend="gint">gint</link> format,
                                                         const <link linkend="guchar">guchar</link> *text,
                                                         <link linkend="gint">gint</link> length,
                                                         <link linkend="gchar">gchar</link> ***list);
<link linkend="void">void</link>                <link linkend="gdk-free-text-list">gdk_free_text_list</link>                  (<link linkend="gchar">gchar</link> **list);
<link linkend="gint">gint</link>                <link linkend="gdk-text-property-to-utf8-list">gdk_text_property_to_utf8_list</link>      (<link linkend="GdkAtom">GdkAtom</link> encoding,
                                                         <link linkend="gint">gint</link> format,
                                                         const <link linkend="guchar">guchar</link> *text,
                                                         <link linkend="gint">gint</link> length,
                                                         <link linkend="gchar">gchar</link> ***list);
<link linkend="gint">gint</link>                <link linkend="gdk-text-property-to-utf8-list-for-display">gdk_text_property_to_utf8_list_for_display</link>
                                                        (<link linkend="GdkDisplay">GdkDisplay</link> *display,
                                                         <link linkend="GdkAtom">GdkAtom</link> encoding,
                                                         <link linkend="gint">gint</link> format,
                                                         const <link linkend="guchar">guchar</link> *text,
                                                         <link linkend="gint">gint</link> length,
                                                         <link linkend="gchar">gchar</link> ***list);
<link linkend="gint">gint</link>                <link linkend="gdk-string-to-compound-text">gdk_string_to_compound_text</link>         (const <link linkend="gchar">gchar</link> *str,
                                                         <link linkend="GdkAtom">GdkAtom</link> *encoding,
                                                         <link linkend="gint">gint</link> *format,
                                                         <link linkend="guchar">guchar</link> **ctext,
                                                         <link linkend="gint">gint</link> *length);
<link linkend="gint">gint</link>                <link linkend="gdk-string-to-compound-text-for-display">gdk_string_to_compound_text_for_display</link>
                                                        (<link linkend="GdkDisplay">GdkDisplay</link> *display,
                                                         const <link linkend="gchar">gchar</link> *str,
                                                         <link linkend="GdkAtom">GdkAtom</link> *encoding,
                                                         <link linkend="gint">gint</link> *format,
                                                         <link linkend="guchar">guchar</link> **ctext,
                                                         <link linkend="gint">gint</link> *length);
<link linkend="void">void</link>                <link linkend="gdk-free-compound-text">gdk_free_compound_text</link>              (<link linkend="guchar">guchar</link> *ctext);
<link linkend="gchar">gchar</link> *             <link linkend="gdk-utf8-to-string-target">gdk_utf8_to_string_target</link>           (const <link linkend="gchar">gchar</link> *str);
<link linkend="gboolean">gboolean</link>            <link linkend="gdk-utf8-to-compound-text">gdk_utf8_to_compound_text</link>           (const <link linkend="gchar">gchar</link> *str,
                                                         <link linkend="GdkAtom">GdkAtom</link> *encoding,
                                                         <link linkend="gint">gint</link> *format,
                                                         <link linkend="guchar">guchar</link> **ctext,
                                                         <link linkend="gint">gint</link> *length);
<link linkend="gboolean">gboolean</link>            <link linkend="gdk-utf8-to-compound-text-for-display">gdk_utf8_to_compound_text_for_display</link>
                                                        (<link linkend="GdkDisplay">GdkDisplay</link> *display,
                                                         const <link linkend="gchar">gchar</link> *str,
                                                         <link linkend="GdkAtom">GdkAtom</link> *encoding,
                                                         <link linkend="gint">gint</link> *format,
                                                         <link linkend="guchar">guchar</link> **ctext,
                                                         <link linkend="gint">gint</link> *length);
<link linkend="GdkAtom">GdkAtom</link>             <link linkend="gdk-atom-intern">gdk_atom_intern</link>                     (const <link linkend="gchar">gchar</link> *atom_name,
                                                         <link linkend="gboolean">gboolean</link> only_if_exists);
<link linkend="GdkAtom">GdkAtom</link>             <link linkend="gdk-atom-intern-static-string">gdk_atom_intern_static_string</link>       (const <link linkend="gchar">gchar</link> *atom_name);
<link linkend="gchar">gchar</link>*              <link linkend="gdk-atom-name">gdk_atom_name</link>                       (<link linkend="GdkAtom">GdkAtom</link> atom);
<link linkend="gboolean">gboolean</link>            <link linkend="gdk-property-get">gdk_property_get</link>                    (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="GdkAtom">GdkAtom</link> property,
                                                         <link linkend="GdkAtom">GdkAtom</link> type,
                                                         <link linkend="gulong">gulong</link> offset,
                                                         <link linkend="gulong">gulong</link> length,
                                                         <link linkend="gint">gint</link> pdelete,
                                                         <link linkend="GdkAtom">GdkAtom</link> *actual_property_type,
                                                         <link linkend="gint">gint</link> *actual_format,
                                                         <link linkend="gint">gint</link> *actual_length,
                                                         <link linkend="guchar">guchar</link> **data);
<link linkend="void">void</link>                <link linkend="gdk-property-change">gdk_property_change</link>                 (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="GdkAtom">GdkAtom</link> property,
                                                         <link linkend="GdkAtom">GdkAtom</link> type,
                                                         <link linkend="gint">gint</link> format,
                                                         <link linkend="GdkPropMode">GdkPropMode</link> mode,
                                                         const <link linkend="guchar">guchar</link> *data,
                                                         <link linkend="gint">gint</link> nelements);
enum                <link linkend="GdkPropMode">GdkPropMode</link>;
<link linkend="void">void</link>                <link linkend="gdk-property-delete">gdk_property_delete</link>                 (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="GdkAtom">GdkAtom</link> property);
</synopsis>
</refsynopsisdiv>









<refsect1 id="gdk-Properties-and-Atoms.description" role="desc">
<title role="desc.title">Description</title>
<para>
Each window under X can have any number of associated
<firstterm>properties</firstterm> attached to it.
Properties are arbitrary chunks of data identified by
<firstterm>atom</firstterm>s. (An <firstterm>atom</firstterm>
is a numeric index into a string table on the X server. They are used
to transfer strings efficiently between clients without
having to transfer the entire string.) A property
has an associated type, which is also identified
using an atom.
</para>
<para>
A property has an associated <firstterm>format</firstterm>,
an integer describing how many bits are in each unit
of data inside the property. It must be 8, 16, or 32.
When data is transferred between the server and client,
if they are of different endianesses it will be byteswapped
as necessary according to the format of the property.
Note that on the client side, properties of format 32
will be stored with one unit per <emphasis>long</emphasis>,
even if a long integer has more than 32 bits on the platform.
(This decision was apparently made for Xlib to maintain
compatibility with programs that assumed longs were 32
bits, at the expense of programs that knew better.)
</para>
<para>
The functions in this section are used to add, remove
and change properties on windows, to convert atoms
to and from strings and to manipulate some types of
data commonly stored in X window properties.
</para>
</refsect1>

<refsect1 id="gdk-Properties-and-Atoms.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GdkAtom" role="struct">
<title>GdkAtom</title>
<indexterm zone="GdkAtom"><primary sortas="Atom">GdkAtom</primary></indexterm><programlisting>typedef struct _GdkAtom GdkAtom;</programlisting>
<para>
An opaque type representing a string as an index into a table
of strings on the X server.
</para></refsect2>
<refsect2 id="GDK-ATOM-TO-POINTER--CAPS" role="macro">
<title>GDK_ATOM_TO_POINTER()</title>
<indexterm zone="GDK-ATOM-TO-POINTER--CAPS"><primary sortas="ATOM_TO_POINTER">GDK_ATOM_TO_POINTER</primary></indexterm><programlisting>#define GDK_ATOM_TO_POINTER(atom) (atom)
</programlisting>
<para>
Converts a <link linkend="GdkAtom"><type>GdkAtom</type></link> into a pointer type.
</para><variablelist role="params">
<varlistentry><term><parameter>atom</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GdkAtom"><type>GdkAtom</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GDK-POINTER-TO-ATOM--CAPS" role="macro">
<title>GDK_POINTER_TO_ATOM()</title>
<indexterm zone="GDK-POINTER-TO-ATOM--CAPS"><primary sortas="POINTER_TO_ATOM">GDK_POINTER_TO_ATOM</primary></indexterm><programlisting>#define GDK_POINTER_TO_ATOM(ptr)  ((GdkAtom)(ptr))
</programlisting>
<para>
Extracts a <link linkend="GdkAtom"><type>GdkAtom</type></link> from a pointer. The <link linkend="GdkAtom"><type>GdkAtom</type></link> must have been
stored in the pointer with <link linkend="GDK-ATOM-TO-POINTER--CAPS"><function>GDK_ATOM_TO_POINTER()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>ptr</parameter>&#160;:</term>
<listitem><simpara>a pointer containing a <link linkend="GdkAtom"><type>GdkAtom</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GDK-NONE--CAPS" role="macro">
<title>GDK_NONE</title>
<indexterm zone="GDK-NONE--CAPS"><primary sortas="NONE">GDK_NONE</primary></indexterm><programlisting>#define GDK_NONE            _GDK_MAKE_ATOM (0)
</programlisting>
<para>
A null value for <link linkend="GdkAtom"><type>GdkAtom</type></link>, used in a similar way as <literal>None</literal>
in the Xlib API.
</para></refsect2>
<refsect2 id="gdk-text-property-to-text-list" role="function">
<title>gdk_text_property_to_text_list ()</title>
<indexterm zone="gdk-text-property-to-text-list"><primary sortas="text_property_to_text_list">gdk_text_property_to_text_list</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_text_property_to_text_list      (<link linkend="GdkAtom">GdkAtom</link> encoding,
                                                         <link linkend="gint">gint</link> format,
                                                         const <link linkend="guchar">guchar</link> *text,
                                                         <link linkend="gint">gint</link> length,
                                                         <link linkend="gchar">gchar</link> ***list);</programlisting>
<para>
Converts a text string from the encoding as it is stored in
a property into an array of strings in the encoding of
the current local. (The elements of the array represent
the nul-separated elements of the original text string.)
</para><variablelist role="params">
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara>an atom representing the encoding. The most common
           values for this are <literal>STRING</literal>,
           or <literal>COMPOUND_TEXT</literal>. This is
           value used as the type for the property.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>the format of the property.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>text</parameter>&#160;:</term>
<listitem><simpara>the text data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>the length of the property, in items.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>list</parameter>&#160;:</term>
<listitem><simpara>location to store a terminated array of strings
       in the encoding of the current locale. This
       array should be freed using <link linkend="gdk-free-text-list"><function>gdk_free_text_list()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the number of strings stored in <parameter>list</parameter>, or 0,
          if the conversion failed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-text-property-to-text-list-for-display" role="function" condition="since:2.2">
<title>gdk_text_property_to_text_list_for_display ()</title>
<indexterm zone="gdk-text-property-to-text-list-for-display" role="2.2"><primary sortas="text_property_to_text_list_for_display">gdk_text_property_to_text_list_for_display</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_text_property_to_text_list_for_display
                                                        (<link linkend="GdkDisplay">GdkDisplay</link> *display,
                                                         <link linkend="GdkAtom">GdkAtom</link> encoding,
                                                         <link linkend="gint">gint</link> format,
                                                         const <link linkend="guchar">guchar</link> *text,
                                                         <link linkend="gint">gint</link> length,
                                                         <link linkend="gchar">gchar</link> ***list);</programlisting>
<para>
Convert a text string from the encoding as it is stored 
in a property into an array of strings in the encoding of
the current locale. (The elements of the array represent the
nul-separated elements of the original text string.)</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>display</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="GdkDisplay"><type>GdkDisplay</type></link> where the encoding is defined.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara> an atom representing the encoding. The most 
   common values for this are STRING, or COMPOUND_TEXT. 
   This is value used as the type for the property.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara> the format of the property.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>text</parameter>&#160;:</term>
<listitem><simpara> The text data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara> The number of items to transform.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>list</parameter>&#160;:</term>
<listitem><simpara> location to store a terminated array of strings in 
   the encoding of the current locale. This array should be 
   freed using <link linkend="gdk-free-text-list"><function>gdk_free_text_list()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of strings stored in list, or 0, 
if the conversion failed. 

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="gdk-free-text-list" role="function">
<title>gdk_free_text_list ()</title>
<indexterm zone="gdk-free-text-list"><primary sortas="free_text_list">gdk_free_text_list</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_free_text_list                  (<link linkend="gchar">gchar</link> **list);</programlisting>
<para>
Frees the array of strings created by
<link linkend="gdk-text-property-to-text-list"><function>gdk_text_property_to_text_list()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>list</parameter>&#160;:</term>
<listitem><simpara>the value stored in the <parameter>list</parameter> parameter by
       a call to <link linkend="gdk-text-property-to-text-list"><function>gdk_text_property_to_text_list()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-text-property-to-utf8-list" role="function">
<title>gdk_text_property_to_utf8_list ()</title>
<indexterm zone="gdk-text-property-to-utf8-list"><primary sortas="text_property_to_utf8_list">gdk_text_property_to_utf8_list</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_text_property_to_utf8_list      (<link linkend="GdkAtom">GdkAtom</link> encoding,
                                                         <link linkend="gint">gint</link> format,
                                                         const <link linkend="guchar">guchar</link> *text,
                                                         <link linkend="gint">gint</link> length,
                                                         <link linkend="gchar">gchar</link> ***list);</programlisting>
<para>
Convert a text property in the giving encoding to
a list of UTF-8 strings.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara> an atom representing the encoding of the text
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>   the format of the property
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>text</parameter>&#160;:</term>
<listitem><simpara>     the text to convert
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>   the length of <parameter>text</parameter>, in bytes
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>list</parameter>&#160;:</term>
<listitem><simpara>     location to store the list of strings or <link linkend="NULL--CAPS"><literal>NULL</literal></link>. The
           list should be freed with <link linkend="g-strfreev"><function>g_strfreev()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of strings in the resulting
              list.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-text-property-to-utf8-list-for-display" role="function" condition="since:2.2">
<title>gdk_text_property_to_utf8_list_for_display ()</title>
<indexterm zone="gdk-text-property-to-utf8-list-for-display" role="2.2"><primary sortas="text_property_to_utf8_list_for_display">gdk_text_property_to_utf8_list_for_display</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_text_property_to_utf8_list_for_display
                                                        (<link linkend="GdkDisplay">GdkDisplay</link> *display,
                                                         <link linkend="GdkAtom">GdkAtom</link> encoding,
                                                         <link linkend="gint">gint</link> format,
                                                         const <link linkend="guchar">guchar</link> *text,
                                                         <link linkend="gint">gint</link> length,
                                                         <link linkend="gchar">gchar</link> ***list);</programlisting>
<para>
Converts a text property in the given encoding to
a list of UTF-8 strings.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>display</parameter>&#160;:</term>
<listitem><simpara>  a <link linkend="GdkDisplay"><type>GdkDisplay</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara> an atom representing the encoding of the text
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>   the format of the property
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>text</parameter>&#160;:</term>
<listitem><simpara>     the text to convert
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>   the length of <parameter>text</parameter>, in bytes
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>list</parameter>&#160;:</term>
<listitem><simpara>     location to store the list of strings or <link linkend="NULL--CAPS"><literal>NULL</literal></link>. The
           list should be freed with <link linkend="g-strfreev"><function>g_strfreev()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of strings in the resulting
              list.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="gdk-string-to-compound-text" role="function">
<title>gdk_string_to_compound_text ()</title>
<indexterm zone="gdk-string-to-compound-text"><primary sortas="string_to_compound_text">gdk_string_to_compound_text</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_string_to_compound_text         (const <link linkend="gchar">gchar</link> *str,
                                                         <link linkend="GdkAtom">GdkAtom</link> *encoding,
                                                         <link linkend="gint">gint</link> *format,
                                                         <link linkend="guchar">guchar</link> **ctext,
                                                         <link linkend="gint">gint</link> *length);</programlisting>
<para>
Converts a string from the encoding of the current locale
into a form suitable for storing in a window property.
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&#160;:</term>
<listitem><simpara>a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara>location to store the encoding atom (to be used as the type for the property).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>location to store the format for the property.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ctext</parameter>&#160;:</term>
<listitem><simpara>location to store newly allocated data for the property.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>location to store the length of <parameter>ctext</parameter> in items.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>0 upon sucess, non-zero upon failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-string-to-compound-text-for-display" role="function" condition="since:2.2">
<title>gdk_string_to_compound_text_for_display ()</title>
<indexterm zone="gdk-string-to-compound-text-for-display" role="2.2"><primary sortas="string_to_compound_text_for_display">gdk_string_to_compound_text_for_display</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_string_to_compound_text_for_display
                                                        (<link linkend="GdkDisplay">GdkDisplay</link> *display,
                                                         const <link linkend="gchar">gchar</link> *str,
                                                         <link linkend="GdkAtom">GdkAtom</link> *encoding,
                                                         <link linkend="gint">gint</link> *format,
                                                         <link linkend="guchar">guchar</link> **ctext,
                                                         <link linkend="gint">gint</link> *length);</programlisting>
<para>
Convert a string from the encoding of the current 
locale into a form suitable for storing in a window property.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>display</parameter>&#160;:</term>
<listitem><simpara>  the <link linkend="GdkDisplay"><type>GdkDisplay</type></link> where the encoding is defined.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str</parameter>&#160;:</term>
<listitem><simpara>      a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara> location to store the encoding atom 
      (to be used as the type for the property).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>   location to store the format of the property
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ctext</parameter>&#160;:</term>
<listitem><simpara>    location to store newly allocated data for the property.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>   the length of <parameter>text</parameter>, in bytes
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 upon success, non-zero upon failure. 

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="gdk-free-compound-text" role="function">
<title>gdk_free_compound_text ()</title>
<indexterm zone="gdk-free-compound-text"><primary sortas="free_compound_text">gdk_free_compound_text</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_free_compound_text              (<link linkend="guchar">guchar</link> *ctext);</programlisting>
<para>
Frees the data returned from <link linkend="gdk-string-to-compound-text"><function>gdk_string_to_compound_text()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>ctext</parameter>&#160;:</term>
<listitem><simpara>The pointer stored in <parameter>ctext</parameter> from a call to <link linkend="gdk-string-to-compound-text"><function>gdk_string_to_compound_text()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-utf8-to-string-target" role="function">
<title>gdk_utf8_to_string_target ()</title>
<indexterm zone="gdk-utf8-to-string-target"><primary sortas="utf8_to_string_target">gdk_utf8_to_string_target</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             gdk_utf8_to_string_target           (const <link linkend="gchar">gchar</link> *str);</programlisting>
<para>
Convert an UTF-8 string into the best possible representation
as a STRING. The representation of characters not in STRING
is not specified; it may be as pseudo-escape sequences
\x{ABCD}, or it may be in some other form of approximation.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&#160;:</term>
<listitem><simpara> a UTF-8 string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated string, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the
              conversion failed. (It should not fail for
              any properly formed UTF-8 string.)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-utf8-to-compound-text" role="function">
<title>gdk_utf8_to_compound_text ()</title>
<indexterm zone="gdk-utf8-to-compound-text"><primary sortas="utf8_to_compound_text">gdk_utf8_to_compound_text</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gdk_utf8_to_compound_text           (const <link linkend="gchar">gchar</link> *str,
                                                         <link linkend="GdkAtom">GdkAtom</link> *encoding,
                                                         <link linkend="gint">gint</link> *format,
                                                         <link linkend="guchar">guchar</link> **ctext,
                                                         <link linkend="gint">gint</link> *length);</programlisting>
<para>
Convert from UTF-8 to compound text.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&#160;:</term>
<listitem><simpara>      a UTF-8 string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara> location to store resulting encoding
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>   location to store format of the result
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ctext</parameter>&#160;:</term>
<listitem><simpara>    location to store the data of the result
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>   location to store the length of the data
           stored in <parameter>ctext</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the conversion succeeded, otherwise
              false.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-utf8-to-compound-text-for-display" role="function" condition="since:2.2">
<title>gdk_utf8_to_compound_text_for_display ()</title>
<indexterm zone="gdk-utf8-to-compound-text-for-display" role="2.2"><primary sortas="utf8_to_compound_text_for_display">gdk_utf8_to_compound_text_for_display</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gdk_utf8_to_compound_text_for_display
                                                        (<link linkend="GdkDisplay">GdkDisplay</link> *display,
                                                         const <link linkend="gchar">gchar</link> *str,
                                                         <link linkend="GdkAtom">GdkAtom</link> *encoding,
                                                         <link linkend="gint">gint</link> *format,
                                                         <link linkend="guchar">guchar</link> **ctext,
                                                         <link linkend="gint">gint</link> *length);</programlisting>
<para>
Converts from UTF-8 to compound text.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>display</parameter>&#160;:</term>
<listitem><simpara>  a <link linkend="GdkDisplay"><type>GdkDisplay</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str</parameter>&#160;:</term>
<listitem><simpara>      a UTF-8 string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara> location to store resulting encoding
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>   location to store format of the result
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ctext</parameter>&#160;:</term>
<listitem><simpara>    location to store the data of the result
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>   location to store the length of the data
           stored in <parameter>ctext</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the conversion succeeded, otherwise
              <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="gdk-atom-intern" role="function">
<title>gdk_atom_intern ()</title>
<indexterm zone="gdk-atom-intern"><primary sortas="atom_intern">gdk_atom_intern</primary></indexterm><programlisting><link linkend="GdkAtom">GdkAtom</link>             gdk_atom_intern                     (const <link linkend="gchar">gchar</link> *atom_name,
                                                         <link linkend="gboolean">gboolean</link> only_if_exists);</programlisting>
<para>
Finds or creates an atom corresponding to a given string.
</para><variablelist role="params">
<varlistentry><term><parameter>atom_name</parameter>&#160;:</term>
<listitem><simpara>a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>only_if_exists</parameter>&#160;:</term>
<listitem><simpara>if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, GDK is allowed to not create a new atom, but
                 just return <link linkend="GDK-NONE--CAPS"><literal>GDK_NONE</literal></link> if the requested atom doesn't already
                 exists. Currently, the flag is ignored, since checking the
                 existance of an atom is as expensive as creating it.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the atom corresponding to <parameter>atom_name</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-atom-intern-static-string" role="function" condition="since:2.10">
<title>gdk_atom_intern_static_string ()</title>
<indexterm zone="gdk-atom-intern-static-string" role="2.10"><primary sortas="atom_intern_static_string">gdk_atom_intern_static_string</primary></indexterm><programlisting><link linkend="GdkAtom">GdkAtom</link>             gdk_atom_intern_static_string       (const <link linkend="gchar">gchar</link> *atom_name);</programlisting>
<para>
Finds or creates an atom corresponding to a given string.
</para>
<para>
Note that this function is identical to <link linkend="gdk-atom-intern"><function>gdk_atom_intern()</function></link> except
that if a new <link linkend="GdkAtom"><type>GdkAtom</type></link> is created the string itself is used rather 
than a copy. This saves memory, but can only be used if the string 
will <emphasis>always</emphasis> exist. It can be used with statically
allocated strings in the main program, but not with statically 
allocated memory in dynamically loaded modules, if you expect to
ever unload the module again (e.g. do not use this function in
GTK+ theme engines).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>atom_name</parameter>&#160;:</term>
<listitem><simpara> a static string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the atom corresponding to <parameter>atom_name</parameter>

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.10</para></refsect2>
<refsect2 id="gdk-atom-name" role="function">
<title>gdk_atom_name ()</title>
<indexterm zone="gdk-atom-name"><primary sortas="atom_name">gdk_atom_name</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gdk_atom_name                       (<link linkend="GdkAtom">GdkAtom</link> atom);</programlisting>
<para>
Determines the string corresponding to an atom.
</para><variablelist role="params">
<varlistentry><term><parameter>atom</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GdkAtom"><type>GdkAtom</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated string containing the string
          corresponding to <parameter>atom</parameter>. When you are done
          with the return value, you should free it
          using <link linkend="g-free"><function>g_free()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-property-get" role="function">
<title>gdk_property_get ()</title>
<indexterm zone="gdk-property-get"><primary sortas="property_get">gdk_property_get</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gdk_property_get                    (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="GdkAtom">GdkAtom</link> property,
                                                         <link linkend="GdkAtom">GdkAtom</link> type,
                                                         <link linkend="gulong">gulong</link> offset,
                                                         <link linkend="gulong">gulong</link> length,
                                                         <link linkend="gint">gint</link> pdelete,
                                                         <link linkend="GdkAtom">GdkAtom</link> *actual_property_type,
                                                         <link linkend="gint">gint</link> *actual_format,
                                                         <link linkend="gint">gint</link> *actual_length,
                                                         <link linkend="guchar">guchar</link> **data);</programlisting>
<para>
Retrieves a portion of the contents of a property. If the
property does not exist, then the function returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>,
and <link linkend="GDK-NONE--CAPS"><literal>GDK_NONE</literal></link> will be stored in <parameter>actual_property_type</parameter>.
</para>
<note>
<para>
The <link linkend="XGetWindowProperty"><function>XGetWindowProperty()</function></link> function that <link linkend="gdk-property-get"><function>gdk_property_get()</function></link>
uses has a very confusing and complicated set of semantics.
Unfortunately, <link linkend="gdk-property-get"><function>gdk_property_get()</function></link> makes the situation
worse instead of better (the semantics should be considered
undefined), and also prints warnings to stderr in cases where it
should return a useful error to the program. You are advised to use
<link linkend="XGetWindowProperty"><function>XGetWindowProperty()</function></link> directly until a replacement function for
<link linkend="gdk-property-get"><function>gdk_property_get()</function></link>
is provided.
</para>
</note><variablelist role="params">
<varlistentry><term><parameter>window</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GdkWindow"><type>GdkWindow</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property</parameter>&#160;:</term>
<listitem><simpara>the property to retrieve.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara>the desired property type, or <link linkend="GDK-NONE--CAPS"><literal>GDK_NONE</literal></link>, if any type of data
       is acceptable. If this does not match the actual
       type, then <parameter>actual_format</parameter> and <parameter>actual_length</parameter> will
       be filled in, a warning will be printed to stderr
       and no data will be returned.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&#160;:</term>
<listitem><simpara>the offset into the property at which to begin
         retrieving data, in 4 byte units.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>the length of the data to retrieve in bytes.  Data is
         considered to be retrieved in 4 byte chunks, so <parameter>length</parameter>
         will be rounded up to the next highest 4 byte boundary
         (so be careful not to pass a value that might overflow
          when rounded up).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pdelete</parameter>&#160;:</term>
<listitem><simpara>if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, delete the property after retrieving the
          data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>actual_property_type</parameter>&#160;:</term>
<listitem><simpara>location to store the actual type of 
                       the property.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>actual_format</parameter>&#160;:</term>
<listitem><simpara>location to store the actual return format of the
                data; either 8, 16 or 32 bits.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>actual_length</parameter>&#160;:</term>
<listitem><simpara>location to store the length of the retrieved data, in
                bytes.  Data returned in the 32 bit format is stored
                in a long variable, so the actual number of 32 bit
                elements should be be calculated via
                <parameter>actual_length</parameter>/sizeof(glong) to ensure portability to
                64 bit systems.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>location to store a pointer to the data. The retrieved
       data should be freed with <link linkend="g-free"><function>g_free()</function></link> when you are finished
       using it.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if data was successfully received and stored
          in <parameter>data</parameter>, otherwise <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-property-change" role="function">
<title>gdk_property_change ()</title>
<indexterm zone="gdk-property-change"><primary sortas="property_change">gdk_property_change</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_property_change                 (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="GdkAtom">GdkAtom</link> property,
                                                         <link linkend="GdkAtom">GdkAtom</link> type,
                                                         <link linkend="gint">gint</link> format,
                                                         <link linkend="GdkPropMode">GdkPropMode</link> mode,
                                                         const <link linkend="guchar">guchar</link> *data,
                                                         <link linkend="gint">gint</link> nelements);</programlisting>
<para>
Changes the contents of a property on a window.
</para><variablelist role="params">
<varlistentry><term><parameter>window</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GdkWindow"><type>GdkWindow</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property</parameter>&#160;:</term>
<listitem><simpara>the property to change.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara>the new type for the property. If <parameter>mode</parameter> is
       <link linkend="GDK-PROP-MODE-PREPEND--CAPS"><literal>GDK_PROP_MODE_PREPEND</literal></link> or <link linkend="GDK-PROP-MODE-APPEND--CAPS"><literal>GDK_PROP_MODE_APPEND</literal></link>, then this
       must match the existing type or an error will occur.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>the new format for the property. If <parameter>mode</parameter> is
         <link linkend="GDK-PROP-MODE-PREPEND--CAPS"><literal>GDK_PROP_MODE_PREPEND</literal></link> or <link linkend="GDK-PROP-MODE-APPEND--CAPS"><literal>GDK_PROP_MODE_APPEND</literal></link>, then this
         must match the existing format or an error will occur.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mode</parameter>&#160;:</term>
<listitem><simpara>a value describing how the new data is to be combined
       with the current data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the data
       (a <literal>guchar *</literal>
        <literal>gushort *</literal>, or
        <literal>gulong *</literal>, depending on <parameter>format</parameter>), cast to a
        <literal>guchar *</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nelements</parameter>&#160;:</term>
<listitem><simpara>the number of elements of size determined by the format,
            contained in <parameter>data</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GdkPropMode" role="enum">
<title>enum GdkPropMode</title>
<indexterm zone="GdkPropMode"><primary sortas="PropMode">GdkPropMode</primary></indexterm><programlisting>typedef enum
{
  GDK_PROP_MODE_REPLACE,
  GDK_PROP_MODE_PREPEND,
  GDK_PROP_MODE_APPEND
} GdkPropMode;
</programlisting>
<para>
Describes how existing data is combined with new data when
using <link linkend="gdk-property-change"><function>gdk_property_change()</function></link>.
</para><variablelist role="enum">
<varlistentry id="GDK-PROP-MODE-REPLACE--CAPS" role="constant">
<term><literal>GDK_PROP_MODE_REPLACE</literal></term>
<listitem><simpara>the new data replaces the existing data.
</simpara></listitem>
</varlistentry>
<varlistentry id="GDK-PROP-MODE-PREPEND--CAPS" role="constant">
<term><literal>GDK_PROP_MODE_PREPEND</literal></term>
<listitem><simpara>the new data is prepended to the existing data.
</simpara></listitem>
</varlistentry>
<varlistentry id="GDK-PROP-MODE-APPEND--CAPS" role="constant">
<term><literal>GDK_PROP_MODE_APPEND</literal></term>
<listitem><simpara>the new data is appended to the existing data.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-property-delete" role="function">
<title>gdk_property_delete ()</title>
<indexterm zone="gdk-property-delete"><primary sortas="property_delete">gdk_property_delete</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_property_delete                 (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="GdkAtom">GdkAtom</link> property);</programlisting>
<para>
Deletes a property from a window.
</para><variablelist role="params">
<varlistentry><term><parameter>window</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GdkWindow"><type>GdkWindow</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property</parameter>&#160;:</term>
<listitem><simpara>the property to delete.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
