2.5 GFX Spinner/Spin Control Widget

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.

A spinner is a graphical control element with which a user may adjust a value in an adjoining text box by either clicking on an up or down arrow, causing the value in the text box to increase (if the up arrow is held down) or decrease (if the down arrow is held down).

Typical flow of an application using the spin-collection system:

  1. Define spinners.
  2. Initialize each spinners with gfx_mono_spinctrl_init.
  3. Define a spin-collection struct and initialize it with gfx_mono_spinctrl_spincollection_init.
  4. Add spinners to spin-collection with gfx_mono_spinctrl_spincollection_add_spinner.
  5. Draw spin-collection 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.

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 spin-collection, and can therefore not be used in two spin-collections at the same time.

As soon as input is received, inform the spin-collection 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 key-code:

  • GFX_MONO_SPINCTRL_KEYCODE_DOWN: Change selection to next spinner value or to next spinner, or OK button in a spin-collection.
  • GFX_MONO_SPINCTRL_KEYCODE_UP: Change selection to previous spinner value or to previous spinner, or OK button in a spin-collection.
  • GFX_MONO_SPINCTRL_KEYCODE_ENTER: Select spinner value or select spinner, or OK button in a spin-collection.
  • GFX_MONO_SPINCTRL_KEYCODE_BACK: Deselect spinner or cancel spin-collection application.

The value of the key-codes 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.

In this example, three buttons are used as input methods. Button 1 is used as UP button, button 2 is used as DOWN button, and button 3 is used as OK button. By pressing these buttons, it will return the GFX_MONO_SPINCTRL_KEYCODE_UP, GFX_MONO_SPINCTRL_KEYCODE_DOWN, and GFX_MONO_SPINCTRL_KEYCODE_ENTER respectively.

When navigation arrow is pointing to a spinner, pressing the OK button will enter the spinner value selection. By pressing the UP and DOWN buttons, values can be changed. In this example, one string spinner and two integer spinners are demonstrated. After all spinners' value are selected, move the arrow to "OK", press the OK (button 3) button, then the selected values will be displayed.