<refentry id="GtkCheckMenuItem">
<refmeta>
<refentrytitle>GtkCheckMenuItem</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkCheckMenuItem</refname><refpurpose>a menu item with a check box.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

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


struct      <link linkend="GtkCheckMenuItem-struct">GtkCheckMenuItem</link>;
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gtk-check-menu-item-new">gtk_check_menu_item_new</link>         (void);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gtk-check-menu-item-new-with-label">gtk_check_menu_item_new_with_label</link>
                                            (const <link linkend="gchar">gchar</link> *label);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gtk-check-menu-item-new-with-mnemonic">gtk_check_menu_item_new_with_mnemonic</link>
                                            (const <link linkend="gchar">gchar</link> *label);
#define     <link linkend="gtk-check-menu-item-set-state">gtk_check_menu_item_set_state</link>
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-check-menu-item-get-active">gtk_check_menu_item_get_active</link>  (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item);
void        <link linkend="gtk-check-menu-item-set-active">gtk_check_menu_item_set_active</link>  (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item,
                                             <link linkend="gboolean">gboolean</link> is_active);
void        <link linkend="gtk-check-menu-item-set-show-toggle">gtk_check_menu_item_set_show_toggle</link>
                                            (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *menu_item,
                                             <link linkend="gboolean">gboolean</link> always);
