updated the docs for 2.0.3

CHANGELOG

@@ -1,6 +1,11 @@
 Change Log
 ==========
 
+v2.0.3
+------
+- Updated documentation. Examples page, creating custom bitmaps and tools.
+- Fixed bug in LCDQuestion.
+
 v2.0.2
 ------
 - Updated lirc docs.

docs/creating_custom_bitmaps.rst

@@ -12,22 +12,20 @@ of binary values each describing a line. For example::
 
 or as hex::
 
-    >>> quaver = pifacecad.LCDBitmap(
-    ...     [0x2, 0x3, 0x2, 0xe, 0x1e, 0xc, 0x0])
+    >>> quaver = pifacecad.LCDBitmap([0x2, 0x3, 0x2, 0xe, 0x1e, 0xc, 0x0])
 
-or as binary (you can almost see the bitmap here)::
+or as binary (you can almost see the bitmap image here)::
 
-    >>> quaver = pifacecad.LCDBitmap([
-    ...     0b00010,
-    ...     0b00011,
-    ...     0b00010,
-    ...     0b01110,
-    ...     0b11110,
-    ...     0b01100,
-    ...     0b00000])
+    >>> quaver = pifacecad.LCDBitmap([0b00010,
+    ...                               0b00011,
+    ...                               0b00010,
+    ...                               0b01110,
+    ...                               0b11110,
+    ...                               0b01100,
+    ...                               0b00000])
 
 .. note:: You can use `this tool <http://www.quinapalus.com/hd44780udg.html>`_
-   to help design custom bitmaps.
+   to help design custom bitmaps. Make sure you select 5x8.
 
 You store and display custom bitmaps with the following commands::
 
@@ -38,11 +36,7 @@ You store and display custom bitmaps with the following commands::
 Here is a complete code example::
 
     >>> import pifacecad
-    >>> pifacecad.init()
     >>> cad = pifacecad.PiFaceCAD()
-    >>> # create, store and write the bitmap
-    >>> quaver = pifacecad.LCDBitmap(
-    ...     [0x2, 0x3, 0x2, 0xe, 0x1e, 0xc, 0x0])
-    ...
+    >>> quaver = pifacecad.LCDBitmap([0x2, 0x3, 0x2, 0xe, 0x1e, 0xc, 0x0])
     >>> cad.lcd.store_custom_bitmap(0, quaver)
     >>> cad.lcd.write_custom_bitmap(0)

docs/example.rst

@@ -5,19 +5,49 @@ Examples
 Basic usage
 ===========
 
-::
+Hello, World!::
 
     >>> import pifacecad
 
     >>> cad = pifacecad.PiFaceCAD()    # create PiFace Control and Display object
     >>> cad.lcd.backlight_on()         # turns the backlight on
     >>> cad.lcd.write("Hello, world!") # writes hello world on to the LCD
-    >>>
+
+Reading the switches::
+
     >>> cad.switches[3].value  # reads the value of switch 3
     1
     >>> cad.switch_port.value  # reads the value of the switch port
     4
 
+Cursor control::
+
+    >>> cad.lcd.set_cursor(4, 1)  # set the cursor to col 4 on the second row
+    >>> cad.lcd.cursor_off()      # turns the cursor off
+    >>> cad.lcd.write("3.141592") # writes π to the LCD
+
+    >>> cad.lcd.blink_off()       # turns the blinking off
+    >>> cad.lcd.cursor_on()       # turns the cursor on
+    >>> cad.lcd.home()            # send the cursor home
+
+    >>> cad.lcd.write("PiFace Control\nand Display")  # '\n' starts a new line
+    >>> cad.lcd.clear()           # clear the screen (also sends the cursor home)
+
+The LCD has more RAM than just the 16x2 characters that you can see::
+
+    >>> cad.lcd.write("Something really, really long.")
+    >>> cad.lcd.move_right()
+    >>> cad.lcd.move_left()
+    >>> cad.lcd.see_cursor()  # move the display so that we can see the cursor
+
+The `viewport_corner` variable describes which column the top left display
+character is showing from RAM::
+
+    >>> cad.lcd.viewport_corner       # inspect the viewport_corner variable
+    8
+    >>> cad.lcd.viewport_corner = 15  # set the viewport_corner variable
+
+You can also `create your own custom bitmaps <creating_custom_bitmaps.html>`_.
 
 IR Receiver
 ===========

docs/index.rst

@@ -20,7 +20,7 @@ Links:
     - `Blog <http://pifacedigital.wordpress.com/>`_
     - `GitHub <https://github.com/piface/pifacecad/>`_
     - `PyPI <https://pypi.python.org/pypi/pifacecad/>`_
