path: root/docs/reference/pygtk-gtkcolorselection.xml

<?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-gtkcolorselection">
  <refnamediv>
    <refname>gtk.ColorSelection</refname>
    <refpurpose>a widget used to select a color.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.ColorSelection</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkvbox">gtk.VBox</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkcolorselection">gtk.ColorSelection</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--get-has-opacity-control">get_has_opacity_control</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--set-has-opacity-control">set_has_opacity_control</link></methodname>
	<methodparam><parameter
		       role="keyword">has_opacity</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--get-has-palette">get_has_palette</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--set-has-palette">set_has_palette</link></methodname>
	<methodparam><parameter
		       role="keyword">has_palette</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--set-current-color">set_current_color</link></methodname>
	<methodparam><parameter
		       role="keyword">color</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--set-current-alpha">set_current_alpha</link></methodname>
	<methodparam><parameter
		       role="keyword">alpha</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--get-current-color">get_current_color</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--get-current-alpha">get_current_alpha</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--set-previous-color">set_previous_color</link></methodname>
	<methodparam><parameter
		       role="keyword">color</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--set-previous-alpha">set_previous_alpha</link></methodname>
	<methodparam><parameter
		       role="keyword">alpha</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--get-previous-color">get_previous_color</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--get-previous-alpha">get_previous_alpha</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcolorselection--is-adjusting">is_adjusting</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
    </classsynopsis>

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

<methodsynopsis language="python">
    <methodname><link linkend="function-gtk--color-selection-palette-from-string">gtk.color_selection_palette_from_string</link></methodname>
    <methodparam><parameter role="keyword">str</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--color-selection-palette-to-string">gtk.color_selection_palette_to_string</link></methodname>
    <methodparam><parameter role="keyword">colors</parameter></methodparam>
  </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

    <synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +--<link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
        +-- <link linkend="class-gtkbox">gtk.Box</link>
          +-- <link linkend="class-gtkvbox">gtk.VBox</link>
            +-- <link linkend="class-gtkcolorselection">gtk.ColorSelection</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtkcolorselection">
    <title>gtk.ColorSelection Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
    <para><link linkend="properties-gtkbox">gtk.Box Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="3.5in"/>
	  <tbody>

            <row valign="top">
              <entry>"current-alpha"</entry>
              <entry>Read/Write</entry>
              <entry>The current opacity value (0 fully transparent, 65535 fully
              opaque)</entry>
            </row>

            <row valign="top">
              <entry>"current-color"</entry>
              <entry>Read/Write</entry>
              <entry>The current color as a <link
              linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link></entry>
            </row>

            <row valign="top">
              <entry>"has-opacity-control"</entry>
              <entry>Read/Write</entry>
              <entry>If <literal>True</literal>, the color selector should allow
              setting opacity</entry>
            </row>

            <row valign="top">
              <entry>"has-palette"</entry>
              <entry>Read/Write</entry>
              <entry>If <literal>True</literal>, a palette should be used</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkcolorselection">
    <title>gtk.ColorSelection Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>

  </refsect1>

  <refsect1 id="child-properties-gtkcolorselection">
    <title>gtk.ColorSelection Child Properties</title>

    <para><link linkend="child-properties-gtkbox">gtk.Box Child Properties</link></para>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkcolorselection">
    <title>gtk.ColorSelection Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcolorselection--color-changed">color-changed</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>colorselection</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkcolorselection"><classname>gtk.ColorSelection</classname></link> 
is a widget that is used to select a color. It consists of a color wheel and
entry boxes for color parameters such as hue, saturation, value, red, green,
blue, and color name and optionally an opacity control and/or a color
palette. It is found on the standard color selection dialog box <link
linkend="class-gtkcolorselectiondialog"><classname>gtk.ColorSelectionDialog</classname></link>. 
The color wheel can be manipulated to set a new color or new entries can be
made in the entry boxes. The new color is displayed next to the previous
color. An eyedropper button is available to allow the selection of a color
from a pixel location on the display.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.ColorSelection</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtkcolorselection"><classname>gtk.ColorSelection</classname></link></simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkcolorselection"><classname>gtk.ColorSelection</classname></link> 
widget.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkcolorselection--get-has-opacity-control">
      <title>gtk.ColorSelection.get_has_opacity_control</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_has_opacity_control</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the
<parameter>colorsel</parameter> has an opacity control;
<literal>False</literal> if it doesn't.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_opacity</methodname>() method determines
whether the colorselection is displaying an opacity control.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--set-has-opacity-control">
      <title>gtk.ColorSelection.set_has_opacity_control</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_has_opacity_control</methodname>
	  <methodparam><parameter
			 role="keyword">has_opacity</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">has_opacity</parameter>&nbsp;:</term>
	  <listitem><simpara>If <literal>True</literal> the colorselection
will display the opacity control.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_has_opacity_control</methodname>() method
sets the "has-opacity-control" property to the value of
<parameter>has_opacity</parameter>. If <parameter>has_opacity</parameter> is
<literal>True</literal> the colorselection will display the opacity control
slider and entry box; otherwise the opacity control is not displayed.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--get-has-palette">
      <title>gtk.ColorSelection.get_has_palette</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_has_palette</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the selector has a
palette; <literal>False</literal> if it hasn't.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_has_palette</methodname>() method returns
the value of the "has-palette" property that determines whether the color
selector displays a color palette.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--set-has-palette">
      <title>gtk.ColorSelection.set_has_palette</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_has_palette</methodname>
	  <methodparam><parameter
			 role="keyword">has_palette</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">has_palette</parameter>&nbsp;:</term>
	  <listitem><simpara>If <literal>True</literal> the color palette is