void        <link linkend="gtk-check-menu-item-toggled">gtk_check_menu_item_toggled</link>     (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-check-menu-item-get-inconsistent">gtk_check_menu_item_get_inconsistent</link>
                                            (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item);
void        <link linkend="gtk-check-menu-item-set-inconsistent">gtk_check_menu_item_set_inconsistent</link>
                                            (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item,
                                             <link linkend="gboolean">gboolean</link> setting);


</synopsis>
</refsynopsisdiv>

<refsect1>
<title>Object Hierarchy</title>
<synopsis>

  <link linkend="GObject">GObject</link>
   +----<link linkend="GtkObject">GtkObject</link>
         +----<link linkend="GtkWidget">GtkWidget</link>
               +----<link linkend="GtkContainer">GtkContainer</link>
                     +----<link linkend="GtkBin">GtkBin</link>
                           +----<link linkend="GtkItem">GtkItem</link>
                                 +----<link linkend="GtkMenuItem">GtkMenuItem</link>
                                       +----GtkCheckMenuItem
</synopsis>

</refsect1>

<refsect1>
<title>Properties</title>
<synopsis>

  &quot;<link linkend="GtkCheckMenuItem--active">active</link>&quot;               <link linkend="gboolean">gboolean</link>             : Read / Write
  &quot;<link linkend="GtkCheckMenuItem--inconsistent">inconsistent</link>&quot;         <link linkend="gboolean">gboolean</link>             : Read / Write
</synopsis>
</refsect1>

<refsect1>
<title>Signal Prototypes</title>
<synopsis>

&quot;<link linkend="GtkCheckMenuItem-toggled">toggled</link>&quot;   void        user_function      (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *checkmenuitem,
                                            <link linkend="gpointer">gpointer</link> user_data);
</synopsis>
</refsect1>


<refsect1>
<title>Description</title>
<para>
A <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> is a menu item that maintains the state of a boolean 
value in addition to a <link linkend="GtkMenuItem">GtkMenuItem</link>'s usual role in activating application
code.
</para>

<para>
A check box indicating the state of the boolean value is displayed
at the left side of the <link linkend="GtkMenuItem">GtkMenuItem</link>.  Activating the <link linkend="GtkMenuItem">GtkMenuItem</link> 
toggles the value.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GtkCheckMenuItem-struct">struct GtkCheckMenuItem</title>
<programlisting>struct GtkCheckMenuItem;</programlisting>
<para>
The <link linkend="GtkCheckMenuItem-struct">GtkCheckMenuItem</link> struct contains the following fields.
(These fields should be considered read-only. They should never be set by
an application.)

<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>

<row>
<entry><link linkend="guint">guint</link> active;</entry>
<entry>TRUE if the check box is active.</entry>
</row>

</tbody></tgroup></informaltable>
</para></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-new">gtk_check_menu_item_new ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gtk_check_menu_item_new         (void);</programlisting>
<para>
Creates a new <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-new-with-label">gtk_check_menu_item_new_with_label ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gtk_check_menu_item_new_with_label
                                            (const <link linkend="gchar">gchar</link> *label);</programlisting>
<para>
Creates a new <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> with a label.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>label</parameter>&nbsp;:</entry>
<entry>the string to use for the label.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-new-with-mnemonic">gtk_check_menu_item_new_with_mnemonic ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gtk_check_menu_item_new_with_mnemonic
                                            (const <link linkend="gchar">gchar</link> *label);</programlisting>
<para>
Creates a new <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> containing a label. The label
will be created using <link linkend="gtk-label-new-with-mnemonic">gtk_label_new_with_mnemonic</link>(), so underscores
in <parameter>label</parameter> indicate the mnemonic for the menu item.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>label</parameter>&nbsp;:</entry>
<entry> The text of the button, with an underscore in front of the
        mnemonic character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-set-state">gtk_check_menu_item_set_state</title>
<programlisting>#define	gtk_check_menu_item_set_state		gtk_check_menu_item_set_active
</programlisting>
<warning>
<para>
<literal>gtk_check_menu_item_set_state</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
This macro is provided to preserve compatibility with older code.
New code should use <link linkend="gtk-check-menu-item-set-active">gtk_check_menu_item_set_active</link>() function instead.
</para></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-get-active">gtk_check_menu_item_get_active ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_check_menu_item_get_active  (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item);</programlisting>
<para>
Returns whether the check menu item is active. See
<link linkend="gtk-check-menu-item-set-active">gtk_check_menu_item_set_active</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>check_menu_item</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the menu item is checked.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-set-active">gtk_check_menu_item_set_active ()</title>
<programlisting>void        gtk_check_menu_item_set_active  (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item,
                                             <link linkend="gboolean">gboolean</link> is_active);</programlisting>
<para>
Sets the active state of the menu item's check box.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>check_menu_item</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>.
</entry></row>
<row><entry align="right"><parameter>is_active</parameter>&nbsp;:</entry>
<entry>boolean value indicating whether the check box is active.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-set-show-toggle">gtk_check_menu_item_set_show_toggle ()</title>
<programlisting>void        gtk_check_menu_item_set_show_toggle
                                            (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *menu_item,
                                             <link linkend="gboolean">gboolean</link> always);</programlisting>
<warning>
<para>
<literal>gtk_check_menu_item_set_show_toggle</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Controls whether the check box is shown at all times.
Normally the check box is shown only when it is active or while the 
menu item is selected.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>menu_item</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>.
</entry></row>
<row><entry align="right"><parameter>always</parameter>&nbsp;:</entry>
<entry>boolean value indicating whether to always show the check box.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-toggled">gtk_check_menu_item_toggled ()</title>
<programlisting>void        gtk_check_menu_item_toggled     (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item);</programlisting>
<para>
Emits the GtkCheckMenuItem::toggled signal.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>check_menu_item</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-get-inconsistent">gtk_check_menu_item_get_inconsistent ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_check_menu_item_get_inconsistent
                                            (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item);</programlisting>
<para>
Retrieves the value set by <link linkend="gtk-check-menu-item-set-inconsistent">gtk_check_menu_item_set_inconsistent</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>check_menu_item</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if inconsistent
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-check-menu-item-set-inconsistent">gtk_check_menu_item_set_inconsistent ()</title>
<programlisting>void        gtk_check_menu_item_set_inconsistent
                                            (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *check_menu_item,
                                             <link linkend="gboolean">gboolean</link> setting);</programlisting>
<para>
If the user has selected a range of elements (such as some text or
spreadsheet cells) that are affected by a boolean setting, and the
current values in that range are inconsistent, you may want to
display the check in an "in between" state. This function turns on
"in between" display.  Normally you would turn off the inconsistent
state again if the user explicitly selects a setting. This has to be
done manually, <link linkend="gtk-check-menu-item-set-inconsistent">gtk_check_menu_item_set_inconsistent</link>() only affects
visual appearance, it doesn't affect the semantics of the widget.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>check_menu_item</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link>
</entry></row>
<row><entry align="right"><parameter>setting</parameter>&nbsp;:</entry>
<entry> <literal>TRUE</literal> to display an "inconsistent" third state check
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>
<refsect1>
<title>Properties</title>
<variablelist>
<varlistentry><term><anchor id="GtkCheckMenuItem--active">&quot;<literal>active</literal>&quot; (<link linkend="gboolean">gboolean</link> : Read / Write)</term>
<listitem>
<para>

</para></listitem></varlistentry>
<varlistentry><term><anchor id="GtkCheckMenuItem--inconsistent">&quot;<literal>inconsistent</literal>&quot; (<link linkend="gboolean">gboolean</link> : Read / Write)</term>
<listitem>
<para>

</para></listitem></varlistentry>

</variablelist>
</refsect1>

<refsect1>
<title>Signals</title>
<refsect2><title><anchor id="GtkCheckMenuItem-toggled">The &quot;toggled&quot; signal</title>
<programlisting>void        user_function                  (<link linkend="GtkCheckMenuItem">GtkCheckMenuItem</link> *checkmenuitem,
                                            <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
This signal is emitted when the state of the check box is changed.
</para>

<para>
A signal handler can examine the <structfield>active</structfield> 
field of the <link linkend="GtkCheckMenuItem-struct">GtkCheckMenuItem</link> struct to discover the new state.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>checkmenuitem</parameter>&nbsp;:</entry>
<entry>the object which received the signal.

</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry>user data set when the signal handler was connected.</entry></row>
</tbody></tgroup></informaltable></refsect2>
</refsect1>



</refentry>
