<?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-gdkcolormap">
  <refnamediv>
    <refname>gtk.gdk.Colormap</refname>
    <refpurpose>a table of color display component values</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.gdk.Colormap</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gdkcolormap">gtk.gdk.Colormap</link></methodname>
	<methodparam><parameter
		       role="keyword">visual</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">allocate</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkcolormap--alloc-color">alloc_color</link></methodname>
	<methodparam><parameter
		       role="keyword">color</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">writeable</parameter>
	  <initializer>False</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">best_match</parameter>
	  <initializer>True</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkcolormap--alloc-color2">alloc_color</link></methodname>
	<methodparam><parameter
		       role="keyword">spec</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">writeable</parameter>
	  <initializer>False</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">best_match</parameter>
	  <initializer>True</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkcolormap--alloc-color3">alloc_color</link></methodname>
	<methodparam><parameter
		       role="keyword">red</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">green</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">blue</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">writeable</parameter>
	  <initializer>False</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">best_match</parameter>
	  <initializer>True</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkcolormap--get-visual">get_visual</link></methodname>
	<methodparam></methodparam>  
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkcolormap--get-screen">get_screen</link></methodname>
	<methodparam></methodparam>  
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkcolormap--query-color">query_color</link></methodname>
	<methodparam><parameter role="keyword">pixel</parameter></methodparam>  
      </methodsynopsis>
    </classsynopsis>

    <programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
	<methodname><link linkend="function-gdk--colormap-get-system">gtk.gdk.colormap_get_system</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gdkcolormap">gtk.gdk.Colormap</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gdkcolormap"><classname>gtk.gdk.Colormap</classname></link>
contains a table mapping index values to the RGB color component values used
to display the colors. The index value corresponds to the pixel value of a
<link linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
object and the RGB component values correspond to the <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> red,
green and blue values. The <link
linkend="method-gtkwidget--get-colormap"><methodname>gtk.Widget.get_colormap</methodname>()</link> 
method is used to retrieve the colormap used by a widget. The default system
colormap is retrieved by using the <link
linkend="function-gdk--colormap-get-system"><methodname>gtk.gdk.colormap_get_system</methodname>()</link> 
function. The <link
linkend="method-gdkcolormap--alloc-color"><methodname>alloc_color</methodname>()</link> 
method has three signatures to allow the color specification using an
unallocated <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>, a
string or a RGB trio.</para>

  </refsect1>

  <refsect1 id="constructor-gdkcolormap">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.gdk.Colormap</methodname>
	<methodparam><parameter
		       role="keyword">visual</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">allocate</parameter></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">visual</parameter>&nbsp;:</term>
	<listitem><simpara>the <link
linkend="class-gdkvisual"><classname>gtk.gdk.Visual</classname></link> to
use</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">allocate</parameter>&nbsp;:</term>
	<listitem><simpara>if <literal>True</literal>, the newly created
colormap will be a private colormap, and all colors in it will be allocated
for the applications use.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a <link
linkend="class-gdkcolormap"><classname>gtk.gdk.Colormap</classname></link>
object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gdkcolormap"><classname>gtk.gdk.Colormap</classname></link>
for the <link
linkend="class-gdkvisual"><classname>gtk.gdk.Visual</classname></link>
specified by <parameter>visual</parameter>. If
<parameter>allocate</parameter> is <literal>True</literal> the colormap will
be a private colormap for the sole use of the application.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

  <refsect2 id="method-gdkcolormap--alloc-color">
      <title>gtk.gdk.Colormap.alloc_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>alloc_color</methodname>
	  <methodparam><parameter
			 role="keyword">color</parameter></methodparam>
	  <methodparam><parameter role="keyword">writeable</parameter>
	    <initializer>False</initializer></methodparam>
	  <methodparam><parameter role="keyword">best_match</parameter>
	    <initializer>True</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">color</parameter>&nbsp;:</term>
	  <listitem><simpara>an unallocated <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">writeable</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the colormap entry
is writeable.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">best_match</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> a best match to the
requested color can be used if needed.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
object</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>alloc_color</methodname>() method allocates the
color specified by <parameter>color</parameter> in the colormap. The value
of color should be an unallocated <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>. If
<parameter>writeable</parameter> is <literal>True</literal> the color is
allocated writeable which means it can be changed after allocation but
cannot be shared with another application. If
<parameter>best_match</parameter> is <literal>True</literal> the closest
match to the color will be returned if the request could not be satisfied
exactly.</para>

      <para>This method raises:</para>

      <itemizedlist>
	<listitem>
	  <simpara>the ValueError (TypeError prior to PyGTK 2.4) exception if
unable to parse the color specification</simpara>
	</listitem>
	<listitem>
	  <simpara>the RuntimeError exception if the color could not be
allocated</simpara>
	</listitem>
      </itemizedlist>

      <para></para>

  </refsect2>

    <refsect2 id="method-gdkcolormap--alloc-color2">
      <title>gtk.gdk.Colormap.alloc_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>alloc_color</methodname>
	  <methodparam><parameter
			 role="keyword">spec</parameter></methodparam>
	  <methodparam><parameter role="keyword">writeable</parameter>
	    <initializer>False</initializer></methodparam>
	  <methodparam><parameter role="keyword">best_match</parameter>
	    <initializer>True</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">spec</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing a color
specification</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">writeable</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the colormap entry
is writeable.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">best_match</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> a best match to the
requested color can be used if needed.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
object</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>alloc_color</methodname>() method allocates the
color specified by <parameter>spec</parameter> in the colormap. The format
of <parameter>spec</parameter> is a string containing the specification of
the color either as a name (e.g. "navajowhite") as specified in the X11
<filename>rgb.txt</filename> file or as a hexadecimal string (e.g.
"#FF0078"). The hexadecimal string must start with '#' and must contain 3
sets of hexadecimal digits of the same length (i.e. 1, 2 ,3 or 4 digits).
For example the following specify the same color value: "#F0A", "#FF00AA",
"#FFF000AAA" and "#FFFF0000AAAA". If <parameter>writeable</parameter> is
<literal>True</literal> the color is allocated writeable which means it can
be changed after allocation but cannot be shared with another application.
If <parameter>best_match</parameter> is <literal>True</literal> the closest
match to the color will be returned if the request could not be satisfied
exactly.</para>

      <para>This method raises:</para>

      <itemizedlist>
	<listitem>
	  <simpara>the ValueError (TypeError prior to PyGTK 2.4) exception if
unable to parse the color specification</simpara>
	</listitem>
	<listitem>
	  <simpara>the RuntimeError exception if the color could not be
allocated</simpara>
	</listitem>
      </itemizedlist>

      <para></para>

  </refsect2>

  <refsect2 id="method-gdkcolormap--alloc-color3">
    <title>gtk.gdk.Colormap.alloc_color</title>

