Field that manages selection from a static list of items. More...

#include <ListField.h>

Inheritance diagram for ListField:

Public Member Functions
	ListField (const String &label)
	Constructs a new list field with a specific label. More...

	ListField (Form &form, const String &label, ListItems items, int value=0)
	Constructs a new list field with a specific label, list of items, and value, and attaches it to a form.

int	dispatch (int event)
	Dispatches event via this field. More...

void	enterField (bool reverse)
	Enters the field due to form navigation. More...

ListItems	items () const
	Returns the array of items in this list. More...

void	setItems (ListItems items)
	Sets the array of items for this list. More...

int	value () const
	Returns the value of this list; i.e. the index within items() of the selected item. More...

void	setValue (int value)
	Sets the value of this list; i.e. the index within items() of the selected item. More...

Public Member Functions inherited from Field
	Field (const String &label)
	Constructs a new field with a specific label. More...

	Field (Form &form, const String &label)
	Constructs a new field with a specific label and attaches it to a form.

	~Field ()
	Destroys this field and removes it from its owning Form. More...

Form *	form () const
	Returns the Form that owns this field; null if not associated with a Form.

virtual void	exitField ()
	Exits the field due to form navigation. More...

const String &	label () const
	Returns the label to display in the first line of this field. More...

void	setLabel (const String &label)
	Sets the label to display in the first line of this field. More...

bool	isCurrent () const
	Returns true if this field is the currently-displayed field in its owning form; false otherwise. More...

Additional Inherited Members
Protected Member Functions inherited from Field
LiquidCrystal *	lcd () const
	Returns the LCD that this field is being drawn on.

virtual void	updateCursor ()
	Updates the cursor position after the label has been drawn by setLabel(). More...

Detailed Description

Field that manages selection from a static list of items.

ListField is intended for selecting an element from a list of items. Each items is represented by a string within program memory, with the list terminated by null. For example:

const char item_Eggs[] PROGMEM = "Eggs";
const char item_Cheese[] PROGMEM = "Cheese";
const char item_Pumpkin[] PROGMEM = "Pumpkin";
ListItem const ingredients[] PROGMEM = {
   item_Eggs,
   item_Cheese,
   item_Pumpkin,
   0
};
Form mainForm(lcd);
ListField ingredient(mainForm, "Select ingredient", ingredients);

If there are only two items in the list, then BoolField can be used instead.

See Also: Field, BoolField

Definition at line 32 of file ListField.h.

Constructor & Destructor Documentation

ListField::ListField ( const String & label )

explicit

Constructs a new list field with a specific label.

The field is initially not associated with a Form. The field can be added to a form later using Form::addField().

Initially, items() is null and value() is -1.

See Also: Form::addField()

Definition at line 64 of file ListField.cpp.

Member Function Documentation

int ListField::dispatch ( int event )

virtual

Dispatches event via this field.

The event is usually obtained from LCD::getButton().

Returns zero if the event has been handled and no further action is required.

Returns FORM_CHANGED if the event has changed the value of this field in a manner that may require the application to take further action based on the new field value.

Returns -1 if the event is not handled by this field, and should be handled by the Form itself (particularly for Left and Right buttons). The default implementation returns -1 for all events.

See Also: Form::dispatch(), LCD::getButton()

Reimplemented from Field.

Definition at line 87 of file ListField.cpp.

void ListField::enterField ( bool reverse )

virtual

Enters the field due to form navigation.

This function is typically called when the user presses Left and Right buttons to navigate to the field. If reverse is true, then navigation was due to the Left button being pressed.

This function can assume that the display has been cleared and the cursor is positioned at (0, 0).

The default implementation prints the label().

See Also: exitField()

Reimplemented from Field.

Definition at line 105 of file ListField.cpp.

ListItems ListField::items ( ) const

inline

Returns the array of items in this list.

See Also: setItems()

Definition at line 41 of file ListField.h.

void ListField::setItems ( ListItems items )

Sets the array of items for this list.

The items must be stored within program memory and terminated by null; for example:

const char item_Eggs[] PROGMEM = "Eggs";
const char item_Cheese[] PROGMEM = "Cheese";
const char item_Pumpkin[] PROGMEM = "Pumpkin";
ListItem const ingredients[] PROGMEM = {
   item_Eggs,
   item_Cheese,
   item_Pumpkin,
   0
};
list.setItems(ingredients);