From 7a2326f25ec59ae541ed10df1dc895b5573211a9 Mon Sep 17 00:00:00 2001
From: troyhy <toni@montel.fi>
Date: Tue, 3 Sep 2024 20:38:22 +0300
Subject: [PATCH] add color_image documentation and add ColorBitMap to lazy
 loader of widgets

---
 README.md               | 37 +++++++++++++++++++++++++++++++++++++
 gui/widgets/__init__.py |  1 +
 2 files changed, 38 insertions(+)

diff --git a/README.md b/README.md
index 39879e7..03a9b20 100644
--- a/README.md
+++ b/README.md
@@ -2807,6 +2807,43 @@ action. Use in animations is questionable.
 See `gui/demos/bitmap.py` for a usage example. Files must be copied from
 `gui/fonts/bitmaps/` to the root directory of the device.
 
+## 6.19 ColorBitMap Widget (experimental)
+
+```python
+from gui.widgets import ColorBitMap  # File: color_bitmap.py
+```
+![Image](./images/bitmap.JPG)  
+
+This renders a image with color palette prepared with image_converter.py. The
+bitmap file format is python module. ColorBitwapWidget has the bitmap() method to 
+decode bitstream. Bitmap can have up to 8 bits for color from 16 bit palette. Converter 
+script downscales image colors to fit wanted bit per pixel.
+
+This Widget is only tested currently with drivers/st7789/st7789_16bit.py and has a 
+palette transformer function that converts bitmap palette to display's rgb565 format
+
+Constructor mandatory positional args:  
+ 1. `writer` A `Writer` instance.
+ 2. `row` Location on screen.
+ 3. `col`
+ 4. `height` Image height in pixels. Dimensions must exactly match the image file.
+ 5. `width` Image width in pixels.
+
+Keyword only args:  
+ * `fgcolor=None` Foreground (1) color of image. <NOT USED ATM>
+ * `bgcolor=None` Background (0) color. <NOT USED ATM>
+ * `bdcolor=RED` Border color.
+
+Methods:__
+ * `value` mandatory arg `fn` path to an image file. Causes the `BitMap` image
+ to be updated from the file. Files should be stored on the root directory of
+ the host. Blocks for a period depending on filesystem performance.
+ * `color` arg `bgcolor=None`. Causes the border color to be changed. The file 
+   will be re-read and the image updated.
+
+See `gui/demos/color_bitmap.py` for a usage example. The test_image.py must be copied 
+from `gui/fonts/bitmaps/` to the root directory of the device.
+
 ###### [Contents](./README.md#0-contents)
 
 ## 6.20 QRMap Widget
diff --git a/gui/widgets/__init__.py b/gui/widgets/__init__.py
index 94d05ed..859bb0a 100644
--- a/gui/widgets/__init__.py
+++ b/gui/widgets/__init__.py
@@ -26,6 +26,7 @@ _attrs = {
     "BitMap": "bitmap",
     "QRMap": "qrcode",
     "Grid": "grid",
+    "ColorBitMap": "color_bitmap",
     }
 
 # Lazy loader, effectively does: