Choice widget
-------------

A choice widget is a class of widgets that allows to select exactly one choice
from a given set.

There are two different choices application APIs, the choices can either be
static initialized by an string array, or dynamic backed by an structure with
callbacks.

The widget class allows to get values and modify widget state by an unified
API.

.Choice class API functions
[source,c]
-------------------------------------------------------------------------------
void gp_widget_choice_sel_set(gp_widget *self, size_t sel);

size_t gp_widget_choice_sel_get(gp_widget *self);

size_t gp_widget_choice_prev_sel_get(gp_widget *self);

size_t gp_widget_choice_cnt_get(gp_widget *self);

const char *gp_widget_choice_name_get(gp_widget *self, size_t idx);
-------------------------------------------------------------------------------

Functions to get and set the selected choice, the choices count and particular
choice name and the choice widget class constructor.

The 'gp_widget_choice_prev_sel_get()' can be used to query previously selected
choice inside of the widget event handler.

.Choice class ops and array constructors
[source,c]
-------------------------------------------------------------------------------
enum gp_widget_choice_flags {
        GP_WIDGET_CHOICE_COPY = 1,
};

gp_widget *gp_widget_choice_new(unsigned int widget_type,
                                const char *choices[],
                                size_t cnt, size_t sel);

gp_widget *gp_widget_choice_ops_new(unsigned int widget_type,
                                    const struct gp_widget_choice_ops *ops);

gp_widget *gp_widget_choice_arr_new(unsigned int widget_type, const void *array,
                                    size_t memb_cnt, uint16_t memb_size,
                                    uint16_t memb_off, size_t sel, int flags);
-------------------------------------------------------------------------------

Creates a choice widget from a static array. The array choices can either be
compied when 'GP_WIDGET_CHOICE_COPY' is passed in the flags, or the base
pointer is stored and dereferenced each time widget is repainted.

See link:example_widgets_choice2.html[choice array API example].

.Choices callback API
[source,c]
-------------------------------------------------------------------------------
enum gp_widget_choice_op {
        GP_WIDGET_CHOICE_OP_SEL,
        GP_WIDGET_CHOICE_OP_CNT,
};

struct gp_widget_choice_ops {
        const char *(*get_choice)(gp_widget *self, size_t idx);
        size_t (*get)(gp_widget *self, enum gp_widget_choice_op op);
        void (*set)(gp_widget *self, size_t val);
};

void gp_widget_choice_refresh(gp_widget *self);
-------------------------------------------------------------------------------

The ops structure implements callbacks to get choice count and selected
choice, set selected choice and get choice name.

The refresh function must be called by the application every time the choices
do change since the widget will cache some of the data returned by these
callbacks. The refresh function will re-read the data and also check if the
widget needs to be resized.

See link:example_widgets_choice.html[choice ops API example].

Spinbutton
~~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
gp_widget *gp_widget_spinbutton_new(const char *choices[],
                                    unsigned int choice_cnt,
                                    unsigned int selected);

gp_widget *gp_widget_spinbutton_ops_new(const struct gp_widget_choice_ops *ops);

gp_widget *gp_widget_spinbutton_arr_new(const void *array,
                                        size_t memb_cnt, uint16_t memb_size,
                                        uint16_t memb_off, size_t sel, int flags);
-------------------------------------------------------------------------------

Spinbutton is parsed from JSON with when type equals to "spinbutton".

.Spinbutton
image:spinbutton.png[Spinbutton]

Radiobutton
~~~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
gp_widget *gp_widget_radiobutton_new(const char *choices[],
                                     unsigned int choice_cnt,
                                     unsigned int selected);

gp_widget *gp_widget_radiobutton_ops_new(const struct gp_widget_choice_ops *ops);

gp_widget *gp_widget_radiobutton_arr_new(const void *array,
                                         size_t memb_cnt, uint16_t memb_size,
                                         uint16_t memb_off, size_t sel, int flags);
-------------------------------------------------------------------------------

Radiobutton is parsed from JSON with when type equals to "radiobutton".

.Radiobutton
image:radiobutton.png[Radiobutton]

.Choice class JSON attributes
[cols=",,,3",options="header"]
|===================================================
|  Attribute  |     Type      | Default | Description
|  +choices+  | string array  |         | List of choices
|  +ops+      |    string     |         | The ops structure id
|  +selected+ | uint | string |    0    | Currently selected choice
|===================================================

.Choice class widget events
[cols=",3",options="header"]
|===================================================
| Widget event value | Description
|         0          | Emitted on selection change.
|===================================================