displayed.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_has_palette</methodname>() method sets the
"has-palette" property to the value of <parameter>has_palette</parameter>.
If <parameter>has_palette</parameter> is True the palette will be displayed;
otherwise the palette will be hidden.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--set-current-color">
      <title>gtk.ColorSelection.set_current_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_current_color</methodname>
	  <methodparam><parameter
			 role="keyword">color</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">color</parameter>&nbsp;:</term>
	  <listitem><simpara>A <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> to set
the current color with.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_current_color</methodname>() method sets the
current color to the value of <parameter>color</parameter>.  The first time
this is called, it will also set the previous color to the value of
<parameter>color</parameter> too.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--set-current-alpha">
      <title>gtk.ColorSelection.set_current_alpha</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_current_alpha</methodname>
	  <methodparam><parameter
			 role="keyword">alpha</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">alpha</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer between 0 and
65535.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_current_alpha</methodname>() method sets the
"current-alpha" property (the opacity) to the value of alpha. The alpha
(opacity) is displayed in the range of 0 to 255 in the colorselection.  The
first time this is called, it will also set the previous opacity to the
value of <parameter>alpha</parameter> too.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--get-current-color">
      <title>gtk.ColorSelection.get_current_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_current_color</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
representing the current color.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_current_color</methodname>() method
retrieves the current color in the colorselection.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--get-current-alpha">
      <title>gtk.ColorSelection.get_current_alpha</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_current_alpha</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the current alpha value in the range 0 to
65535.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_current_alpha</methodname>() method returns
the value of the "current_alpha" property that controls the opacity
value.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--set-previous-color">
      <title>gtk.ColorSelection.set_previous_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_previous_color</methodname>
	  <methodparam><parameter
			 role="keyword">color</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">color</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> to set
the previous color with.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_previous_color</methodname>() method sets
the 'previous' color to the value of <parameter>color</parameter>.
Applications usually do not call this method. The first time <link
linkend="method-gtkcolorselection--set-current-color"><methodname>set_current_color</methodname>()</link> 
the 'previous' color will be set.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--set-previous-alpha">
      <title>gtk.ColorSelection.set_previous_alpha</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_previous_alpha</methodname>
	  <methodparam><parameter
			 role="keyword">alpha</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">alpha</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer between 0 and
65535.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The set_previous_alpha() method sets the 'previous' alpha to the
value of <parameter>alpha</parameter>. Applications usually do not call this
method. The first time <link
linkend="method-gtkcolorselection--set-current-alpha"><methodname>set_current_alpha</methodname>()</link> 
the 'previous' alpha will be set.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--get-previous-color">
      <title>gtk.ColorSelection.get_previous_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_previous_color</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> with
the previous color value.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_previous_color</methodname>() method
retrieves the previous color value.</para>

    </refsect2>


    <refsect2 id="method-gtkcolorselection--get-previous-alpha">
      <title>gtk.ColorSelection.get_previous_alpha</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_previous_alpha</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>an integer between 0 and
65535.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The get_previous_alpha() method returns the previous alpha
value.</para>

    </refsect2>

    <refsect2 id="method-gtkcolorselection--is-adjusting">
      <title>gtk.ColorSelection.is_adjusting</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>is_adjusting</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the user is
currently dragging a color around, and <literal>False</literal> if the
selection has stopped.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>is_adjusting</methodname>() method retrieves the
current state of the colorselection. If True the user is in the process of
changing the current color.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--color-selection-palette-from-string">
      <title>gtk.color_selection_palette_from_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.color_selection_palette_from_string</methodname>
	  <methodparam><parameter
			 role="keyword">str</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">str</parameter>&nbsp;:</term>
	  <listitem><simpara>the string containing the list of
colors</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a list of <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> objects
or <literal>None</literal> if the conversion fails</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The
<function>gtk.color_selection_palette_from_string</function>() function
returns a list of <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> objects
corresponding to the color specifications in the string specified by
<parameter>str</parameter>. str is a colon-separated list of color names
readable by <link
linkend="function-gdk--color-parse"><function>gtk.gtk.color_parse</function>()</link>. 
If <parameter>str</parameter> cannot be converted to a list of color this
function returns <literal>None</literal>.</para>

    </refsect2>

    <refsect2 id="function-gtk--color-selection-palette-to-string">
      <title>gtk.color_selection_palette_to_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.color_selection_palette_to_string</methodname>
	  <methodparam><parameter
			 role="keyword">colors</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">colors</parameter>&nbsp;:</term>
	  <listitem><simpara>a list or tuple of <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
objects</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a string containing a colon-separated list of
<parameter>colors</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.color_selection_palette_to_string</function>()
function returns a string containing a colon-separated list of the
representation of the <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> objects
in <parameter>colors</parameter>.</para>

      <para>This function is useful to save a special palette of colors for
a <link
linkend="class-gtkcolorselection"><classname>gtk.ColorSelection</classname></link> 
as a string that can later be used by calling the <link
linkend="method-gobject--set-property"><methodname>gobject.set_property</methodname>()</link> 
method to set the "gtk-color-palette" property on the default <link
linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
returned from the <link
linkend="function-gtk--settings-get-default"><function>gtk.settings_get_default</function>()</link>) 
function.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkcolorselection--color-changed">
      <title>The "color-changed" gtk.ColorSelection Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>colorselection</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>colorselection</parameter>&nbsp;:</term>
	  <listitem><simpara>the colorselection that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "color-changed" signal is emitted when the current color in
the colorselection changes.</para>

    </refsect2>

  </refsect1>

</refentry>