-    - `Create Custom Bitmaps <http://www.quinapalus.com/hd44780udg.html>`_
+    - `Custom Bitmaps Generator <http://www.quinapalus.com/hd44780udg.html>`_
 
 Contents:
 
@@ -29,8 +29,9 @@ Contents:
 
    installation
    example
-   lirc
    creating_custom_bitmaps
+   tools
+   lirc
    reference
    reference_tools
 

docs/tools.rst

@@ -0,0 +1,82 @@
+Tools
+=====
+
+There are some tools provided with PiFace Control and Display which simplify
+getting input from a user.
+
+Question
+--------
+:class:`pifacecad.tools.question.LCDQuestion` will display a question on the
+top row and an answer on the  bottom. The user can cycle through answers by
+moving the navigation switch left and right and select an answer by pressing
+the navigation switch in.
+
+It can be used like this::
+
+    >>> import pifacecad
+    >>> from pifacecad.tools.question import LCDQuestion
+
+    >>> question = LCDQuestion(question="What is 5 x 2?", answers=["1", "10", "12"])
+    >>> answer_index = question.ask()
+
+You can pass in an already initialised Control and Display object and also
+specify a custom selector::
+
+    >>> import pifacecad
+    >>> from pifacecad.tools.question import LCDQuestion
+
+    >>> customcad = pifacecad.PiFaceCAD()
+    >>> customcad.lcd.cursor_off()
+    >>> customcad.lcd.blink_off()
+
+    >>> question = LCDQuestion(question="What is 5 x 2?",
+    ...                        answers=["1", "10", "12"],
+    ...                        selector="#",
+    ...                        cad=customcad)
+    >>> answer_index = question.ask()
+
+Scanf
+-----
+:class:`pifacecad.tools.scanf.LCDScanf` will display a custom string that
+can be modified using the navigation switch. In 'select' mode, moving the
+navigation switch left or right (switches 6 and 7) selects a character.
+Change to 'edit' mode by pressing the navigation switch in (switch 5).
+In edit mode, moving the navigation switch left or right changes the character.
+
+To return the input, move the cursor under the 'enter' arrow and press the
+navigation switch in.
+
+The `LCDScanf` class can be used like this::
+
+    >>> import pifacecad
+    >>> from pifacecad.tools.scanf import LCDScanf
+
+    >>> scanner = LCDScanf("Text: %c%2i%.%r")
+    >>> print(scanner.scan())  # user enters things on PiFace C&D
+    ['a', '13', '!']
+
+The format string defines editable variables using a `%` symbol. The
+format specification is::
+
+    c: Characters
+    C: Capital Characters
+    i: Integers
+    d: Intergers
+    x: Hexadecimal
+    X: Capital Hexadecimal
+    .: Punctuation
+    m: Custom (specifed by ``custom_values`` in init args)
+    r: Return (switch 5 to submit string)
+
+To add multiple characters in the same variable you can specify a number
+after the `%` symbol. For example, to request that the user enter a two
+digit integer::
+
+    >>> print(LCDScanf("%2i%r").scan())
+    ['42']
+
+You can use the `m` specifier to enter custom variable values::
+
+    >>> scanner = LCDScanf("Animal: %m%r", custom_values=('cat', 'dog', 'fish'))
+    >>> print(scanner.scan())
+    ['fish']

pifacecad/tools/question.py

@@ -1,6 +1,7 @@
 import sys
 import threading
 import pifacecad
+import pifacecad.lcd
 
 # Python 2 barrier hack (if you know a better way, please tell me)
 PY3 = sys.version_info[0] >= 3
@@ -91,7 +92,7 @@ def change_answer(self, new_answer_index=None):
 
         # pad with spaces to overwrite previous answer (ljust)
         prev_ans = self.answers[self._displayed_answer_index]
-        prev_ans_len = max(len(prev_ans), pifacecad.LCD_WIDTH)
+        prev_ans_len = max(len(prev_ans), pifacecad.lcd.LCD_WIDTH)
         answer = self.answers[new_answer_index].ljust(prev_ans_len)
 
         self.cad.lcd.set_cursor(0, 1)

pifacecad/tools/scanf.py

@@ -42,8 +42,9 @@ class UnknownSpecifierError(Exception):
 class LCDScanf(object):
     """Allows the user to input text using the LCD.
 
-    To change mode from moving and editing press switch 5 (rocker switch *in*).
-    Move the rocker switch side to side (switches 6 and 7) to change character.
+    To change mode from moving and editing press switch 5 (navigation switch
+    *in*). Move the navigation switch side to side (switches 6 and 7) to
+    change character.
 
     The available character set is specified using a format string similar to
     printf. Supported character specifiers are::

pifacecad/version.py

@@ -1 +1 @@
-__version__ = '2.0.2'
+__version__ = '2.0.3'