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,19 +1,70 @@
 #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)
     , _value(false)
 {
 }
 
-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,13 +112,39 @@ 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;
     if (isCurrent())
         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 @@ class BoolField : public Field {
     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,13 +137,35 @@ 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())
         return false;
     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 @@ class Field {
     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;