<?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">
]>
<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
<refentry id="GtkColorButton">
<refmeta>
<refentrytitle role="top_of_page" id="GtkColorButton.top_of_page">GtkColorButton</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkColorButton</refname>
<refpurpose>A button to launch a color selection dialog</refpurpose>
</refnamediv>

<refsynopsisdiv id="GtkColorButton.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

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

                    <link linkend="GtkColorButton-struct">GtkColorButton</link>;
<link linkend="GtkWidget">GtkWidget</link> *         <link linkend="gtk-color-button-new">gtk_color_button_new</link>                (void);
<link linkend="GtkWidget">GtkWidget</link> *         <link linkend="gtk-color-button-new-with-color">gtk_color_button_new_with_color</link>     (const <link linkend="GdkColor">GdkColor</link> *color);
<link linkend="void">void</link>                <link linkend="gtk-color-button-set-color">gtk_color_button_set_color</link>          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         const <link linkend="GdkColor">GdkColor</link> *color);
<link linkend="void">void</link>                <link linkend="gtk-color-button-get-color">gtk_color_button_get_color</link>          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         <link linkend="GdkColor">GdkColor</link> *color);
<link linkend="void">void</link>                <link linkend="gtk-color-button-set-alpha">gtk_color_button_set_alpha</link>          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         <link linkend="guint16">guint16</link> alpha);
<link linkend="guint16">guint16</link>             <link linkend="gtk-color-button-get-alpha">gtk_color_button_get_alpha</link>          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button);
<link linkend="void">void</link>                <link linkend="gtk-color-button-set-use-alpha">gtk_color_button_set_use_alpha</link>      (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         <link linkend="gboolean">gboolean</link> use_alpha);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-color-button-get-use-alpha">gtk_color_button_get_use_alpha</link>      (<link linkend="GtkColorButton">GtkColorButton</link> *color_button);
<link linkend="void">void</link>                <link linkend="gtk-color-button-set-title">gtk_color_button_set_title</link>          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         const <link linkend="gchar">gchar</link> *title);
const <link linkend="gchar">gchar</link> *       <link linkend="gtk-color-button-get-title">gtk_color_button_get_title</link>          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GtkColorButton.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----<link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
         +----<link linkend="GtkObject">GtkObject</link>
               +----<link linkend="GtkWidget">GtkWidget</link>
                     +----<link linkend="GtkContainer">GtkContainer</link>
                           +----<link linkend="GtkBin">GtkBin</link>
                                 +----<link linkend="GtkButton">GtkButton</link>
                                       +----GtkColorButton
</synopsis>
</refsect1>



<refsect1 id="GtkColorButton.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkColorButton implements
 <link linkend="GtkActivatable">GtkActivatable</link>,  <link linkend="AtkImplementorIface">AtkImplementorIface</link> and  <link linkend="GtkBuildable">GtkBuildable</link>.</para>
</refsect1>


<refsect1 id="GtkColorButton.properties" role="properties">
<title role="properties.title">Properties</title>
<synopsis>
  &quot;<link linkend="GtkColorButton--alpha">alpha</link>&quot;                    <link linkend="guint">guint</link>                 : Read / Write
  &quot;<link linkend="GtkColorButton--color">color</link>&quot;                    <link linkend="GdkColor">GdkColor</link>*             : Read / Write
  &quot;<link linkend="GtkColorButton--title">title</link>&quot;                    <link linkend="gchar">gchar</link>*                : Read / Write
  &quot;<link linkend="GtkColorButton--use-alpha">use-alpha</link>&quot;                <link linkend="gboolean">gboolean</link>              : Read / Write
</synopsis>
</refsect1>

<refsect1 id="GtkColorButton.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<synopsis>
  &quot;<link linkend="GtkColorButton-color-set">color-set</link>&quot;                                      : Run First
</synopsis>
</refsect1>


<refsect1 id="GtkColorButton.description" role="desc">
<title role="desc.title">Description</title>
<para>
The <link linkend="GtkColorButton"><type>GtkColorButton</type></link> is a button which displays the currently selected color
an allows to open a color selection dialog to change the color. It is suitable
widget for selecting a color in a preference dialog.
</para>
</refsect1>

