<?xml version="1.0" standalone="no"?>
<!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="class-gdkatom">
  <refnamediv>
    <refname>gtk.gdk.Atom</refname>
    <refpurpose>an object representing an interned string</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

<classsynopsis language="python">
  <ooclass><classname>gtk.gdk.Atom</classname></ooclass>
<constructorsynopsis language="python">
    <methodname><link linkend="constructor-gdkatom-intern">gtk.gdk.atom_intern</link></methodname>
    <methodparam><parameter role="keyword">name</parameter></methodparam>
	<methodparam><parameter role="keyword">only_if_exists</parameter><initializer><literal>False</literal></initializer></methodparam>
  </constructorsynopsis>
</classsynopsis>

</refsect1>

  <refsect1>
    <title>Description</title>

    <para><link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> is a
<literal>PyGTK</literal> class that wraps the <literal>GTK</literal>+
<type>GdkAtom</type> - an unsigned integer representing an interned
string. An interned string is a string that has an internal
<literal>GTK</literal>+ mapping between an atom and a string. <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> has no
methods. A copy of the interned string can be retrieved by using the Python
<function>str()</function> function. <link
linkend="constructor-gdkatom-intern">gtk.gdk.atom_intern</link>() will
return a <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link>
referencing an existing interned string but will intern a string if it isn't
already interned.</para>

    <para><link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> objects
are used to provide the targets for <link
linkend="class-gtkselectiondata"><classname>gtk.SelectionData</classname></link>
objects that are used by <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link> and
<link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>,
objects and for drag and drop (see <link
linkend="class-gdkdragcontext"><classname>gtk.gdk.DragContext</classname></link>,
<link linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link>
and <link
linkend="class-gtktreedragsource"><classname>gtk.TreeDragSource</classname></link>
and <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
for more information). The advantage of the interned string is that it is
easy to pass between processes and even systems since only an integer value
is passed.</para>

    <para><literal>PyGTK</literal> 2.4 has a number of pre-defined atoms
that map to builtin <literal>GTK+</literal> interned string atoms. The
interned strings and the <literal>PyGTK</literal> 2.4 <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> objects
are:</para>

    <variablelist>
      <varlistentry>
	<term>"PRIMARY"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.SELECTION_PRIMARY</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"SECONDARY"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.SELECTION_SECONDARY</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"CLIPBOARD"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.SELECTION_CLIPBOARD</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"ATOM"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.SELECTION_TYPE_ATOM</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"BITMAP"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.TARGET_BITMAP</literal> or
<literal>gtk.gdk.SELECTION_TYPE_BITMAP</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"COLORMAP"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.TARGET_COLORMAP</literal> or
<literal>gtk.gdk.SELECTION_TYPE_COLORMAP</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"DRAWABLE"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.TARGET_DRAWABLE</literal> or
<literal>gtk.gdk.SELECTION_TYPE_DRAWABLE</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"PIXMAP"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.TARGET_PIXMAP</literal> or
<literal>gtk.gdk.SELECTION_TYPE_PIXMAP</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"STRING"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.TARGET_STRING</literal> or
<literal>gtk.gdk.SELECTION_TYPE_STRING</literal></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"WINDOW"</term>
	<listitem>
	  <simpara><literal>gtk.gdk.SELECTION_TYPE_WINDOW</literal></simpara>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>Also in <literal>PyGTK</literal> 2.4, comparison between a string
and a <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> is
supported.</para>

  </refsect1>

  <refsect1 id="constructor-gdkatom-intern">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.gdk.atom_intern</methodname>
	<methodparam><parameter
		       role="keyword">name</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">only_if_exists</parameter><initializer><literal>False</literal></initializer></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">name</parameter>&nbsp;:</term>
	<listitem><simpara>the string to be interned or
	retrieved</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter
	role="keyword">only_if_exists</parameter>&nbsp;:</term>
	<listitem><simpara>this value is ignored</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
	linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link>
	or <literal>None</literal></simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link>
referencing the interned string specified by <parameter>name</parameter>. An
interned string is a string that has a <literal>GTK</literal>+ mapping to an
unsigned integer value. This constructor will intern the string and create a
<link linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> if
it does not already exist. <parameter>only_if_exists</parameter> is
ignored and essentially is always <literal>False</literal>.</para>

  </refsect1>

</refentry>
