/*
 * Copyright (C) 2012 Southern Storm Software, Pty Ltd.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

/**
\file lcd-form.dox
\page lcd_form Form example for LCD displays

The Form and Field classes simplify the process of building user interfaces
for Arduino projects that use a <a href="http://www.freetronics.com/pages/16x2-lcd-shield-quickstart-guide">Freetronics LCD</a> shield.  That shield has a
16x2 LCD display and five buttons for Up, Down, Left, Right, and Select.

The user interface is organised as a "form" which consists of one or more
"fields" that display or modify a single program parameter.  The Left and
Right buttons are used to navigate between fields, and the Up and Down
buttons are used to modify the value of the currently-displayed field.

We start by including the classes from the library that we will need:

\dontinclude FreetronicsLCD/examples/Form/Form.pde
\skip FreetronicsLCD.h
\until BoolField.h

Next, we initialize the LCD display, create the main form, and populate
it with fields:

\dontinclude FreetronicsLCD/examples/Form/Form.pde
\skip lcd;
\until lcd;
\skip mainForm
\until durationField

Each field has a specific type, which may be one of the following classes:

\li BoolField displays a boolean on/off value with the Up, Down, or Select
buttons used to toggle its state.
\li IntField displays an integer value within a specified range, with the
Up and Down buttons used to modify the value.
\li TextField displays a read-only value, which is typically used for
status messages and program results.
\li TimeField displays a time in hours, minutes, and seconds.  The field may
be either read-only or writable.  Writable time fields can be modified with
the Up, Down, Left, and Right buttons to select a specific duration.

Returning to our example, the above code creates the following fields:

\li \c welcomeField to display the program's name and version.
\li \c timeField to display the number of seconds since reset, wrapping around
after 24 hours.  This field is read-only.
\li \c volumeField which displays a volume between 0 and 100, with an Up/Down
step of 5, and a suffix of "%".
\li \c ledField which displays the current boolean state of the status LED on
D13; the LED will change state when the user toggles the field's value.
\li \c durationField which displays a read-write time field for selecting a
duration between 0 and 24 hours.

Now that we have defined our form, we need to initialize the program and
show it for the first time:

\dontinclude FreetronicsLCD/examples/Form/Form.pde
\skip STATUS_LED
\until }

An application can have multiple forms, but only one can be shown at any
given time.  To switch to another form, call Form::hide() on the old
form and Form::show() on the new form.

All that remains is to define our application's \c loop function which
retrieves button events from FreetronicsLCD::getButton() and dispatches them
to the form:

\dontinclude FreetronicsLCD/examples/Form/Form.pde
\skip loop()
\until }
\until }
\until }

The full source code for the example follows:

\include FreetronicsLCD/examples/Form/Form.pde
*/