## GwySensitivityGroup

GwySensitivityGroup — Control widget sensitivity by flags

## Synopsis

    #include <libgwydgets/gwydgets.h>

                        GwySensitivityGroup;
                        GwySensitivityGroupClass;
    GwySensitivityGroup* gwy_sensitivity_group_new          (void);
    void                gwy_sensitivity_group_add_widget    (GwySensitivityGroup *sensgroup,
                                                             GtkWidget *widget,
                                                             guint mask);
    void                gwy_sensitivity_group_set_state     (GwySensitivityGroup *sensgroup,
                                                             guint affected_mask,
                                                             guint state);
    guint               gwy_sensitivity_group_get_state     (GwySensitivityGroup *sensgroup);
    void                gwy_sensitivity_group_release_widget
                                                            (GwySensitivityGroup *sensgroup,
                                                             GtkWidget *widget);
    guint               gwy_sensitivity_group_get_widget_mask
                                                            (GwySensitivityGroup *sensgroup,
                                                             GtkWidget *widget);
    void                gwy_sensitivity_group_set_widget_mask
                                                            (GwySensitivityGroup *sensgroup,
                                                             GtkWidget *widget,
                                                             guint mask);

## Object Hierarchy

      GObject
       +----GwySensitivityGroup

## Description

GwySensitivityGroup is a tool to manage sensitivity of sets of related widgets based on fulfilment of some conditions.

A new sensitivity group is created with `gwy_sensitivity_group_new()`. Widgets are then added to it with `gwy_sensitivity_group_add_widget()`, each with some set of flags it reacts to. When state of the sensitivity group is then changed with `gwy_sensitivity_group_set_state()`, widgets whose flags are set are made sensitive, others insensitive (see `gwy_sensitivity_group_set_state()` description for details).

The interpretation of the flags is completely up to GwySensitivityGroup user, but they generally represent availability of some resource or possibility of some action.

In the following example we have two conditions, `SENS_IMAGE` and `SENS_GRAPH`, representing availability of image data and graph data:

    enum {
         SENS_IMAGE = 1 << 0,
         SENS_GRAPH = 1 << 1,
         SENS_MASK  = 0x03
    };

We create buttons for three actions, one operates on image data, another on graph data, and the last on both:

    sensgroup = gwy_sensitivity_group_new();
    button = gtk_button_new_with_label("Filter Data");
    gwy_sensitivity_group_add_widget(sensgroup, button, SENS_IMAGE);
    button = gtk_button_new_with_label("Fit Graph");
    gwy_sensitivity_group_add_widget(sensgroup, button, SENS_GRAPH);
    button = gtk_button_new_with_label("Add Profile");
    gwy_sensitivity_group_add_widget(sensgroup, button, SENS_IMAGE | SENS_GRAPH);
    g_object_unref(sensgroup);

When graph data becomes available, we simply call

    gwy_sensitivity_group_set_state(sensgroup, SENS_GRAPH, SENS_GRAPH);

and when image data becomes unavailable

    gwy_sensitivity_group_set_state(sensgroup, SENS_IMAGE, 0);

and the button sensitivities will be adjusted to match the situation.

## Details

### GwySensitivityGroup

    typedef struct _GwySensitivityGroup GwySensitivityGroup;

### GwySensitivityGroupClass

    typedef struct {
        GObjectClass parent_class;

        void (*reserved1)(void);
        void (*reserved2)(void);
        void (*reserved3)(void);
    } GwySensitivityGroupClass;

### gwy_sensitivity_group_new ()

    GwySensitivityGroup* gwy_sensitivity_group_new          (void);

Creates a new flag-based widget sensitivity group.

Returns : | The newly created sensitivity group. It starts with zero state.

### gwy_sensitivity_group_add_widget ()

    void                gwy_sensitivity_group_add_widget    (GwySensitivityGroup *sensgroup,
                                                             GtkWidget *widget,
                                                             guint mask);

Adds a widget to flag sensitivity group.

Widget sensitivity should not be set manually after the addition as the result is likely to be a fight over sensitivity setting.

The added widget takes a reference on `sensgroup`. So the group is not destroyed when they are any widgets in, generally, you can release your initial reference after adding widgets to the group.

`sensgroup` : | A widget flag sensitivity group.
`widget` : | Widget to add to `sensgroup`.
`mask` : | Which flags the widget is sensitive to. See `gwy_sensitivity_group_set_state()` for details.

### gwy_sensitivity_group_set_state ()

    void                gwy_sensitivity_group_set_state     (GwySensitivityGroup *sensgroup,
                                                             guint affected_mask,
                                                             guint state);

Sets the state of a widget flag sensitivity group.

Widget sensitivity states are then updated accordingly.

More precisely, widget will be made sensitive when all bits in its `mask` are set in current `sensgroup` state, insensitive otherwise. This means when `mask` is zero, widget will be always sensitive.

`sensgroup` : | A widget flag sensitivity group.
`affected_mask` : | Which bits in `state` to copy to `sensgroup` state. 1's in `affected_mask` causes corresponding bits in `sensgroup` state to be set to the value of corresponding bit in `state`. 0's in `affected_mask` cause corresponding state bits to be kept on their current value.
`state` : | The new state of `sensgroup` (masked with `affected_mask`).

### gwy_sensitivity_group_get_state ()

    guint               gwy_sensitivity_group_get_state     (GwySensitivityGroup *sensgroup);

Gets the current state of a widget flag sensitivity group.

`sensgroup` : | A widget flag sensitivity group.
Returns : | The current state as set with `gwy_sensitivity_group_set_state()`.

### gwy_sensitivity_group_release_widget ()

    void                gwy_sensitivity_group_release_widget
                                                            (GwySensitivityGroup *sensgroup,
                                                             GtkWidget *widget);

Removes a widget from flag sensitivity group.

`sensgroup` : | A widget flag sensitivity group.
`widget` : | Widget to remove from `sensgroup`.

### gwy_sensitivity_group_get_widget_mask ()

    guint               gwy_sensitivity_group_get_widget_mask
                                                            (GwySensitivityGroup *sensgroup,
                                                             GtkWidget *widget);

Gets sensitivity flags of a widget in a flag sensitivity group.

`sensgroup` : | A widget flag sensitivity group.
`widget` : | Widget to get flags of.
Returns : | The mask as passed to `gwy_sensitivity_group_add_widget()` or `gwy_sensitivity_group_set_widget_mask()`.

### gwy_sensitivity_group_set_widget_mask ()

    void                gwy_sensitivity_group_set_widget_mask
                                                            (GwySensitivityGroup *sensgroup,
                                                             GtkWidget *widget,
                                                             guint mask);

Sets the flag mask of a widget in a flag sensitivity group.

`sensgroup` : | A widget flag sensitivity group.
`widget` : | Widget to set flags of.
`mask` : | Which flags the widget is sensitive to. See `gwy_sensitivity_group_set_state()` for details.