Documentation for FreetronicsLCD library

.gitignore

@@ -1 +1,2 @@
 backup
+*.swp

Form/Form.pde

@@ -47,8 +47,8 @@ void loop() {
   timeField.setValue(millis() / 1000);
 
   // Dispatch button events to the main form.
-  int button = lcd.getButton();
-  if (mainForm.dispatch(button) == FORM_CHANGED) {
+  int event = lcd.getButton();
+  if (mainForm.dispatch(event) == FORM_CHANGED) {
     if (mainForm.isCurrent(ledField)) {
       if (ledField.value())
         digitalWrite(STATUS_LED, HIGH);

doc/.gitignore

@@ -0,0 +1 @@
+html

doc/mainpage.dox

@@ -0,0 +1,6 @@
+/**
+\file mainpage.dox
+\mainpage
+
+Utility libraries for enhanced use of standard Arduino shields.
+*/

libraries/FreetronicsLCD/BoolField.cpp

@@ -1,5 +1,53 @@
 #include "BoolField.h"
 
+/**
+ * \class BoolField BoolField.h <BoolField.h>
+ * \brief Field that manages the input of a boolean value.
+ *
+ * BoolField is intended for field values that are modifiable by the user.
+ * Pressing one of Up, Down, or Select will toggle the field's current value.
+ *
+ * The following example creates a boolean field that shows the state
+ * of the status LED on D13.  When the LED is on (the default), the string
+ * "On" will be displayed on the LCD screen.  When the LED is off, the
+ * string "Off" will be displayed instead.
+ *
+ * \code
+ * Form mainForm(lcd);
+ * BoolField ledField(mainForm, "Status LED", "On", "Off", true);
+ * \endcode
+ *
+ * To actually toggle the LED, the application's main loop() function
+ * should contain the following code:
+ *
+ * \code
+ * int event = lcd.getButton();
+ * if (mainForm.dispatch(event) == FORM_CHANGED) {
+ *     if (mainForm.isCurrent(ledField)) {
+ *         if (ledField.value())
+ *             digitalWrite(STATUS_LED, HIGH);
+ *         else
+ *             digitalWrite(STATUS_LED, LOW);
+ *     }
+ * }
+ * \endcode
+ *
+ * Use TextField for read-only fields that report boolean values but
+ * which are not modifiable by the user.
+ *
+ * \sa Field, TextField
+ */
+
+/**
+ * \brief Constructs a new boolean field with a specific \a label.
+ *
+ * The field is initially not associated with a Form.  The field can be
+ * added to a form later using Form::addField().
+ *
+ * The initial value() will be false.
+ *
+ * \sa Form::addField()
+ */
 BoolField::BoolField(const String &label)
     : Field(label)
     , _printLen(0)
@@ -7,13 +55,16 @@ BoolField::BoolField(const String &label)
 {
 }
 
-BoolField::BoolField(Form &form, const String &label)
-    : Field(form, label)
-    , _printLen(0)
-    , _value(false)
-{
-}
-
+/**
+ * \brief Constructs a new boolean field with a specific \a label and
+ * attaches it to a \a form.
+ *
+ * The initial value() of the field is set to the parameter \a value.
+ * When value() is true, \a trueLabel will be displayed on the screen.
+ * When value() is false, \a falseLabel will be displayed on the screen.
+ *
+ * \sa value()
+ */
 BoolField::BoolField(Form &form, const String &label, const String &trueLabel, const String &falseLabel, bool value)
     : Field(form, label)
     , _trueLabel(trueLabel)
@@ -40,6 +91,18 @@ void BoolField::enterField(bool reverse)
     printValue();
 }
 
+/**
+ * \fn bool BoolField::value() const
+ * \brief Returns the current value of this field, true or false.
+ *
+ * \sa setValue()
+ */
+
+/**
+ * \brief Sets the current value of this field to \a value.
+ *
+ * \sa value()
+ */
 void BoolField::setValue(bool value)
 {
     if (value != _value) {
@@ -49,6 +112,19 @@ void BoolField::setValue(bool value)
     }
 }
 
+/**
+ * \fn const String &BoolField::trueLabel() const
+ * \brief Returns the string that is displayed when value() is true.
+ *
+ * \sa setTrueLabel(), falseLabel()
+ */
+
+/**
+ * \brief Sets the string that is displayed when value() is true to
+ * \a trueLabel.
+ *
+ * \sa trueLabel(), setFalseLabel()
+ */
 void BoolField::setTrueLabel(const String &trueLabel)
 {
     _trueLabel = trueLabel;
@@ -56,6 +132,19 @@ void BoolField::setTrueLabel(const String &trueLabel)
         printValue();
 }
 
+/**
+ * \fn const String &BoolField::falseLabel() const
+ * \brief Returns the string that is displayed when value() is false.
+ *
+ * \sa setFalseLabel(), trueLabel()
+ */
+
+/**
+ * \brief Sets the string that is displayed when value() is false to
+ * \a falseLabel.
+ *
+ * \sa falseLabel(), setTrueLabel()
+ */
 void BoolField::setFalseLabel(const String &falseLabel)
 {
     _falseLabel = falseLabel;

libraries/FreetronicsLCD/BoolField.h

@@ -6,7 +6,6 @@
 class BoolField : public Field {
 public:
     explicit BoolField(const String &label);
-    BoolField(Form &form, const String &label);
     BoolField(Form &form, const String &label, const String &trueLabel, const String &falseLabel, bool value);
 
     int dispatch(int event);
@@ -16,10 +15,10 @@ public:
     bool value() const { return _value; }
     void setValue(bool value);
 
-    String trueLabel() const { return _trueLabel; }
+    const String &trueLabel() const { return _trueLabel; }
     void setTrueLabel(const String &trueLabel);
 
-    String falseLabel() const { return _falseLabel; }
+    const String &falseLabel() const { return _falseLabel; }
     void setFalseLabel(const String &falseLabel);
 
 private:

libraries/FreetronicsLCD/Field.cpp

@@ -1,5 +1,20 @@
 #include "Field.h"
 
+/**
+ * \class Field Field.h <Field.h>
+ * \brief Manages a single data input/output field within a Form.
+ *
+ * \sa Form, BoolField, IntField, TextField, TimeField
+ */
+
+/**
+ * \brief Constructs a new field with a specific \a label.
+ *
+ * The field is initially not associated with a Form.  The field can be
+ * added to a form later using Form::addField().
+ *
+ * \sa Form::addField()
+ */
 Field::Field(const String &label)
     : _label(label)
     , _form(0)
@@ -8,6 +23,10 @@ Field::Field(const String &label)
 {
 }
 
+/**
+ * \brief Constructs a new field with a specific \a label and attaches
+ * it to a \a form.
+ */
 Field::Field(Form &form, const String &label)
     : _label(label)
     , _form(0)
@@ -17,31 +36,91 @@ Field::Field(Form &form, const String &label)
     form.addField(this);
 }
 
+/**
+ * \brief Destroys this field and removes it from its owning Form.
+ *
+ * \sa Form::removeField()
+ */
 Field::~Field()
 {
     if (_form)
         _form->removeField(this);
 }
 
+/**
+ * \fn Form *Field::form() const
+ * \brief Returns the Form that owns this field; null if not associated
+ * with a Form.
+ */
+
+/**
+ * \brief Dispatches \a event via this field.
+ *
+ * The \a event is usually obtained from FreetronicsLCD::getButton().
+ *
+ * Returns zero if the \a event has been handled and no further action
+ * is required.
+ *
+ * Returns FORM_CHANGED if the \a 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 \a 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.
+ *
+ * \sa Form::dispatch(), FreetronicsLCD::getButton()
+ */
 int Field::dispatch(int event)
 {
     // Nothing to do here.
     return -1;
 }
 
+/**
+ * \brief 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 \a 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().
+ *
+ * \sa exitField()
+ */
 void Field::enterField(bool reverse)
 {
-    // Print the label and then position the cursor on the second line.
-    // We assume that the screen has just been cleared.
     lcd()->print(_label);
-    lcd()->setCursor(0, 1);
 }
 
+/**
+ * \brief Exits the field due to form navigation.
+ *
+ * This function is typically called when the user presses Left and Right
+ * buttons to navigate from the field.
+ *
+ * \sa enterField()
+ */
 void Field::exitField()
 {
     // Nothing to do here.
 }
 
+/**
+ * \fn const String &Field::label() const
+ * \brief Returns the label to display in the first line of this field.
+ *
+ * \sa setLabel()
+ */
+
+/**
+ * \brief Sets the \a label to display in the first line of this field.
+ *
+ * \sa label()
+ */
 void Field::setLabel(const String &label)
 {
     if (isCurrent()) {
@@ -58,6 +137,13 @@ void Field::setLabel(const String &label)
     }
 }
 
+/**
+ * \brief Returns true if this field is the currently-displayed field in
+ * its owning form; false otherwise.
+ *
+ * This function should be called from property setters in subclasses to
+ * determine if the screen should be updated when a property is modified.
+ */
 bool Field::isCurrent() const
 {
     if (!_form->isVisible())
@@ -65,6 +151,21 @@ bool Field::isCurrent() const
     return _form->currentField() == this;
 }
 
+/**
+ * \fn LiquidCrystal *Field::lcd() const
+ * \brief Returns the LCD that this field is being drawn on.
+ */
+
+/**
+ * \brief Updates the cursor position after the label has been drawn
+ * by setLabel().
+ *
+ * The default implementation does nothing.  Subclasses that use an LCD
+ * cursor may override this to ensure that the cursor position stays
+ * valid after the label is modified.
+ *
+ * \sa setLabel()
+ */
 void Field::updateCursor()
 {
     // Nothing to do here.

libraries/FreetronicsLCD/Field.h

@@ -16,7 +16,7 @@ public:
     virtual void enterField(bool reverse);
     virtual void exitField();
 
-    String label() const { return _label; }
+    const String &label() const { return _label; }
     void setLabel(const String &label);
 
     bool isCurrent() const;

libraries/FreetronicsLCD/Form.cpp

@@ -1,6 +1,22 @@
 #include "Form.h"
 #include "Field.h"
 
+/**
+ * \class Form Form.h <Form.h>
+ * \brief Manager for a form containing data input/output fields.
+ */
+
+/**
+ * \brief Constructs a new form and associates it with \a lcd.
+ *
+ * This constructor is typically followed by calls to construct Field
+ * values for each of the fields on the form.  For example:
+ *
+ * \code
+ * Form mainForm(lcd);
+ * TextField welcomeField(mainForm, "Form example", "v1.0");
+ * \endcode
+ */
 Form::Form(LiquidCrystal &lcd)
     : _lcd(&lcd)
     , first(0)
@@ -9,6 +25,9 @@ Form::Form(LiquidCrystal &lcd)
 {
 }
 
+/**
+ * \brief Detaches all remaining fields and destroys this form.
+ */
 Form::~Form()
 {
     Field *field = first;
@@ -22,6 +41,34 @@ Form::~Form()
     }
 }
 
+/**
+ * \brief Dispatches \a event to the currently active field using
+ * Field::dispatch().
+ *
+ * The \a event is usually obtained from FreetronicsLCD::getButton().
+ *
+ * Returns zero if the \a event has been handled and no further action
+ * is required.
+ *
+ * Returns FORM_CHANGED if one of the fields on the form has changed value
+ * due to the \a event, perhaps requiring the application to take further
+ * action based on the new field value.  Use currentField() or isCurrent()
+ * to determine which field has changed.
+ *
+ * \code
+ * int event = lcd.getButton();
+ * if (mainForm.dispatch(event) == FORM_CHANGED) {
+ *     if (mainForm.isCurrent(volumeField)) {
+ *         // Adjust the volume to match the field.
+ *         setVolume(volumeField.value());
+ *     }
+ * }
+ * \endcode
+ *
+ * This function handles the Left and Right buttons to navigate between fields.
+ *
+ * \sa Field::dispatch(), FreetronicsLCD::getButton(), currentField(), isCurrent()
+ */
 int Form::dispatch(int event)
 {
     if (current) {
@@ -36,6 +83,11 @@ int Form::dispatch(int event)
     return 0;
 }
 
+/**
+ * \brief Changes to the next field in the "tab order".
+ *
+ * \sa prevField(), defaultField(), currentField()
+ */
 void Form::nextField()
 {
     Field *field = current;
@@ -48,6 +100,11 @@ void Form::nextField()
     setCurrentField(field);
 }
 
+/**
+ * \brief Changes to the previous field in the "tab order".
+ *
+ * \sa nextField(), defaultField(), currentField()
+ */
 void Form::prevField()
 {
     Field *field = current;
@@ -60,11 +117,24 @@ void Form::prevField()
     setCurrentField(field);
 }
 
+/**
+ * \brief Changes to default field (i.e., the first field).
+ *
+ * \sa nextField(), prevField(), currentField()
+ */
 void Form::defaultField()
 {
     setCurrentField(first);
 }
 
+/**
+ * \brief Adds \a field to this form.
+ *
+ * Usually this function is not required because the field's constructor
+ * will add the field to the form automatically.
+ *
+ * \sa removeField()
+ */
 void Form::addField(Field *field)
 {
     if (field->_form)
@@ -79,6 +149,14 @@ void Form::addField(Field *field)
     last = field;
 }
 
+/**
+ * \brief Removes \a field from this form.
+ *
+ * If \a field is the current field on-screen, then either the next or
+ * previous field will be made current.
+ *
+ * \sa addField()
+ */
 void Form::removeField(Field *field)
 {
     if (field->_form != this)
@@ -104,6 +182,24 @@ void Form::removeField(Field *field)
     field->prev = 0;
 }
 
+/**
+ * \fn Field *Form::currentField() const
+ * \brief Returns the current field that is displayed on-screen.
+ *
+ * Returns null if the form has no fields, or setCurrentField() explicitly
+ * set the current field to null.
+ *
+ * \sa setCurrentField(), isCurrent()
+ */
+
+/**
+ * \brief Sets the current \a field that is displayed on-screen.
+ *
+ * Use this function to programmatically force the form to display a
+ * specific field on-screen.
+ *
+ * \sa currentField(), isCurrent()
+ */
 void Form::setCurrentField(Field *field)
 {
     if (field && field->_form != this)
@@ -126,6 +222,28 @@ void Form::setCurrentField(Field *field)
     }
 }
 
+/**
+ * \fn bool Form::isCurrent(Field &field) const
+ * \brief Returns true if \a field is currently displayed on-screen, false otherwise.
+ *
+ * This function is typically called after dispatch() returns FORM_CHANGED
+ * to determine which field has changed.
+ *
+ * \sa currentField(), setCurrentField()
+ */
+
+/**
+ * \brief Shows the form, or does nothing if the form is already on-screen.
+ *
+ * When the form is shown, the screen will be cleared and the currentField()
+ * will be drawn.
+ *
+ * If the form was previously hidden, then the field that was previously
+ * current will be shown again.  Call defaultField() before show() to reset
+ * the form to show the first field instead.
+ *
+ * \sa hide(), isVisible(), defaultField()
+ */
 void Form::show()
 {
     if (!visible) {
@@ -138,6 +256,13 @@ void Form::show()
     }
 }
 
+/**
+ * \brief Hides the form, or does nothing if the form is not on-screen.
+ *
+ * The screen will be cleared to remove the contents of the current field.
+ *
+ * \sa show(), isVisible()
+ */
 void Form::hide()
 {
     if (visible) {
@@ -147,3 +272,10 @@ void Form::hide()
         _lcd->clear();
     }
 }
+
+/**
+ * \fn bool Form::isVisible() const
+ * \brief Returns true if the form is shown; false if the form is hidden.
+ *
+ * \sa show(), hide()
+ */

libraries/FreetronicsLCD/FreetronicsLCD.cpp

@@ -11,6 +11,80 @@
 #define LCD_BUTTON_LEFT_VALUE   505
 #define LCD_BUTTON_SELECT_VALUE 741
 
+/**
+ * \class FreetronicsLCD FreetronicsLCD.h <FreetronicsLCD.h>
+ * \brief Enhanced library for Freetronics 16x2 LCD shields
+ *
+ * This class extends the standard Arduino LiquidCrystal library with
+ * extra functionality for the Freetronics 16x2 LCD shield:
+ *
+ * http://www.freetronics.com/pages/16x2-lcd-shield-quickstart-guide
+ *
+ * The Freetronics LCD has an additional back light, which is turned
+ * on and off with the display() and noDisplay() functions.  The user
+ * can also call enableScreenSaver() to cause the display and back light
+ * to automatically turn off after a specific timeout.
+ *
+ * The Freetronics LCD also has 5 push buttons for Left, Right, Up, Down,
+ * and Select, to assist with the creation of interactive sketches.
+ * The user can call getButton() to get the current button state.
+ * One of the following values may be returned:
+ *
+ * \li LCD_BUTTON_NONE - No button has been pressed, or a button has been
+ * pressed but not yet released.
+ * \li LCD_BUTTON_LEFT - Left button was pressed.
+ * \li LCD_BUTTON_RIGHT - Right button was pressed.
+ * \li LCD_BUTTON_UP - Up button was pressed.
+ * \li LCD_BUTTON_DOWN - Down button was pressed.
+ * \li LCD_BUTTON_SELECT - Select button was pressed.
+ * \li LCD_BUTTON_LEFT_RELEASED - Left button was released.
+ * \li LCD_BUTTON_RIGHT_RELEASED - Right button was released.
+ * \li LCD_BUTTON_UP_RELEASED - Up button was released.
+ * \li LCD_BUTTON_DOWN_RELEASED - Down button was released.
+ * \li LCD_BUTTON_SELECT_RELEASED - Select button was released.
+ *
+ * For convenience, all RELEASED button codes are the negation of their
+ * pressed counterparts.  That is, LCD_BUTTON_LEFT_RELEASED == -LCD_BUTTON_LEFT.
+ * LCD_BUTTON_NONE is defined to be zero.  Thus, you can check if a
+ * generic button has been pressed with <tt>button &gt; 0</tt> and if a
+ * generic button has been released with <tt>button &lt; 0</tt>.
+ *
+ * \sa Form
+ */
+
+/**
+ * \fn FreetronicsLCD::FreetronicsLCD()
+ * \brief Initialize the Freetronics LCD display with the default
+ * pin assignment.
+ *
+ * The following example shows how to initialize the Freetronics
+ * LCD shield:
+ *
+ * \code
+ * FreetronicsLCD lcd;
+ * \endcode
+ */
+
+/**
+ * \fn FreetronicsLCD::FreetronicsLCD(uint8_t pin9)
+ * \brief Initialize the Freetronics LCD display for USBDroid.
+ *
+ * On the USBDroid, the D9 pin is used for USB Host functionality.
+ * Either the USB Host's use of D9 must be reassigned to another pin,
+ * or the Freetronics LCD shield must be modified.  The following Web
+ * page describes the modifications that are necessary:
+ * http://www.freetronics.com/pages/combining-the-lcd-keypad-shield-and-the-usbdroid
+ *
+ * If you choose to modify the LCD shield, then you must use this version
+ * of the constructor to initialize the shield, passing the alternative
+ * pin as the \a pin9 parameter.  Using the recommended pin from the above
+ * Web page of A1, you would initialize the LCD as follows:
+ *
+ * \code
+ * FreetronicsLCD lcd(A1);
+ * \endcode
+ */
+
 void FreetronicsLCD::init()
 {
     // The Freetronics display is 16x2.
@@ -32,6 +106,15 @@ void FreetronicsLCD::init()
     screenSaved = false;
 }
 
+/**
+ * \brief Turns on the display of text on the LCD and the back light.
+ *
+ * If the screen saver is active, then calling this function will
+ * deactivate the screen saver and reset the timeout.  Thus, this
+ * function can be called for force the screen to restore.
+ *
+ * \sa noDisplay(), enableScreenSaver()
+ */
 void FreetronicsLCD::display()
 {
     LiquidCrystal::display();
@@ -41,6 +124,13 @@ void FreetronicsLCD::display()
     lastRestore = millis();
 }
 
+/**
+ * \brief Turns off the display of text on the LCD and the back light.
+ *
+ * This function can be called to force the screen saver to activate.
+ *
+ * \sa display(), enableScreenSaver()
+ */
 void FreetronicsLCD::noDisplay()
 {
     LiquidCrystal::noDisplay();
@@ -48,6 +138,21 @@ void FreetronicsLCD::noDisplay()
     screenSaved = true;
 }
 
+/**
+ * \brief Enables the screen saver and causes it to activate after
+ * \a timeoutSecs of inactivity on the buttons.
+ *
+ * If \a timeoutSecs is less than or equal to zero, then the call
+ * is equivalent to calling disableScreenSaver().
+ *
+ * For the screen saver to work, the application must regularly call
+ * getButton() to fetch the LCD's button state even if no buttons
+ * are pressed.
+ *
+ * If the \a timeoutSecs parameter is not supplied, the default is 10 seconds.
+ *
+ * \sa disableScreenSaver(), display(), getButton(), isScreenSaved()
+ */
 void FreetronicsLCD::enableScreenSaver(int timeoutSecs)
 {
     if (timeoutSecs < 0)
@@ -57,12 +162,45 @@ void FreetronicsLCD::enableScreenSaver(int timeoutSecs)
     display();
 }
 
+/**
+ * \brief Disables the screen saver.
+ *
+ * \sa enableScreenSaver(), display(), isScreenSaved()
+ */
 void FreetronicsLCD::disableScreenSaver()
 {
     timeout = 0;
     display();
 }
 
+/**
+ * \fn bool FreetronicsLCD::isScreenSaved() const
+ * \brief Returns true if the screen has been saved; false otherwise.
+ *
+ * \sa enableScreenSaver()
+ */
+
+/**
+ * \brief Gets the next button press, release, or idle event.
+ *
+ * If no buttons are pressed, this function will return LCD_BUTTON_NONE.
+ *
+ * When a button is pressed, this function will return one of
+ * LCD_BUTTON_LEFT, LCD_BUTTON_RIGHT, LCD_BUTTON_UP, LCD_BUTTON_DOWN,
+ * or LCD_BUTTON_SELECT.  While the button is pressed, this function
+ * will return LCD_BUTTON_NONE until the button is released.  When the
+ * button is released, this function will return one of
+ * LCD_BUTTON_LEFT_RELEASED, LCD_BUTTON_RIGHT_RELEASED,
+ * LCD_BUTTON_UP_RELEAED, LCD_BUTTON_DOWN_RELEASED,
+ * or LCD_BUTTON_SELECT_RELEASED.
+ *
+ * If the screen saver is currently active, then it will be deactivated
+ * by this function whenever a button is pressed.  In that case, the function
+ * will "eat" the button press and return LCD_BUTTON_NONE.  The scrren saver
+ * can also be deactivated under program control by calling display()
+ *
+ * \sa enableScreenSaver(), display(), Form::dispatch()
+ */
 int FreetronicsLCD::getButton()
 {
     int value = analogRead(LCD_BUTTON_PIN);

libraries/FreetronicsLCD/FreetronicsLCD.h

@@ -26,34 +26,15 @@
 class FreetronicsLCD : public LiquidCrystal {
 public:
     FreetronicsLCD() : LiquidCrystal(8, 9, 4, 5, 6, 7) { init(); }
-
-    // For USBDroid where D9 needs to be reassigned to some other pin.
     FreetronicsLCD(uint8_t pin9) : LiquidCrystal(8, pin9, 4, 5, 6, 7) { init(); }
 
-    // Turn on the display, including the back light and the text.
-    // This will also reset the screen saver timeout.
     void display();
-
-    // Turn off the display, including the back light and the text,
-    // effectively forcing the screen saver to activate immediately.
     void noDisplay();
 
-    // Enable the screen saver and activate it after timeout seconds
-    // of inactivity on the buttons.  Note: the screen saver is activated
-    // during the call to getButton() so it must be polled regularly.
     void enableScreenSaver(int timeoutSecs = 10);
-
-    // Disable the screen saver and turn the screen back on.
     void disableScreenSaver();
-
-    // Determine if the screen saver is active.
     bool isScreenSaved() const { return screenSaved; }
 
-    // Get the next button event, or LCD_BUTTON_NONE if no change
-    // since the last event.  If the screen saver is active, then
-    // pressing a button will disable the screen saver and return
-    // LCD_BUTTON_NONE as the button code.  Thus, any button can
-    // be used to wake up the screen.
     int getButton();
 
 private:

libraries/FreetronicsLCD/IntField.cpp

@@ -1,5 +1,49 @@
 #include "IntField.h"
 
+/**
+ * \class IntField IntField.h <IntField.h>
+ * \brief Field that manages the input of an integer value.
+ *
+ * IntField is intended for field values that are modifiable by the user.
+ * Pressing Up adds stepValue() to the current value and pressing Down
+ * subtracts stepValue() from the current value.  The value is clamped to
+ * the range minValue() to maxValue().
+ *
+ * The following example creates an integer field with the label "Iterations",
+ * that ranges between 1 and 5, with a stepValue() of 1, and an initial
+ * default value() of 2:
+ *
+ * \code
+ * Form mainForm(lcd);
+ * IntField iterField(mainForm, "Iterations", 1, 5, 1, 2);
+ * \endcode
+ *
+ * IntField can be configured to show a suffix() on the screen after the
+ * integer value().  This is intended for communicating the units in which
+ * the value is expressed.  For example:
+ *
+ * \code
+ * IntField volumeField(mainForm, "Volume", 0, 100, 5, 85, "%");
+ * IntField speedField(mainForm, "Speed", 0, 2000, 15, 450, " rpm");
+ * \endcode
+ *
+ * Use TextField for read-only fields that report integer values but
+ * which are not modifiable by the user.
+ *
+ * \sa Field, TextField
+ */
+
+/**
+ * \brief Constructs a new integer field with a specific \a label.
+ *
+ * The field is initially not associated with a Form.  The field can be
+ * added to a form later using Form::addField().
+ *
+ * Initially, value() is 0, minValue() is 0, maxValue() is 100,
+ * stepValue() is 1, and suffix() is an empty string.
+ *
+ * \sa Form::addField()
+ */
 IntField::IntField(const String &label)
     : Field(label)
     , _minValue(0)
@@ -10,37 +54,28 @@ IntField::IntField(const String &label)
 {
 }
 
-IntField::IntField(Form &form, const String &label)
-    : Field(form, label)
-    , _minValue(0)
-    , _maxValue(100)
-    , _stepValue(1)
-    , _value(0)
-    , _printLen(0)
-{
-}
-
-IntField::IntField(Form &form, const String &label, int minValue, int maxValue, int value)
+/**
+ * \brief Constructs a new integer field with a specific \a label,
+ * \a minValue, \a maxValue, \a stepValue, and \a value, and attaches
+ * it to a \a form.
+ *
+ * The suffix() is initially set to an empty string.
+ */
+IntField::IntField(Form &form, const String &label, int minValue, int maxValue, int stepValue, int value)
     : Field(form, label)
     , _minValue(minValue)
     , _maxValue(maxValue)
-    , _stepValue(1)
+    , _stepValue(stepValue)
     , _value(value)
     , _printLen(0)
 {
 }
 
-IntField::IntField(Form &form, const String &label, int minValue, int maxValue, int value, const String &suffix)
-    : Field(form, label)
-    , _minValue(minValue)
-    , _maxValue(maxValue)
-    , _stepValue(1)
-    , _value(value)
-    , _printLen(0)
-    , _suffix(suffix)
-{
-}
-
+/**
+ * \brief Constructs a new integer field with a specific \a label,
+ * \a minValue, \a maxValue, \a stepValue, \a value, and \a suffix
+ * and attaches it to a \a form.
+ */
 IntField::IntField(Form &form, const String &label, int minValue, int maxValue, int stepValue, int value, const String &suffix)
     : Field(form, label)
     , _minValue(minValue)
@@ -70,6 +105,72 @@ void IntField::enterField(bool reverse)
     printValue();
 }
 
+/**
+ * \fn int IntField::minValue() const
+ * \brief Returns the minimum value for the input field.
+ *
+ * \sa setMinValue(), maxValue(), stepValue(), value()
+ */
+
+/**
+ * \fn void IntField::setMinValue(int value)
+ * \brief Sets the minimum \a value for the input field.
+ *
+ * The new minimum \a value will be used to clamp the field's value the
+ * next time setValue() is called.
+ *
+ * \sa minValue(), setMaxValue(), setStepValue(), setValue()
+ */
+
+/**
+ * \fn int IntField::maxValue() const
+ * \brief Returns the maximum value for the input field.
+ *
+ * \sa setMaxValue(), minValue(), stepValue(), value()
+ */
+
+/**
+ * \fn void IntField::setMaxValue(int value)
+ * \brief Sets the maximum \a value for the input field.
+ *
+ * The new maximum \a value will be used to clamp the field's value the
+ * next time setValue() is called.
+ *
+ * \sa maxValue(), setMinValue(), setStepValue(), setValue()
+ */
+
+/**
+ * \fn int IntField::stepValue() const
+ * \brief Returns the step value to use when increasing or decreasing the
+ * value() due to Up and Down button presses.
+ *
+ * \sa setStepValue(), minValue(), maxValue(), value()
+ */
+
+/**
+ * \fn void IntField::setStepValue(int value)
+ * \brief Sets the step value \a value to use when increasing or decreasing
+ * the value() due to Up and Down button presses.
+ *
+ * \sa stepValue(), setMinValue(), setMaxValue(), setValue()
+ */
+
+/**
+ * \fn int IntField::value() const
+ * \brief Returns the current value of this field.
+ *
+ * \sa setValue(), minValue(), maxValue(), stepValue()
+ */
+
+/**
+ * \fn void IntField::setValue(int value)
+ * \brief Sets the current \a value of this field.
+ *
+ * The \a value will be clamped to the range defined by minValue()
+ * and maxValue().
+ *
+ * \sa value(), setMinValue(), setMaxValue(), setStepValue()
+ */
 void IntField::setValue(int value)
 {
     if (value < _minValue)
@@ -83,6 +184,26 @@ void IntField::setValue(int value)
     }
 }
 
+/**
+ * \fn const String &IntField::suffix() const
+ * \brief Returns the suffix string to be displayed after the field's value.
+ *
+ * \sa setSuffix()
+ */
+
+/**
+ * \brief Sets the \a suffix string to be displayed after the field's value.
+ *
+ * Suffixes are typically used to indicate the units that the value() is
+ * expressed in.  For example:
+ *
+ * \code
+ * field.setSuffix("%");
+ * field.setSuffix(" rpm");
+ * \endcode
+ *
+ * \sa suffix()
+ */
 void IntField::setSuffix(const String &suffix)
 {
     _suffix = suffix;

libraries/FreetronicsLCD/IntField.h

@@ -6,9 +6,7 @@
 class IntField : public Field {
 public:
     explicit IntField(const String &label);
-    IntField(Form &form, const String &label);
-    IntField(Form &form, const String &label, int minValue, int maxValue, int value);
-    IntField(Form &form, const String &label, int minValue, int maxValue, int value, const String &suffix);
+    IntField(Form &form, const String &label, int minValue, int maxValue, int stepValue, int value);
     IntField(Form &form, const String &label, int minValue, int maxValue, int stepValue, int value, const String &suffix);
 
     int dispatch(int event);
@@ -27,7 +25,7 @@ public:
     int value() const { return _value; }
     void setValue(int value);
 
-    String suffix() const { return _suffix; }
+    const String &suffix() const { return _suffix; }
     void setSuffix(const String &suffix);
 
 private:

libraries/FreetronicsLCD/TextField.cpp

@@ -1,15 +1,55 @@
 #include "TextField.h"
 
+/**
+ * \class TextField TextField.h <TextField.h>
+ * \brief Field that displays a read-only text value.
+ *
+ * This following example displays a text field with the label
+ * "Form example" and a value() of "v1.0".
+ *
+ * \code
+ * Form mainForm(lcd);
+ * TextField welcomeField(mainForm, "Form example", "v1.0");
+ * \endcode
+ *
+ * As well as static messages, TextField can be used to display read-only
+ * information that is computed at runtime:
+ *
+ * \code
+ * TextField timeField(mainForm, "Time since reset", "0");
+ *
+ * void loop() {
+ *     timeField.setValue(millis() / 1000);
+ *     mainForm.dispatch(lcd.getButton());
+ * }
+ * \endcode
+ *
+ * For writable fields, use BoolField, IntField, or TimeField.
+ *
+ * \sa Field
+ */
+
+/**
+ * \brief Constructs a new text field with a specific \a label.
+ *
+ * The field is initially not associated with a Form.  The field can be
+ * added to a form later using Form::addField().
+ *
+ * The initial value() will be the empty string.
+ *
+ * \sa Form::addField()
+ */
 TextField::TextField(const String &label)
     : Field(label)
 {
 }
 
-TextField::TextField(Form &form, const String &label)
-    : Field(form, label)
-{
-}
-
+/**
+ * \brief Constructs a new text field with a specific \a label and \a value
+ * attaches it to a \a form.
+ *
+ * \sa value()
+ */
 TextField::TextField(Form &form, const String &label, const String &value)
     : Field(form, label)
     , _value(value)
@@ -19,9 +59,22 @@ TextField::TextField(Form &form, const String &label, const String &value)
 void TextField::enterField(bool reverse)
 {
     Field::enterField(reverse);
+    lcd()->setCursor(0, 1);
     lcd()->print(_value);
 }
 
+/**
+ * \fn const String &TextField::value() const
+ * \brief Returns the text value that is currently displayed by this field.
+ *
+ * \sa setValue()
+ */
+
+/**
+ * \brief Sets the text \a value that is displayed by this field.
+ *
+ * \sa value()
+ */
 void TextField::setValue(const String &value)
 {
     if (isCurrent()) {

libraries/FreetronicsLCD/TextField.h

@@ -6,12 +6,11 @@
 class TextField : public Field {
 public:
     explicit TextField(const String &label);
-    TextField(Form &form, const String &label);
     TextField(Form &form, const String &label, const String &value);
 
     void enterField(bool reverse);
 
-    String value() const { return _value; }
+    const String &value() const { return _value; }
     void setValue(const String &value);
 
 private:

libraries/FreetronicsLCD/TimeField.cpp

@@ -1,11 +1,58 @@
 #include "TimeField.h"
 
+/**
+ * \class TimeField TimeField.h <TimeField.h>
+ * \brief Field that manages the display and editing of a time value.
+ *
+ * TimeField is suitable for displaying wall clock time in 24-hour format,
+ * or for displaying timeouts and durations in seconds.  Times are specified
+ * in seconds as an <tt>unsigned long</tt> value.  They are displayed
+ * as <tt>HH:MM:SS</tt>, for hours, minutes, and seconds.
+ *
+ * The time field can be either read-only or read-write.  When read-write,
+ * the Up, Down, Left, and Right buttons can be used to modify the hour,
+ * minute, and second components of the time value.
+ *
+ * The following example displays the number of hours, minutes, and seconds
+ * since the device was reset, wrapping around after 24 hours:
+ *
+ * \code
+ * Form mainForm(lcd);
+ * TimeField timeField(mainForm, "Time since reset", 24, TIMEFIELD_READ_ONLY);
+ *
+ * void loop() {
+ *     timeField.setValue(millis() / 1000);
+ *     mainForm.dispatch(lcd.getButton());
+ * }
+ * \endcode
+ *
+ * A read-write field can be used to ask the user for the duration of an
+ * application count-down timer:
+ *
+ * \code
+ * TimeField durationField(mainForm, "Timer duration", 24, TIMEFIELD_READ_WRITE);
+ * \endcode
+ *
+ * \sa Field
+ */
+
 #define EDIT_HOUR           0
 #define EDIT_MINUTE_TENS    1
 #define EDIT_MINUTE         2
 #define EDIT_SECOND_TENS    3
 #define EDIT_SECOND         4
 
+/**
+ * \brief Constructs a new time field with a specific \a label.
+ *
+ * The field is initially not associated with a Form.  The field can be
+ * added to a form later using Form::addField().
+ *
+ * Initially value() is 0, maxHours() is 24, and isReadOnly() is
+ * TIMEFIELD_READ_WRITE.
+ *
+ * \sa Form::addField()
+ */
 TimeField::TimeField(const String &label)
     : Field(label)
     , _value(0)
@@ -16,16 +63,19 @@ TimeField::TimeField(const String &label)
 {
 }
 
-TimeField::TimeField(Form &form, const String &label)
-    : Field(form, label)
-    , _value(0)
-    , _maxHours(24)
-    , _printLen(0)
-    , _readOnly(false)
-    , editField(EDIT_HOUR)
-{
-}
-
+/**
+ * \brief Constructs a new boolean field with a specific \a label and
+ * attaches it to a \a form.
+ *
+ * The initial value() of the field will be 0.  The value() will be limited
+ * to be less than \a maxHours * 60 * 60 seconds.
+ *
+ * If \a readOnly is TIMEFIELD_READ_ONLY, then the field will display times
+ * but not allow them to be modified by the user.  If \a readOnly is
+ * TIMEFIELD_READ_WRITE, then the field will modifiable by the user.
+ *
+ * \sa value()
+ */
 TimeField::TimeField(Form &form, const String &label, int maxHours, bool readOnly)
     : Field(form, label)
     , _value(0)
@@ -133,6 +183,21 @@ void TimeField::exitField()
     Field::exitField();
 }
 
+/**
+ * \fn unsigned long TimeField::value() const
+ * \brief Returns the current value of this time field, in seconds.
+ *
+ * \sa setValue()
+ */
+
+/**
+ * \brief Sets the \a value of this time field, in seconds.
+ *
+ * If \a value is greater than or equal to maxHours() * 60 * 60,
+ * then it will be wrapped around to fall within the valid range.
+ *
+ * \sa value(), maxHours()
+ */
 void TimeField::setValue(unsigned long value)
 {
     unsigned long maxSecs = ((unsigned long)_maxHours) * 60 * 60;
@@ -144,6 +209,36 @@ void TimeField::setValue(unsigned long value)
     }
 }
 
+/**
+ * \fn int TimeField::maxHours() const
+ * \brief Returns the maximum number of hours before the field wraps around.
+ *
+ * \sa setMaxHours(), setValue()
+ */
+
+/**
+ * \fn void TimeField::setMaxHours(int maxHours)
+ * \brief Sets the maximum number of hours before the field wraps around
+ * to \a maxHours.
+ *
+ * \sa maxHours(), setValue()
+ */
+
+/**
+ * \fn bool TimeField::readOnly() const
+ * \brief Returns TIMEFIELD_READ_ONLY (true) or TIMEFIELD_READ_WRITE (false).
+ *
+ * \sa setReadOnly()
+ */
+
+/**
+ * \brief Sets the read-only state of this field to \a value.
+ *
+ * The \a value should be one of TIMEFIELD_READ_ONLY (true) or
+ * TIMEFIELD_READ_WRITE (false).  Use of the named constants is recommended.
+ *
+ * \sa readOnly()
+ */
 void TimeField::setReadOnly(bool value)
 {
     if (_readOnly != value) {

libraries/FreetronicsLCD/TimeField.h

@@ -9,7 +9,6 @@
 class TimeField : public Field {
 public:
     explicit TimeField(const String &label);
-    TimeField(Form &form, const String &label);
     TimeField(Form &form, const String &label, int maxHours, bool readOnly);
 
     int dispatch(int event);
@@ -23,7 +22,7 @@ public:
     int maxHours() const { return _maxHours; }
     void setMaxHours(int maxHours) { _maxHours = maxHours; }
 
-    bool isReadOnly() const { return _readOnly; }
+    bool readOnly() const { return _readOnly; }
     void setReadOnly(bool value);
 
 private:

libraries/FreetronicsLCD/examples/Form/Form.pde

@@ -47,8 +47,8 @@ void loop() {
   timeField.setValue(millis() / 1000);
 
   // Dispatch button events to the main form.
-  int button = lcd.getButton();
-  if (mainForm.dispatch(button) == FORM_CHANGED) {
+  int event = lcd.getButton();
+  if (mainForm.dispatch(event) == FORM_CHANGED) {
     if (mainForm.isCurrent(ledField)) {
       if (ledField.value())
         digitalWrite(STATUS_LED, HIGH);