<programlisting><methodsynopsis language="python">
    <methodname>alloc_color</methodname>
    <methodparam><parameter role="keyword">red</parameter></methodparam>
    <methodparam><parameter role="keyword">green</parameter></methodparam>
    <methodparam><parameter role="keyword">blue</parameter></methodparam>
    <methodparam><parameter role="keyword">writeable</parameter>
	  <initializer>False</initializer></methodparam>
    <methodparam><parameter role="keyword">best_match</parameter>
	  <initializer>True</initializer></methodparam>
  </methodsynopsis></programlisting>
  <variablelist>
    <varlistentry>
      <term><parameter role="keyword">red</parameter>&nbsp;:</term>
      <listitem><simpara>the red component of the color in the range 0-65535</simpara></listitem>
    </varlistentry>
    <varlistentry>
      <term><parameter role="keyword">green</parameter>&nbsp;:</term>
      <listitem><simpara>the green component of the color in the range 0-65535</simpara></listitem>
    </varlistentry>
    <varlistentry>
      <term><parameter role="keyword">blue</parameter>&nbsp;:</term>
      <listitem><simpara>the blue component of the color in the range 0-65535</simpara></listitem>
    </varlistentry>
    <varlistentry>
      <term><parameter role="keyword">writeable</parameter>&nbsp;:</term>
      <listitem><simpara>a gboolean</simpara></listitem>
    </varlistentry>
    <varlistentry>
      <term><parameter role="keyword">best_match</parameter>&nbsp;:</term>
      <listitem><simpara>a gboolean</simpara></listitem>
    </varlistentry>
    <varlistentry>
      <term><emphasis>Returns</emphasis>&nbsp;:</term>
      <listitem><simpara>a <link linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> object</simpara></listitem>
    </varlistentry>
  </variablelist>

      <para>The <methodname>alloc_color</methodname>() method allocates the
color specified by the component values <parameter>red</parameter>,
<parameter>green</parameter> and <parameter>blue</parameter>. If
<parameter>writeable</parameter> is <literal>True</literal> the color is
allocated writeable which means it can be changed after allocation but
cannot be shared with another application. If
<parameter>best_match</parameter> is <literal>True</literal> the closest
match to the color will be returned if the request could not be satisfied
exactly.</para>

      <para>This method raises:</para>

      <itemizedlist>
	<listitem>
	  <simpara>the ValueError (TypeError prior to PyGTK 2.4) exception if
unable to parse the color specification</simpara>
	</listitem>
	<listitem>
	  <simpara>the RuntimeError exception if the color could not be
allocated</simpara>
	</listitem>
      </itemizedlist>

      <para></para>

  </refsect2>

  <refsect2 id="method-gdkcolormap--get-visual">
      <title>gtk.gdk.Colormap.get_visual</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_visual</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkvisual"><classname>gtk.gdk.Visual</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_visual</methodname>() method returns the
visual the colormap was created for. See the <link
linkend="constructor-gdkcolormap">gtk.gdk.Colormap</link>
constructor.</para>

  </refsect2>

  <refsect2 id="method-gdkcolormap--get-screen">
      <title>gtk.gdk.Colormap.get_screen</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_screen</methodname>
	  <methodparam></methodparam>  
</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkvisual"><classname>gtk.gdk.Screen</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_screen</methodname>() method returns the
<link linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>
the colormap was created for.</para>

  </refsect2>

  <refsect2 id="method-gdkcolormap--query-color">
      <title>gtk.gdk.Colormap.query_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>query_color</methodname>
	  <methodparam></methodparam>  
</methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">pixel</parameter>&nbsp;:</term>
          <listitem><simpara>a pixel value</simpara></listitem>
        </varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
	  linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
	  corresponding to <parameter>pixel</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>query_color</methodname>() method returns the
<link linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
corresponding to the hardware pixel value specified by
<parameter>pixel</parameter>. <parameter>pixel</parameter> must be a valid
pixel in the colormap. It's a programmer error to call this method with a
pixel which is not in the colormap. Hardware pixels are normally obtained
from the <link
linkend="method-gdkcolormap--alloc-color"><methodname>alloc_color</methodname>()</link>
method, or from a <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link>
object. (A <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link>
contains image data in hardware format while a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
contains image data in a canonical 24-bit RGB format.)</para>

  </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gdk--colormap-get-system">
      <title>gtk.gdk.colormap_get_system</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.gdk.colormap_get_system</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the system' default
colormap</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <methodname>gtk.gdk.colormap_get_system</methodname>()
method returns the default colormap used by the system on the default
screen. See the <link
linkend="method-gdkscreen--get-system-colormap"><methodname>gtk.gdk.Screen.get_system_colormap</methodname>()</link>
method for more information.</para>

    </refsect2>

  </refsect1>

</refentry>
