lcdMenu/README.md

# lcdMenu

A micropython library, which supports vertical and horizontal scrolling through menu items on both 2x16 and 4x20 liquid crystal displays

This project is the completely rewritten successor of my old (and now archived) [ProgramChooser](/BlueFox/ProgramChooser) library.

It is now production-ready (tested on 2x16 displays only at the moment.) ToDo: Make the README.md also seem production ready!


## Roadmap

- [x] forward, backward and select button
- [x] support for horizontal and vertical scrolling
- [x] support for both 2x16 and 4x20 LCDs
- [x] a reliable order of the menu items
- [x] good documentation for all of this (maybe through examples)
- [x] show an exit screen when a specific exit code is returned by a callback function
- [x] make the menu itself exitable (to enable stuff like submenus, etc.)
- [x] make the project a valid python package 


## Gallery

Here are some of examples of how a lcdMenu will look, and to get those, simply append the `Code` column's contents to the following (considering you have the library "installed" as explained before. All the examples below use a 2x16 display.

```python
from lcdMenu import lcdMenu
from machine import Pin, I2C
from PCF8574T import I2C_LCD

prev_btn = Pin(13, Pin.IN, Pin.PULL_DOWN)  # input of the first btn
next_btn = Pin(14, Pin.IN, Pin.PULL_DOWN)  # input of the second btn
ok_btn   = Pin(15, Pin.IN, Pin.PULL_DOWN)  # input of switch

LCD = I2C_LCD(I2C(0, sda=Pin(8), scl=Pin(9), freq=400000),0x27,2, 16)

def first():
    print("first() called! 1")
def second():
    print("second() called! 2")
def third():
    print("third() called! 3")
    return True


menuItems = [("first item", first),
             ("second item", second),
             ("third item", third)]
button_mappings = {"prev_btn":prev_btn, "next_btn": next_btn, "ok_btn": ok_btn}
```


<table>
    <tr>
        <th>Cycling</th>
        <th>Title shown</th>
        <th>Scroll direction</th>
        <th>Initial selection</th>
        <th>Result</th>
        <th>Code</th>
    </tr>
    <tr>
        <td>yes</td>
        <td>no</td>
        <td>vertical</td>
        <td>first</td>
        <td><img src="images/2x16-title-vertical-up-down-cycling.jpg" alt="No title, first item & cycling on -> up & down, vertical scrolling"/></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=False, cycle=True, hide_menu_name=True)
menu.setup(menuItems)
menu.run()</pre></td>
    </tr>
    <tr>
        <td>no</td>
        <td>no</td>
        <td>vertical</td>
        <td>first</td>
        <td><img src="images/2x16-no-title-vertical-only-down.jpg" alt="No title, first item &amp; no cycling -&gt; only down, vertical scrolling"></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=False, cycle=<b><i>False</i></b>, hide_menu_name=True)   # <- change of cycle to False!
menu.setup(menuItems)
menu.run()</pre></td>
    </tr>
    <tr>
        <td>no</td>
        <td>no</td>
        <td>vertical</td>
        <td>middle</td>
        <td><img src="images/2x16-no-title-vertical-up-down.jpg" alt="No title, middle item -&gt; up &amp; down, vertical scrolling"></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=False, cycle=False, hide_menu_name=True
menu.setup(menuItems, <b><i>start_selection=1</i></b>)  # <- change of the initial selection
menu.run()</pre></td>
    </tr>
    <tr>
        <td>no</td>
        <td>no</td>
        <td>vertical</td>
        <td>last</td>
        <td><img src="images/2x16-no-title-vertical-only-up.jpg" alt="No title, last item &amp; no cycling -&gt; only up, vertical scrolling"></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=False, cycle=False, hide_menu_name=True)
menu.setup(menuItems, start_selection<b><i>=2</i></b>)  # <- set initial selection to the last element
menu.run()</pre></td>
    </tr>
    <tr>
        <td>no</td>
        <td>yes</td>
        <td>vertical</td>
        <td>no options (first and last)</td>
        <td><img src="images/2x16-title-vertical-no-options.jpg" alt="With title, only one option, vertical scrolling"></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=False, cycle=False, hide_menu_name=<b><i>False, name="No options!"</i></b>)  # now with a title
menu.setup(<b><i>[("Only option", lambda: print("Only option chosen!"))]</i></b>)  # now with only one option (ignoring menuItems!)
menu.run()</pre></td>
    </tr>
    <tr>
        <td>no</td>
        <td>yes</td>
        <td>vertical</td>
        <td>first</td>
        <td><img src="images/2x16-title-vertical-only-down.jpg" alt="With title, first item & no cycling -> only down, vertical scrolling"></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=False, cycle=False, hide_menu_name=False, name="No options!")
menu.setup(<b><i>menuItems</i></b>)  # now with menuItems again
menu.run()</pre></td>
    </tr>
    <tr>
        <td>no</td>
        <td>yes</td>
        <td>vertical</td>
        <td>middle</td>
        <td><img src="images/2x16-title-vertical-up-down.jpg" alt="With title, middle item -> up & down, vertical scrolling"></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=False, cycle=False, hide_menu_name=False, name="lcdMenu!")
menu.setup(menuItems<b><i>, start_selection=1</i></b>)  # now with an index again
menu.run()</pre></td>
    </tr>
    <tr>
        <td>no</td>
        <td>yes</td>
        <td>vertical</td>
        <td>last</td>
        <td><img src="images/2x16-title-vertical-only-up.jpg" alt="With title, last item & no cycling -> only up, vertical scrolling"></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=False, cycle=False, hide_menu_name=False, name="lcdMenu!")
menu.setup(menuItems, start_selection<b><i>=2</i></b>)  # <- set initial selection to the last element
menu.run()</pre></td>
    </tr>
    <tr>
        <td>yes</td>
        <td>yes</td>
        <td>horizontal</td>
        <td>first</td>
        <td><img src="images/2x16-title-horizontal.jpg" alt="With title, middle item -> forward and backward, horizontal scrolling"></td>
        <td><pre>
menu = lcdMenu(LCD, button_mappings, scroll_direction=<b><i>True</i></b>, cycle=<b><i>True</i></b>, hide_menu_name=False, name="lcdMenu!")
menu.setup(menuItems)
menu.run()</pre></td>
    </tr>
</table>


## License

This project is licensed under the GPL-v3-or-later. A copy can be found [here](LICENSE).