Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Spinner widget for monochrome graphical displays

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.

Note
The spinners will be linked together when added to a spincollection, and can therefore not be used in two spincollections at the same time.

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
#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
#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().

Enum to specify what kind of data spinner should spin.

Enum to specify what kind of data spinner should spin.

Enumerator
SPINTYPE_STRING 
SPINTYPE_INTEGER 

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.

Parameters
[in]spinnerpointer to initialized gfx_mono_spinctrl struct
[in]redrawtrue 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.

Parameters
[out]spinnerpointer to initialized gfx_mono_spinctrl struct
[in]datatypetyper of spinner, integer or string
[in]titletitle of spinner
[in]datapointer to progmem string array if datatype is string. NULL if datatype is integer.
[in]lower_limitlower limit and start value of spinner's data
[in]upper_limitupper limit of spinner's data
[in]yy 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.

Parameters
[in]spinnerpointer to initialized spinner.
[in]keycodekeycode to process
Return values
selectedselected spinner value
GFX_MONO_SPINCTRL_EVENT_IDLEspinner spinning
GFX_MONO_SPINCTRL_EVENT_BACKspinner 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".

Parameters
[in]spinnerpointer to initialized gfx_mono_spinctrl struct to add to collection
[in]spinnerspointer 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.

Parameters
[out]collectionpointer 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.

Parameters
[in]spinnerspointer to initialized gfx_mono_spinctrl_spincollection
[in]keycodekeycode to process
[in]resultsarray to store results from the spinners, must be of same length as number of spinners
Return values
GFX_MONO_SPINCTRL_EVENT_FINISHuser pressed ok button
GFX_MONO_SPINCTRL_EVENT_BACKuser cancelled
GFX_MONO_SPINCTRL_EVENT_IDLEuser 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.

Parameters
[in]spinnerspointer 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.