GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkCheckMenuItem

## Name

GtkCheckMenuItem -- a menu item with a check box.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkCheckMenuItem;
    GtkWidget*  gtk_check_menu_item_new         (void);
    GtkWidget*  gtk_check_menu_item_new_with_label
                                                (const gchar *label);
    GtkWidget*  gtk_check_menu_item_new_with_mnemonic
                                                (const gchar *label);
    #define     gtk_check_menu_item_set_state
    gboolean    gtk_check_menu_item_get_active  (GtkCheckMenuItem *check_menu_item);
    void        gtk_check_menu_item_set_active  (GtkCheckMenuItem *check_menu_item,
                                                 gboolean is_active);
    void        gtk_check_menu_item_set_show_toggle
                                                (GtkCheckMenuItem *menu_item,
                                                 gboolean always);
    void        gtk_check_menu_item_toggled     (GtkCheckMenuItem *check_menu_item);
    gboolean    gtk_check_menu_item_get_inconsistent
                                                (GtkCheckMenuItem *check_menu_item);
    void        gtk_check_menu_item_set_inconsistent
                                                (GtkCheckMenuItem *check_menu_item,
                                                 gboolean setting);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkItem
                                     +----GtkMenuItem
                                           +----GtkCheckMenuItem

## Properties

      "active"               gboolean             : Read / Write
      "inconsistent"         gboolean             : Read / Write

## Signal Prototypes

    "toggled"   void        user_function      (GtkCheckMenuItem *checkmenuitem,
                                                gpointer user_data);

## Description

A GtkCheckMenuItem is a menu item that maintains the state of a boolean value in addition to a GtkMenuItem's usual role in activating application code.

A check box indicating the state of the boolean value is displayed at the left side of the GtkMenuItem. Activating the GtkMenuItem toggles the value.

## Details

### struct GtkCheckMenuItem

    struct GtkCheckMenuItem;

The GtkCheckMenuItem struct contains the following fields. (These fields should be considered read-only. They should never be set by an application.)

guint active; | TRUE if the check box is active.

### gtk_check_menu_item_new ()

    GtkWidget*  gtk_check_menu_item_new         (void);

Creates a new GtkCheckMenuItem.

Returns : | a new GtkCheckMenuItem.

### gtk_check_menu_item_new_with_label ()

    GtkWidget*  gtk_check_menu_item_new_with_label
                                                (const gchar *label);

Creates a new GtkCheckMenuItem with a label.

`label` : | the string to use for the label.
Returns : | a new GtkCheckMenuItem.

### gtk_check_menu_item_new_with_mnemonic ()

    GtkWidget*  gtk_check_menu_item_new_with_mnemonic
                                                (const gchar *label);

Creates a new GtkCheckMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in `label` indicate the mnemonic for the menu item.

`label` : | The text of the button, with an underscore in front of the mnemonic character
Returns : | a new GtkCheckMenuItem

### gtk_check_menu_item_set_state

    #define	gtk_check_menu_item_set_state		gtk_check_menu_item_set_active

Warning
`gtk_check_menu_item_set_state` is deprecated and should not be used in newly-written code.

This macro is provided to preserve compatibility with older code. New code should use gtk_check_menu_item_set_active() function instead.

### gtk_check_menu_item_get_active ()

    gboolean    gtk_check_menu_item_get_active  (GtkCheckMenuItem *check_menu_item);

Returns whether the check menu item is active. See gtk_check_menu_item_set_active().

`check_menu_item` : | a GtkCheckMenuItem
Returns : | `TRUE` if the menu item is checked.

### gtk_check_menu_item_set_active ()

    void        gtk_check_menu_item_set_active  (GtkCheckMenuItem *check_menu_item,
                                                 gboolean is_active);

Sets the active state of the menu item's check box.

`check_menu_item` : | a GtkCheckMenuItem.
`is_active` : | boolean value indicating whether the check box is active.

### gtk_check_menu_item_set_show_toggle ()

    void        gtk_check_menu_item_set_show_toggle
                                                (GtkCheckMenuItem *menu_item,
                                                 gboolean always);

Warning
`gtk_check_menu_item_set_show_toggle` is deprecated and should not be used in newly-written code.

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.

`menu_item` : | a GtkCheckMenuItem.
`always` : | boolean value indicating whether to always show the check box.

### gtk_check_menu_item_toggled ()

    void        gtk_check_menu_item_toggled     (GtkCheckMenuItem *check_menu_item);

Emits the GtkCheckMenuItem::toggled signal.

`check_menu_item` : | a GtkCheckMenuItem.

### gtk_check_menu_item_get_inconsistent ()

    gboolean    gtk_check_menu_item_get_inconsistent
                                                (GtkCheckMenuItem *check_menu_item);

Retrieves the value set by gtk_check_menu_item_set_inconsistent().

`check_menu_item` : | a GtkCheckMenuItem
Returns : | `TRUE` if inconsistent

### gtk_check_menu_item_set_inconsistent ()

    void        gtk_check_menu_item_set_inconsistent
                                                (GtkCheckMenuItem *check_menu_item,
                                                 gboolean setting);

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, gtk_check_menu_item_set_inconsistent() only affects visual appearance, it doesn't affect the semantics of the widget.

`check_menu_item` : | a GtkCheckMenuItem
`setting` : | `TRUE` to display an "inconsistent" third state check

## Properties

"`active`" (gboolean : Read / Write)

  Whether the menu item is checked.

"`inconsistent`" (gboolean : Read / Write)

  Whether to display an "inconsistent" state.

## Signals

### The "toggled" signal

    void        user_function                  (GtkCheckMenuItem *checkmenuitem,
                                                gpointer user_data);

This signal is emitted when the state of the check box is changed.

A signal handler can examine the `active` field of the GtkCheckMenuItem struct to discover the new state.

`checkmenuitem` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

<<< Previous Page | Home | Up | Next Page >>>
GtkRadioMenuItem | GtkSeparatorMenuItem