Add Textbox widget. Minor API change to Scale.

README.md

@@ -44,6 +44,7 @@ wiring details, pin names and hardware issues.
   3.5 [Dial and Pointer classes](./README.md#35-dial-and-pointer-classes) Clock
   or compass style display of one or more pointers.  
   3.6 [Scale class](./README.md#36-scale-class) Linear display with wide dynamic range.  
+  3.7 [Class Textbox](./README.md#37-class-textbox) Scrolling text display.  
  4. [Device drivers](./README.md#4-device-drivers) Device driver compatibility
  requirements (these are minimal).
 
@@ -71,6 +72,11 @@ following displays. These have internal buffers:
 
 ## 1.1 Update
 
+17 Nov 2020  
+Add `Textbox` widget. `Scale` constructor arg `border` replaced by `bdcolor` as
+per other widgets.
+
+5 Nov 2020  
 This library has been refactored as a Python package. The aim is to reduce RAM
 usage: widgets are imported on demand rather than unconditionally. This enabled
 the addition of new widgets with zero impact on existsing applications. Another
@@ -639,7 +645,7 @@ Keyword only arguments (all optional):
  * `tickcb=None` Callback for setting tick colors (see below).
  * `height=0` Pass 0 for a minimum height based on the font height.
  * `width=200`
- * `border=2` Border width in pixels.
+ * `bdcolor=None` Border color. If `None`, `fgcolor` will be used.
  * `fgcolor=None` Foreground color. Defaults to system color.
  * `bgcolor=None` Background color defaults to system background.
  * `pointercolor=None` Color of pointer. Defaults to `.fgcolor`.
@@ -693,6 +699,61 @@ between consecutive large ticks and legends is divided by 10. This means that
 the `tickcb` callback must return a string having an additional significant
 digit. If this is not done, consecutive legends will have the same value.
 
+###### [Contents](./README.md#contents)
+
+## 3.7 Class Textbox
+
+Displays multiple lines of text in a field of fixed dimensions. Text may be
+clipped to the width of the control or may be word-wrapped. If the number of
+lines of text exceeds the height available, scrolling will occur. Access to
+text that has scrolled out of view may be achieved by by calling a method.
+
+Works with fixed and variable pitch fonts.
+```python
+from gui.widgets.textbox import Textbox
+```
+
+Constructor mandatory positional arguments:
+ 1. `writer` The `Writer` instance (font and screen) to use.
+ 2. `row` Location on screen.
+ 3. `col`  
+ 4. `width` Width of the object in pixels.
+ 5. `nlines` Number of lines of text to display. The object's height is
+ determined from the height of the font:  
+ `height in pixels = nlines*font_height`  
+ As per most widgets the border is drawn two pixels beyond the control's
+ boundary.
+
+Keyword only arguments:
+ * `bdcolor=None` Border color. If `None`, `fgcolor` will be used.
+ * `fgcolor=None` Color of border. Defaults to system color.
+ * `bgcolor=None` Background color of object. Defaults to system background.
+ * `clip=True` By default lines too long to display are right clipped. If
+ `False` is passed, word-wrap is attempted. If the line contains no spaces
+ it will be wrapped at the right edge of the window.
+
+Methods:
+ * `append` Args `s, ntrim=None, line=None` Append the string `s` to the
+ display and scroll up as required to show it. By default only the number of
+ lines which will fit on screen are retained. If an integer `ntrim=N` is
+ passed, only the last N lines are retained; `ntrim` may be greater than can be
+ shown in the control, hidden lines being accessed by scrolling.  
+ If an integer (typically 0) is passed in `line` the display will scroll to
+ show that line.
+ * `scroll` Arg `n` Number of lines to scroll. A negative number scrolls up. If
+ scrolling would achieve nothing because there are no extra lines to display,
+ nothing will happen. Returns `True` if scrolling occurred, otherwise `False`.
+ * `value` No args. Returns the number of lines of text stored in the widget.
+ * `clear` No args. Clears all lines from the widget and refreshes the display.
+ * `goto` Arg `line=None` Fast scroll to a line. By default shows the end of
+ the text. 0 shows the start.
+
+Fast updates:  
+Rendering text to the screen is relatively slow. To send a large amount of text
+the fastest way is to perform a single `append`. Text may contain newline
+(`'\n'`) characters as required. In that way rendering occurs once only.
+
+###### [Contents](./README.md#contents)
 
 # 4. Device drivers
 

gui/core/nanogui.py

@@ -88,6 +88,7 @@ class DObject():
         self.writer = writer
         device = writer.device
         self.device = device
+        # The following assumes that the widget is mal-positioned, not oversize.
         if row < 0:
             row = 0
             self.warning()
@@ -98,7 +99,7 @@ class DObject():
             col = 0
             self.warning()
         elif col + width >= device.width:
-            row = device.width - width - 1
+            col = device.width - width - 1
             self.warning()
         self.row = row
         self.col = col

gui/demos/scale.py

@@ -69,7 +69,7 @@ def test():
     lbl = Label(wri, ssd.height - wri.height - 2, 2, 50, 
                 bgcolor = DARKGREEN, bdcolor = RED, fgcolor=WHITE)
     scale = Scale(wri, 45, 2, width = 124, tickcb = tickcb,
-                  pointercolor=RED, fontcolor=YELLOW)
+                  pointercolor=RED, fontcolor=YELLOW, bdcolor=CYAN)
     asyncio.run(default(scale, lbl))
 
 test()

gui/widgets/scale.py

@@ -13,7 +13,7 @@ from gui.core.colors import BLACK
 class Scale(DObject):
     def __init__(self, writer, row, col, *,
                  ticks=200, legendcb=None, tickcb=None,
-                 height=0, width=100, border=2, fgcolor=None, bgcolor=None,
+                 height=0, width=100, bdcolor=None, fgcolor=None, bgcolor=None,
                  pointercolor=None, fontcolor=None):
         if ticks % 2:
             raise ValueError('ticks arg must be divisible by 2')
@@ -25,18 +25,19 @@ class Scale(DObject):
         bgcolor = BLACK if bgcolor is None else bgcolor
         text_ht = writer.font.height()
         ctrl_ht = 12  # Minimum height for ticks
-        min_ht = text_ht + 2 * border + 2  # Ht of text, borders and gap between text and ticks
+        # Add 2 pixel internal border to give a little more space
+        min_ht = text_ht + 6  # Ht of text, borders and gap between text and ticks
         if height < min_ht + ctrl_ht:
             height = min_ht + ctrl_ht  # min workable height
         else:
             ctrl_ht = height - min_ht  # adjust ticks for greater height
         width &= 0xfffe  # Make divisible by 2: avoid 1 pixel pointer offset
-        super().__init__(writer, row, col, height, width, fgcolor, bgcolor, fgcolor)
+        super().__init__(writer, row, col, height, width, fgcolor, bgcolor, bdcolor)
         self.fontcolor = fontcolor if fontcolor is not None else self.fgcolor
-        self.x0 = col + border
-        self.x1 = col + self.width - border
-        self.y0 = row + border
-        self.y1 = row + self.height - border
+        self.x0 = col + 2
+        self.x1 = col + self.width - 2
+        self.y0 = row + 2
+        self.y1 = row + self.height - 2
         self.ptrcolor = pointercolor if pointercolor is not None else self.fgcolor
         # Define tick dimensions
         ytop = self.y0 + text_ht + 2  # Top of scale graphic (2 pixel gap)