diff --git a/doc/Doxyfile b/doc/Doxyfile index 6ef89ddd..c884ae54 100644 --- a/doc/Doxyfile +++ b/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 diff --git a/doc/lcd-form.dox b/doc/lcd-form.dox new file mode 100644 index 00000000..f3e873fa --- /dev/null +++ b/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 Freetronics LCD 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 +*/ diff --git a/doc/lcd-helloworld.dox b/doc/lcd-helloworld.dox new file mode 100644 index 00000000..cfd40ed2 --- /dev/null +++ b/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 LiquidCrystal +library that supports the additional features of the +Freetronics LCD 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 +this page. 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 +*/ diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 1f1e235d..204a7ab1 100644 --- a/doc/mainpage.dox +++ b/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. + */ diff --git a/libraries/FreetronicsLCD/Form.cpp b/libraries/FreetronicsLCD/Form.cpp index e0f897b3..0087d81c 100644 --- a/libraries/FreetronicsLCD/Form.cpp +++ b/libraries/FreetronicsLCD/Form.cpp @@ -26,6 +26,9 @@ /** * \class Form 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. */ /** diff --git a/libraries/FreetronicsLCD/FreetronicsLCD.cpp b/libraries/FreetronicsLCD/FreetronicsLCD.cpp index a526fdb1..4fb86fae 100644 --- a/libraries/FreetronicsLCD/FreetronicsLCD.cpp +++ b/libraries/FreetronicsLCD/FreetronicsLCD.cpp @@ -71,6 +71,9 @@ * generic button has been pressed with button > 0 and if a * generic button has been released with button < 0. * + * See the \ref lcd_hello_world "Hello World" example for more + * information on using the FreetronicsLCD class. + * * \sa Form */ diff --git a/libraries/FreetronicsLCD/examples/HelloWorld/HelloWorld.pde b/libraries/FreetronicsLCD/examples/HelloWorld/HelloWorld.pde index 74dd075e..ddc63b01 100644 --- a/libraries/FreetronicsLCD/examples/HelloWorld/HelloWorld.pde +++ b/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 - -// 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)