<?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="gdk4-Properties-and-Atoms">
<refmeta>
<refentrytitle role="top_of_page" id="gdk4-Properties-and-Atoms.top_of_page">Properties and Atoms</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Properties and Atoms</refname>
<refpurpose>Functions to manipulate properties on windows</refpurpose>
</refnamediv>

<refsect1 id="gdk4-Properties-and-Atoms.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-text-property-to-utf8-list-for-display">gdk_text_property_to_utf8_list_for_display</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-utf8-to-string-target">gdk_utf8_to_string_target</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="gdk4-Properties-and-Atoms.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GdkAtom">GdkAtom</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="gdk4-Properties-and-Atoms.includes"><title>Includes</title><synopsis>#include &lt;gdk/gdk.h&gt;
</synopsis></refsect1>

<refsect1 id="gdk4-Properties-and-Atoms.description" role="desc">
<title role="desc.title">Description</title>
<para>Each window under X can have any number of associated
“properties” attached to it.
Properties are arbitrary chunks of data identified by
“atom”s. (An “atom”
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 “format”,
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 long,
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="gdk4-Properties-and-Atoms.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gdk-text-property-to-utf8-list-for-display" role="function">
<title>gdk_text_property_to_utf8_list_for_display&#160;()</title>
<indexterm zone="gdk-text-property-to-utf8-list-for-display"><primary>gdk_text_property_to_utf8_list_for_display</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
gdk_text_property_to_utf8_list_for_display
                               (<parameter><link linkend="GdkDisplay"><type>GdkDisplay</type></link> *display</parameter>,
                                <parameter><link linkend="GdkAtom"><type>GdkAtom</type></link> encoding</parameter>,
                                <parameter><link linkend="gint"><type>gint</type></link> format</parameter>,
                                <parameter>const <link linkend="guchar"><type>guchar</type></link> *text</parameter>,
                                <parameter><link linkend="gint"><type>gint</type></link> length</parameter>,
                                <parameter><link linkend="gchar"><type>gchar</type></link> ***list</parameter>);</programlisting>
<para>Converts a text property in the given encoding to
a list of UTF-8 strings.</para>
<refsect3 id="gdk-text-property-to-utf8-list-for-display.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>display</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkDisplay"><type>GdkDisplay</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>encoding</para></entry>
<entry role="parameter_description"><para>an atom representing the encoding of the text</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the format of the property</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>text</para></entry>
<entry role="parameter_description"><para>the text to convert. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=length]</emphasis></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the length of <parameter>text</parameter>
, in bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>list</para></entry>
<entry role="parameter_description"><para>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>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>array</acronym> zero-terminated=1]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-text-property-to-utf8-list-for-display.returns" role="returns">
<title>Returns</title>
<para> the number of strings in the resulting list</para>
</refsect3></refsect2>
<refsect2 id="gdk-utf8-to-string-target" role="function">
<title>gdk_utf8_to_string_target&#160;()</title>
<indexterm zone="gdk-utf8-to-string-target"><primary>gdk_utf8_to_string_target</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
gdk_utf8_to_string_target (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>);</programlisting>
<para>Converts 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>
<refsect3 id="gdk-utf8-to-string-target.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a UTF-8 string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-utf8-to-string-target.returns" role="returns">
<title>Returns</title>
<para>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 unless system limits like memory or
file descriptors are exceeded.). </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="gdk4-Properties-and-Atoms.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GdkAtom" role="struct">
<title>GdkAtom</title>
<indexterm zone="GdkAtom"><primary>GdkAtom</primary></indexterm>
<programlisting language="C">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>

</refsect1>

</refentry>
