Checkboxes: Gwyddion Widgets Library Reference Manual

## Checkboxes Checkboxes — Check box group constructors for flags |

## Functions

GSList * | gwy_check_boxes_create ()
GSList * | gwy_check_boxes_createl ()
gint | gwy_check_boxes_attach_to_grid ()
void | gwy_check_boxes_set_selected ()
guint | gwy_check_boxes_get_selected ()
GSList * | gwy_check_box_get_group ()
GtkWidget * | gwy_check_boxes_find ()
void | gwy_check_boxes_set_sensitive ()
guint | gwy_check_box_get_value ()

## Includes

    #include <libgwyui/gwyui.h>

## Description

Groups of check boxes associated with integer flags can be easily constructed from GwyEnum's with `gwy_check_boxes_create()`.

## Functions

### gwy_check_boxes_create()

    GSList *
    gwy_check_boxes_create (const GwyEnum *entries,
                            gint nentries,
                            GCallback callback,
                            gpointer cbdata,
                            guint selected);

Creates a check box group from a set of flags.

All the enum values must be distinct flags, i.e. positive integers with non-overlapping bits (binary AND of any two values must be zero).

The group GSList returned by this function is analogous to GtkRadioButton groups. However, GTK+ does not know anything about it and it cannot be used with any functions expecting a GtkRadioButton group.

#### Parameters

entries | Check box group items. |
nentries | The number of items. Negative value means that `entries` is terminated with a `NULL`-named item. |
callback | A callback called when a check box is selected (or `NULL` for no callback). |
cbdata | User data passed to the callback. |
selected | Combination of flags corresponding to selected items. |

#### Returns

The newly created check box group (a GSList). Iterate over the list and pack the widgets (the order is the same as in `entries` ). The group is owned by the buttons and must not be freed.

### gwy_check_boxes_createl()

    GSList *
    gwy_check_boxes_createl (GCallback callback,
                             gpointer cbdata,
                             guint selected,
                             ...);

Creates a check box group from a list of label/value pairs.

All the enum values must be distinct flags, i.e. positive integers with non-overlapping bits (binary AND of any two values must be zero).

The group GSList returned by this function is analogous to GtkRadioButton groups. However, GTK+ does not know anything about it and it cannot be used with any functions expecting a GtkRadioButton group.

#### Parameters

callback | A callback called when a check box is selected (or `NULL` for no callback). |
cbdata | User data passed to the callback. |
selected | Combination of flags corresponding to selected items. |
... | First item label, first item value, second item label, second item value, etc. Terminated with `NULL`. |

#### Returns

The newly created check box group (a GSList). Iterate over the list and pack the widgets (the order is the same as in `entries` ). The group is owned by the buttons and must not be freed.

### gwy_check_boxes_attach_to_grid()

    gint
    gwy_check_boxes_attach_to_grid (GSList *group,
                                    GtkGrid *grid,
                                    gint colspan,
                                    gint row);

Attaches a group of radio buttons to grid rows.

#### Parameters

group | A radio button group. Not necessarily created by `gwy_check_boxes_create()`. |
grid | A grid widget. |
colspan | The number of columns the radio buttons should span across. |
row | Table row to start attaching at. |

#### Returns

The row after the last attached radio button.

### gwy_check_boxes_set_selected()

    void
    gwy_check_boxes_set_selected (GSList *group,
                                  guint selected);

Sets the state of all check boxes in `group` to given flag combination.

If `selected` differs significantly from the currently selected flags, lots of check buttons will change state, resulting in lots of callbacks. You might want to avoid reacting to each invidivually.

The callback passed upon construction will be called only after all the state of all check boxes is updated so it will see the check boxes already correspond to `selected` . However, any additional signal handlers you set up will be called during the update unless you block them yourself.

#### Parameters

group | A check box group created by `gwy_check_boxes_create()`. |
selected | Flags to be shown as currently selected. |

### gwy_check_boxes_get_selected()

    guint
    gwy_check_boxes_get_selected (GSList *group);

Gets the flag combination corresponding to currently selected items.

#### Parameters

group | A check box group created by `gwy_check_boxes_create()` or `gwy_check_boxes_createl()`. |

#### Returns

The combination of flags corresponding to currently selected items.

### gwy_check_box_get_group()

    GSList *
    gwy_check_box_get_group (GtkWidget *checkbox);

Gets the group a check box belongs to.

#### Parameters

checkbox | A check box belonging to a group created by `gwy_check_boxes_create()` or `gwy_check_boxes_createl()`. |

#### Returns

The group `checkbox` belongs to.

### gwy_check_boxes_find()

    GtkWidget *
    gwy_check_boxes_find (GSList *group,
                          guint value);

Finds a check box by its associated flag value.

The value must corresponding exactly to the single flag. Otherwise the check box is not considered a match.

#### Parameters

group | A check box group created by `gwy_check_boxes_create()` or `gwy_check_boxes_createl()`. |
value | The value associated with the check box to find. |

#### Returns

The check box corresponding to `value` , or `NULL` on failure.

### gwy_check_boxes_set_sensitive()

    void
    gwy_check_boxes_set_sensitive (GSList *group,
                                   gboolean sensitive);

Sets the sensitivity of all check box in a group.

This function is useful to make the choice as a whole available/unavailable. Use `gwy_check_boxes_find()` combined with `gtk_widget_set_sensitive()` to manage sensitivity of individual options.

#### Parameters

group | A check box group created by `gwy_check_boxes_create()`. |
sensitive | `TRUE` to make all choices sensitive, `FALSE` to make all insensitive. |

### gwy_check_box_get_value()

    guint
    gwy_check_box_get_value (GtkWidget *checkbox);

Gets the flag value associated with a check box.

#### Parameters

checkbox | A check box belonging to a group created by `gwy_check_boxes_create()` or `gwy_check_boxes_createl()`. |

#### Returns

The flag value corresponding to `button` .

## See Also

gwycombobox

-- combo box constructors;

radiobuttons

-- radio button constructors