Document LCD examples

doc/Doxyfile

@@ -668,7 +668,7 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see
 # the \include command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = ../libraries
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp

doc/lcd-form.dox

@@ -0,0 +1,99 @@
+/*
+ * 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
+*/

doc/lcd-helloworld.dox

@@ -0,0 +1,83 @@
+/*
+ * 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-helloworld.dox
+\page lcd_hello_world Hello World for Freetronics LCD
+
+The FreetronicsLCD class provides an enhanced version of the standard
+Arduino <a href="http://arduino.cc/en/Reference/LiquidCrystal">LiquidCrystal</a>
+library that supports the additional features of the
+<a href="http://www.freetronics.com/pages/16x2-lcd-shield-quickstart-guide">Freetronics LCD</a> shield;
+namely the back light and the Up, Down, Left, Right, and Select buttons.
+
+This tutorial explains how to use the FreetronicsLCD class to perform
+basic text output and to use the enhanced shield features.  We start by
+including the library and initializing it:
+
+\dontinclude FreetronicsLCD/examples/HelloWorld/HelloWorld.pde
+\skip FreetronicsLCD.h
+\until lcd
+
+Unlike the LiquidCrystal library we don't normally need to specify the pin
+assignments for this shield.  The one exception is when the shield is used
+with the USBDroid and the D9 pin is reassigned as described on
+<a href="http://www.freetronics.com/pages/combining-the-lcd-keypad-shield-and-the-usbdroid">this page</a>.  In that case, the initialization sequence
+would look something like this instead:
+
+\code
+FreetronicsLCD lcd(A1);
+\endcode
+
+The next step is to enable the screen saver and print some text
+in the \c setup function:
+
+\dontinclude FreetronicsLCD/examples/HelloWorld/HelloWorld.pde
+\skip setup()
+\until }
+
+The screen saver is a built-in feature of the FreetronicsLCD class that
+turns off the display and the back light after a specific timeout
+(the default is 10 seconds).  Pressing any of the keys on the shield
+or calling FreetronicsLCD::display() will wake up the screen again.
+
+In the program's \c loop function we print the number of seconds
+since startup to the second line of the LCD display:
+
+\dontinclude FreetronicsLCD/examples/HelloWorld/HelloWorld.pde
+\skip loop()
+\until millis()
+
+We then print the name of the button that is currently pressed:
+
+\dontinclude FreetronicsLCD/examples/HelloWorld/HelloWorld.pde
+\skip setCursor(8, 1)
+\until }
+
+The FreetronicsLCD::getButton() function returns the key that has
+been pressed or released, or LCD_BUTTON_NONE if no key has been
+pressed or released this time through the loop.
+
+The full source code for the example follows:
+
+\include FreetronicsLCD/examples/HelloWorld/HelloWorld.pde
+*/

doc/mainpage.dox

@@ -1,6 +1,38 @@
+/*
+ * 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 mainpage.dox
 \mainpage
 
-Utility libraries for enhanced use of standard Arduino shields.
+Utility libraries for enhanced use of standard Arduino main boards
+and shields.
+
+\section main_FreeTronics Freetronics LCD Shield
+
+\li FreetronicsLCD class to manage the extended features of the Freetronics
+LCD shield.
+\li Form and Field classes to build simple property sheet UI's on LCD displays.
+\li \ref lcd_hello_world "Hello World" example for the Freetronics LCD shield.
+\li \ref lcd_form "Form" example for LCD displays.
+
 */

libraries/FreetronicsLCD/Form.cpp

@@ -26,6 +26,9 @@
 /**
  * \class Form Form.h <Form.h>
  * \brief Manager for a form containing data input/output fields.
+ *
+ * See the \ref lcd_form "Form example" for more information on
+ * creating an application that uses forms and fields.
  */
 
 /**

libraries/FreetronicsLCD/FreetronicsLCD.cpp

@@ -71,6 +71,9 @@
  * 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>.
  *
+ * See the \ref lcd_hello_world "Hello World" example for more
+ * information on using the FreetronicsLCD class.
+ *
  * \sa Form
  */
 

libraries/FreetronicsLCD/examples/HelloWorld/HelloWorld.pde

@@ -8,10 +8,7 @@ http://www.freetronics.com/pages/16x2-lcd-shield-quickstart-guide
 This example is placed into the public domain.
 */
 
-// include the library code:
 #include <FreetronicsLCD.h>
-
-// initialize the library
 FreetronicsLCD lcd;
 
 // Note: if you are using the USBDroid and have reassigned pin D9 on the LCD shield to some
@@ -20,22 +17,14 @@ FreetronicsLCD lcd;
 // See also: http://www.freetronics.com/pages/combining-the-lcd-keypad-shield-and-the-usbdroid
 
 void setup() {
-  // Enable the screen saver, which will automatically blank the screen after 10 seconds.
-  // The screen will wake up again when a button is pressed or lcd.display() is called.
   lcd.enableScreenSaver();
-  
-  // Print a message to the LCD.
   lcd.print("hello, world!");
 }
 
 void loop() {
-  // set the cursor to column 0, line 1
-  // (note: line 1 is the second row, since counting begins with 0):
   lcd.setCursor(0, 1);
-  // print the number of seconds since reset:
-  lcd.print(millis()/1000);
+  lcd.print(millis() / 1000);
 
-  // print the name of the button that is currently pressed  
   lcd.setCursor(8, 1);
   int button = lcd.getButton();
   if (button == LCD_BUTTON_LEFT)