This module provides a spinner widget system for monochrome graphical displays.
There is support for having one single spinner on the screen, or a collection of spinners.
Typical flow of an application using the spincollection system:
1) Define spinners.
2) Initialize each spinners with gfx_mono_spinctrl_init.
3) Define a spincollection struct and initialize it with gfx_mono_spinctrl_spincollection_init.
4) Add spinners to spincollection with gfx_mono_spinctrl_spincollection_add_spinner.
5) Draw spincollection to screen with gfx_mono_spinctrl_spincollection_show.
6) Define a result array to store the spinner choices.
7) Update spinners and result array with user input using function gfx_mono_spinctrl_spincollection_process_key.
8) Interpret gfx_mono_spinctrl_spincollection_process_key return value.
9) Go to 7.
Typical flow of an application using a single spinner:
1) Define spinner.
2) Initialize the spinners with gfx_mono_spinctrl_init with preferred y position on screen.
3) Draw spinner to screen with gfx_mono_spinctrl_draw.
4) Update spinner with user input using function gfx_mono_spinctrl_process_key.
5) Interpret gfx_mono_spinctrl_process_key return value.
6) Go to 4.
Before the spinners can be updated, you need input from the user. Methods for getting input is not part of the spinner widget.
As soon as input is received, inform the spincollection system or the single spinner using the gfx_mono_spinctrl_spincollection_process_key function or the gfx_mono_spinctrl_process_key function. These functions will then return a status code and act depending on the given keycode:
GFX_MONO_SPINCTRL_KEYCODE_DOWN : Change selection to next spinner value or to next spinner or OK button in a spincollection.
GFX_MONO_SPINCTRL_KEYCODE_UP : Change selection to previous spinner value or to previous spinner or OK button in a spincollection.
GFX_MONO_SPINCTRL_KEYCODE_ENTER : Select spinner value or select spinner or OK button in a spincollection.
GFX_MONO_SPINCTRL_KEYCODE_BACK : Deselect spinner or cancel spincollection application.
The value of the keycodes used are defined in conf_spinctrl.h. These values can be changed if needed.
The graphical indicators used to indicate spinner selections are defined in conf_spinctrl.h. These indicators can be changed if needed.
Data Structures | |
| struct | gfx_mono_spinctrl |
| Spin control struct. More... | |
| struct | gfx_mono_spinctrl_spincollection |
| Collection of spinners struct. More... | |
| struct | gfx_mono_spinctrl_string |
| String struct. More... | |
Macros | |
| #define | GFX_MONO_SPINCTRL_BUTTON 0xFF |
| OK button. More... | |
| #define | GFX_MONO_SPINCTRL_ELEMENTS_PER_SCREEN ((GFX_MONO_LCD_HEIGHT / SYSFONT_LINESPACING) - 1) |
| Maximum number of spinner elements on display. More... | |
| #define | GFX_MONO_SPINCTRL_EVENT_BACK 0xFE |
| Spinner back button pressed event. More... | |
| #define | GFX_MONO_SPINCTRL_EVENT_FINISH 0xFD |
| Spinner ok button pressed event. More... | |
| #define | GFX_MONO_SPINCTRL_EVENT_IDLE 0xFF |
| Spinner idle event. More... | |
| #define | GFX_MONO_SPINCTRL_INT_SPINNER_WIDTH 9 |
| Width of integer spinner choices. More... | |
| #define | GFX_MONO_SPINCTRL_MAX_ELEMENTS_IN_SPINCOLLECTION GFX_MONO_SPINCTRL_ELEMENTS_PER_SCREEN |
| Maximum numbers of spinner elements in a spincollection - limited to one screen. More... | |
| #define | GFX_MONO_SPINCTRL_STRING_SPINNER_WIDTH 9 |
| Width of string spinner choices. More... | |
Typedefs | |
| typedef enum gfx_mono_spinctrl_type_enum | gfx_mono_spinctrl_type_t |
| Enum to specify what kind of data spinner should spin. More... | |
Enumerations | |
| enum | gfx_mono_spinctrl_type_enum { SPINTYPE_STRING, SPINTYPE_INTEGER } |
| Enum to specify what kind of data spinner should spin. More... | |
Functions | |
| void | gfx_mono_spinctrl_draw (struct gfx_mono_spinctrl *spinner, bool redraw) |
| Draw spinner at its position. More... | |
| void | gfx_mono_spinctrl_init (struct gfx_mono_spinctrl *spinner, gfx_mono_spinctrl_type_t datatype, PROGMEM_STRING_T title, PROGMEM_STRING_T *data, int16_t lower_limit, int16_t upper_limit, gfx_coord_t y) |
| Initialize a spinner. More... | |
| int16_t | gfx_mono_spinctrl_process_key (struct gfx_mono_spinctrl *spinner, uint8_t keycode) |
| Update single spinner depending on input. More... | |
| void | gfx_mono_spinctrl_spincollection_add_spinner (struct gfx_mono_spinctrl *spinner, struct gfx_mono_spinctrl_spincollection *spinners) |
| Add spinner to spincollection. More... | |
| void | gfx_mono_spinctrl_spincollection_init (struct gfx_mono_spinctrl_spincollection *collection) |
| Initialize a spincollection. More... | |
| int16_t | gfx_mono_spinctrl_spincollection_process_key (struct gfx_mono_spinctrl_spincollection *spinners, uint8_t keycode, int16_t results[]) |
| Update spincollection on screen depending on input. More... | |
| void | gfx_mono_spinctrl_spincollection_show (struct gfx_mono_spinctrl_spincollection *spinners) |
| Show spincollection. More... | |
| #define GFX_MONO_SPINCTRL_BUTTON 0xFF |
OK button.
Referenced by gfx_mono_spinctrl_spincollection_process_key().
| #define GFX_MONO_SPINCTRL_ELEMENTS_PER_SCREEN ((GFX_MONO_LCD_HEIGHT / SYSFONT_LINESPACING) - 1) |
Maximum number of spinner elements on display.
| #define GFX_MONO_SPINCTRL_EVENT_BACK 0xFE |
Spinner back button pressed event.
Referenced by gfx_mono_spinctrl_process_key(), and gfx_mono_spinctrl_spincollection_process_key().
| #define GFX_MONO_SPINCTRL_EVENT_FINISH 0xFD |
Spinner ok button pressed event.
Referenced by gfx_mono_spinctrl_spincollection_process_key().
| #define GFX_MONO_SPINCTRL_EVENT_IDLE 0xFF |
Spinner idle event.
Referenced by gfx_mono_spinctrl_process_key(), and gfx_mono_spinctrl_spincollection_process_key().
| #define GFX_MONO_SPINCTRL_INT_SPINNER_WIDTH 9 |
Width of integer spinner choices.
Referenced by gfx_mono_spinctrl_draw().
| #define GFX_MONO_SPINCTRL_MAX_ELEMENTS_IN_SPINCOLLECTION GFX_MONO_SPINCTRL_ELEMENTS_PER_SCREEN |
Maximum numbers of spinner elements in a spincollection - limited to one screen.
Referenced by gfx_mono_spinctrl_draw_button(), and gfx_mono_spinctrl_spincollection_add_spinner().
| #define GFX_MONO_SPINCTRL_STRING_SPINNER_WIDTH 9 |
Width of string spinner choices.
Referenced by gfx_mono_spinctrl_draw().
| typedef enum gfx_mono_spinctrl_type_enum gfx_mono_spinctrl_type_t |
Enum to specify what kind of data spinner should spin.
| void gfx_mono_spinctrl_draw | ( | struct gfx_mono_spinctrl * | spinner, |
| bool | redraw | ||
| ) |
Draw spinner at its position.
This function draws a spinner at its position. The title of the spinner is only drawn if the redraw option is set. If the spinner is in focus, arrows will be drawn next to the spinner value to indicate that it is spinnable.
| [in] | spinner | pointer to initialized gfx_mono_spinctrl struct |
| [in] | redraw | true if title of spinner should be drawn |
References gfx_mono_spinctrl_string::data, gfx_mono_spinctrl::datatype, gfx_mono_draw_filled_rect, gfx_mono_draw_progmem_string(), gfx_mono_draw_string(), GFX_MONO_LCD_WIDTH, gfx_mono_spinctrl_draw_spin_indicator(), GFX_MONO_SPINCTRL_INT_SPINNER_WIDTH, GFX_MONO_SPINCTRL_STRING_SPINNER_WIDTH, GFX_PIXEL_CLR, gfx_mono_spinctrl::in_focus, gfx_mono_spinctrl_string::index, gfx_mono_spinctrl::integer_data, PROGMEM_PTR_T, SPINTYPE_INTEGER, SPINTYPE_STRING, gfx_mono_spinctrl::strings, sysfont, gfx_mono_spinctrl::title, and gfx_mono_spinctrl::y.
Referenced by gfx_mono_spinctrl_process_key(), and gfx_mono_spinctrl_spincollection_show().
| void gfx_mono_spinctrl_init | ( | struct gfx_mono_spinctrl * | spinner, |
| gfx_mono_spinctrl_type_t | datatype, | ||
| PROGMEM_STRING_T | title, | ||
| PROGMEM_STRING_T * | data, | ||
| int16_t | lower_limit, | ||
| int16_t | upper_limit, | ||
| gfx_coord_t | y | ||
| ) |
Initialize a spinner.
This function initializes a spinner to either SPINTYPE_STRING spinner that spins through the strings in a PROGMEM_STRING_T or a SPINTYPE_INTEGER spinner that spins through integers. If the spinner type is SPINTYPE_INTEGER, it will spin from lower_limit to upper_limit. If the spinner type is SPINTYPE_STRING, a pointer to a PROGMEM_STRING_T must be provided, and the spinner will spin through the strings starting at index lower_limit ending at index upper_limit. The y parameter specifies where to place the spinner on the screen, but is overwritten if the spinner is put in a spincollection.
| [out] | spinner | pointer to initialized gfx_mono_spinctrl struct |
| [in] | datatype | typer of spinner, integer or string |
| [in] | title | title of spinner |
| [in] | data | pointer to progmem string array if datatype is string. NULL if datatype is integer. |
| [in] | lower_limit | lower limit and start value of spinner's data |
| [in] | upper_limit | upper limit of spinner's data |
| [in] | y | y position of spinner |
References gfx_mono_spinctrl_string::data, data, gfx_mono_spinctrl::datatype, gfx_mono_spinctrl::in_focus, gfx_mono_spinctrl_string::index, gfx_mono_spinctrl::integer_data, gfx_mono_spinctrl::last_saved_value, gfx_mono_spinctrl::lower_limit, SPINTYPE_STRING, gfx_mono_spinctrl::strings, gfx_mono_spinctrl::title, gfx_mono_spinctrl::upper_limit, and gfx_mono_spinctrl::y.
| int16_t gfx_mono_spinctrl_process_key | ( | struct gfx_mono_spinctrl * | spinner, |
| uint8_t | keycode | ||
| ) |
Update single spinner depending on input.
| [in] | spinner | pointer to initialized spinner. |
| [in] | keycode | keycode to process |
| selected | selected spinner value |
| GFX_MONO_SPINCTRL_EVENT_IDLE | spinner spinning |
| GFX_MONO_SPINCTRL_EVENT_BACK | spinner deselected |
References gfx_mono_spinctrl::datatype, gfx_mono_spinctrl_draw(), GFX_MONO_SPINCTRL_EVENT_BACK, GFX_MONO_SPINCTRL_EVENT_IDLE, gfx_mono_spinctrl_step_down(), gfx_mono_spinctrl_step_up(), gfx_mono_spinctrl::in_focus, gfx_mono_spinctrl_string::index, gfx_mono_spinctrl::integer_data, gfx_mono_spinctrl::last_saved_value, SPINTYPE_INTEGER, SPINTYPE_STRING, and gfx_mono_spinctrl::strings.
Referenced by gfx_mono_spinctrl_spincollection_process_key().
| void gfx_mono_spinctrl_spincollection_add_spinner | ( | struct gfx_mono_spinctrl * | spinner, |
| struct gfx_mono_spinctrl_spincollection * | spinners | ||
| ) |
Add spinner to spincollection.
This function adds an initialized spinner to a spincollection and positions it below any other spinners in the spincollection on the screen. The spinners in the spincollection are linked together and number of spinners is updated. It is not possible to add more spinners than maximum number ofspinners in a spincollection".
| [in] | spinner | pointer to initialized gfx_mono_spinctrl struct to add to collection |
| [in] | spinners | pointer to initialized gfx_mono_spinctrl_spincollection struct |
References gfx_mono_spinctrl_spincollection::collection, gfx_mono_spinctrl_spincollection::collection_last, GFX_MONO_SPINCTRL_MAX_ELEMENTS_IN_SPINCOLLECTION, i, if(), gfx_mono_spinctrl::next, gfx_mono_spinctrl_spincollection::number_of_spinners, gfx_mono_spinctrl::prev, and gfx_mono_spinctrl::y.
| void gfx_mono_spinctrl_spincollection_init | ( | struct gfx_mono_spinctrl_spincollection * | collection | ) |
Initialize a spincollection.
This function initializes a spincollection to which spinners can be added.
| [out] | collection | pointer to gfx_mono_spinctrl_spincollection to Initialize |
References gfx_mono_spinctrl_spincollection::active_spinner, gfx_mono_spinctrl_spincollection::current_selection, gfx_mono_spinctrl_spincollection::init, and gfx_mono_spinctrl_spincollection::number_of_spinners.
| int16_t gfx_mono_spinctrl_spincollection_process_key | ( | struct gfx_mono_spinctrl_spincollection * | spinners, |
| uint8_t | keycode, | ||
| int16_t | results[] | ||
| ) |
Update spincollection on screen depending on input.
This function returns GFX_MONO_SPINCTRL_EVENT_FINISH if user has pressed the OK button. The spinner choices can then be extracted from the results array. If a spinner is of type SPINTYPE_STRING, the index of the progmem string will be stored in the results array, else the selected integer value will be stored. The choice from the first spinner added to the spincollection will be stored at index 0 in the results array, the second at index 1 and so on. If user has pressed the back button, GFX_MONO_SPINCTRL_EVENT_BACK is returned, signalling that the application should be cancelled.
| [in] | spinners | pointer to initialized gfx_mono_spinctrl_spincollection |
| [in] | keycode | keycode to process |
| [in] | results | array to store results from the spinners, must be of same length as number of spinners |
| GFX_MONO_SPINCTRL_EVENT_FINISH | user pressed ok button |
| GFX_MONO_SPINCTRL_EVENT_BACK | user cancelled |
| GFX_MONO_SPINCTRL_EVENT_IDLE | user is navigating in spincollection |
References gfx_mono_spinctrl_spincollection::active_spinner, gfx_mono_spinctrl_spincollection::collection, gfx_mono_spinctrl_spincollection::collection_last, gfx_mono_spinctrl_spincollection::current_selection, gfx_mono_spinctrl::datatype, GFX_MONO_SPINCTRL_BUTTON, gfx_mono_spinctrl_draw_button(), gfx_mono_spinctrl_draw_indicator(), GFX_MONO_SPINCTRL_EVENT_BACK, GFX_MONO_SPINCTRL_EVENT_FINISH, GFX_MONO_SPINCTRL_EVENT_IDLE, gfx_mono_spinctrl_process_key(), i, gfx_mono_spinctrl_string::index, gfx_mono_spinctrl_spincollection::init, gfx_mono_spinctrl::integer_data, gfx_mono_spinctrl::next, gfx_mono_spinctrl_spincollection::number_of_spinners, gfx_mono_spinctrl::prev, gfx_mono_spinctrl_spincollection::selection, SPINTYPE_INTEGER, and gfx_mono_spinctrl::strings.
| void gfx_mono_spinctrl_spincollection_show | ( | struct gfx_mono_spinctrl_spincollection * | spinners | ) |
Show spincollection.
This function draws all the spinners in a spincollection to the screen, together with an OK button at the bottom. It also draws an indicator arrow in front of the top spinner.
| [in] | spinners | pointer to initialized spincollection to display |
References gfx_mono_spinctrl_spincollection::collection, gfx_mono_draw_filled_rect, GFX_MONO_LCD_HEIGHT, GFX_MONO_LCD_WIDTH, gfx_mono_spinctrl_draw(), gfx_mono_spinctrl_draw_button(), gfx_mono_spinctrl_draw_indicator(), GFX_PIXEL_CLR, i, gfx_mono_spinctrl::next, and gfx_mono_spinctrl_spincollection::number_of_spinners.
1.8.5