<refsect1 id="GtkColorButton.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GtkColorButton-struct" role="struct">
<title>GtkColorButton</title>
<indexterm zone="GtkColorButton-struct"><primary sortas="ColorButton">GtkColorButton</primary></indexterm><programlisting>typedef struct _GtkColorButton GtkColorButton;</programlisting>
<para>
The GtkColorButton struct has only private fields and
should not be used directly.
</para></refsect2>
<refsect2 id="gtk-color-button-new" role="function" condition="since:2.4">
<title>gtk_color_button_new ()</title>
<indexterm zone="gtk-color-button-new" role="2.4"><primary sortas="color_button_new">gtk_color_button_new</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> *         gtk_color_button_new                (void);</programlisting>
<para>
Creates a new color button. This returns a widget in the form of
a small button containing a swatch representing the current selected 
color. When the button is clicked, a color-selection dialog will open, 
allowing the user to select a color. The swatch will be updated to reflect 
the new color when the user finishes.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new color button.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-new-with-color" role="function" condition="since:2.4">
<title>gtk_color_button_new_with_color ()</title>
<indexterm zone="gtk-color-button-new-with-color" role="2.4"><primary sortas="color_button_new_with_color">gtk_color_button_new_with_color</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> *         gtk_color_button_new_with_color     (const <link linkend="GdkColor">GdkColor</link> *color);</programlisting>
<para>
Creates a new color button.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GdkColor"><type>GdkColor</type></link> to set the current color with.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new color button.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-set-color" role="function" condition="since:2.4">
<title>gtk_color_button_set_color ()</title>
<indexterm zone="gtk-color-button-set-color" role="2.4"><primary sortas="color_button_set_color">gtk_color_button_set_color</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_color_button_set_color          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         const <link linkend="GdkColor">GdkColor</link> *color);</programlisting>
<para>
Sets the current color to be <parameter>color</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color_button</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkColorButton"><type>GtkColorButton</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>color</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GdkColor"><type>GdkColor</type></link> to set the current color with.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-get-color" role="function" condition="since:2.4">
<title>gtk_color_button_get_color ()</title>
<indexterm zone="gtk-color-button-get-color" role="2.4"><primary sortas="color_button_get_color">gtk_color_button_get_color</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_color_button_get_color          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         <link linkend="GdkColor">GdkColor</link> *color);</programlisting>
<para>
Sets <parameter>color</parameter> to be the current color in the <link linkend="GtkColorButton"><type>GtkColorButton</type></link> widget.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color_button</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkColorButton"><type>GtkColorButton</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>color</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GdkColor"><type>GdkColor</type></link> to fill in with the current color.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-set-alpha" role="function" condition="since:2.4">
<title>gtk_color_button_set_alpha ()</title>
<indexterm zone="gtk-color-button-set-alpha" role="2.4"><primary sortas="color_button_set_alpha">gtk_color_button_set_alpha</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_color_button_set_alpha          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         <link linkend="guint16">guint16</link> alpha);</programlisting>
<para>
Sets the current opacity to be <parameter>alpha</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color_button</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkColorButton"><type>GtkColorButton</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>alpha</parameter>&#160;:</term>
<listitem><simpara> an integer between 0 and 65535.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-get-alpha" role="function" condition="since:2.4">
<title>gtk_color_button_get_alpha ()</title>
<indexterm zone="gtk-color-button-get-alpha" role="2.4"><primary sortas="color_button_get_alpha">gtk_color_button_get_alpha</primary></indexterm><programlisting><link linkend="guint16">guint16</link>             gtk_color_button_get_alpha          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button);</programlisting>
<para>
Returns the current alpha value.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color_button</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkColorButton"><type>GtkColorButton</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> an integer between 0 and 65535.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-set-use-alpha" role="function" condition="since:2.4">
<title>gtk_color_button_set_use_alpha ()</title>
<indexterm zone="gtk-color-button-set-use-alpha" role="2.4"><primary sortas="color_button_set_use_alpha">gtk_color_button_set_use_alpha</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_color_button_set_use_alpha      (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         <link linkend="gboolean">gboolean</link> use_alpha);</programlisting>
<para>
Sets whether or not the color button should use the alpha channel.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color_button</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkColorButton"><type>GtkColorButton</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>use_alpha</parameter>&#160;:</term>
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if color button should use alpha channel, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if not.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-get-use-alpha" role="function" condition="since:2.4">
<title>gtk_color_button_get_use_alpha ()</title>
<indexterm zone="gtk-color-button-get-use-alpha" role="2.4"><primary sortas="color_button_get_use_alpha">gtk_color_button_get_use_alpha</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_color_button_get_use_alpha      (<link linkend="GtkColorButton">GtkColorButton</link> *color_button);</programlisting>
<para>
Does the color selection dialog use the alpha channel?</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color_button</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkColorButton"><type>GtkColorButton</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the color sample uses alpha channel, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if not.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-set-title" role="function" condition="since:2.4">
<title>gtk_color_button_set_title ()</title>
<indexterm zone="gtk-color-button-set-title" role="2.4"><primary sortas="color_button_set_title">gtk_color_button_set_title</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_color_button_set_title          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button,
                                                         const <link linkend="gchar">gchar</link> *title);</programlisting>
<para>
Sets the title for the color selection dialog.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color_button</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkColorButton"><type>GtkColorButton</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>title</parameter>&#160;:</term>
<listitem><simpara> String containing new window title.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-color-button-get-title" role="function" condition="since:2.4">
<title>gtk_color_button_get_title ()</title>
<indexterm zone="gtk-color-button-get-title" role="2.4"><primary sortas="color_button_get_title">gtk_color_button_get_title</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       gtk_color_button_get_title          (<link linkend="GtkColorButton">GtkColorButton</link> *color_button);</programlisting>
<para>
Gets the title of the color selection dialog.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>color_button</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkColorButton"><type>GtkColorButton</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> An internal string, do not free the return value

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>

</refsect1>
<refsect1 id="GtkColorButton.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkColorButton--alpha" role="property"><title>The <literal>&quot;alpha&quot;</literal> property</title>
<indexterm zone="GtkColorButton--alpha" role="2.4"><primary sortas="ColorButton:alpha">GtkColorButton:alpha</primary></indexterm><programlisting>  &quot;alpha&quot;                    <link linkend="guint">guint</link>                 : Read / Write</programlisting>
<para>
The selected opacity value (0 fully transparent, 65535 fully opaque).</para>
<para>
</para><para>Allowed values: &lt;= 65535</para>
<para>Default value: 65535</para>
<para>Since 2.4</para>
</refsect2>
<refsect2 id="GtkColorButton--color" role="property"><title>The <literal>&quot;color&quot;</literal> property</title>
<indexterm zone="GtkColorButton--color" role="2.4"><primary sortas="ColorButton:color">GtkColorButton:color</primary></indexterm><programlisting>  &quot;color&quot;                    <link linkend="GdkColor">GdkColor</link>*             : Read / Write</programlisting>
<para>
The selected color.</para>
<para>
</para><para>Since 2.4</para>
</refsect2>
<refsect2 id="GtkColorButton--title" role="property"><title>The <literal>&quot;title&quot;</literal> property</title>
<indexterm zone="GtkColorButton--title" role="2.4"><primary sortas="ColorButton:title">GtkColorButton:title</primary></indexterm><programlisting>  &quot;title&quot;                    <link linkend="gchar">gchar</link>*                : Read / Write</programlisting>
<para>
The title of the color selection dialog</para>
<para>
</para><para>Default value: "Pick a Color"</para>
<para>Since 2.4</para>
</refsect2>
<refsect2 id="GtkColorButton--use-alpha" role="property"><title>The <literal>&quot;use-alpha&quot;</literal> property</title>
<indexterm zone="GtkColorButton--use-alpha" role="2.4"><primary sortas="ColorButton:use-alpha">GtkColorButton:use-alpha</primary></indexterm><programlisting>  &quot;use-alpha&quot;                <link linkend="gboolean">gboolean</link>              : Read / Write</programlisting>
<para>
If this property is set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, the color swatch on the button is rendered against a
checkerboard background to show its opacity and the opacity slider is displayed in the 
color selection dialog.</para>
<para>
</para><para>Default value: FALSE</para>
<para>Since 2.4</para>
</refsect2>

</refsect1>

<refsect1 id="GtkColorButton.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="GtkColorButton-color-set" role="signal"><title>The <literal>&quot;color-set&quot;</literal> signal</title>
<indexterm zone="GtkColorButton-color-set" role="2.4"><primary sortas="ColorButton::color-set">GtkColorButton::color-set</primary></indexterm><programlisting><link linkend="void">void</link>                user_function                      (<link linkend="GtkColorButton">GtkColorButton</link> *widget,
                                                        <link linkend="gpointer">gpointer</link>        user_data)      : Run First</programlisting>
<para>
The ::color-set signal is emitted when the user selects a color.
When handling this signal, use <link linkend="gtk-color-button-get-color"><function>gtk_color_button_get_color()</function></link> and 
<link linkend="gtk-color-button-get-alpha"><function>gtk_color_button_get_alpha()</function></link> to find out which color was just selected.
</para>
<para>
Note that this signal is only emitted when the <emphasis>user</emphasis>
changes the color. If you need to react to programmatic color changes
as well, use the notify::color signal.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter>&#160;:</term>
<listitem><simpara> the object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4</para></refsect2>
</refsect1>


<refsect1 id="GtkColorButton.see-also">
<title>See Also</title>
<para>
<link linkend="GtkColorSelectionDialog"><type>GtkColorSelectionDialog</type></link>, <link linkend="GtkFontButton"><type>GtkFontButton</type></link>
</para>
</refsect1>

</refentry>
