# 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.)


# Installation

To "install" the library on your Pico, clone the repository first using `git clone`. Open [Thonny](https://thonny.org). There, open a file from "This computer" (thonny asks for the location after clicking on "Open"), and select the `__init__.py` from this repository. To get this file to your Pico's storage, choose "Save as" and choose "Raspberry Pi Pico" as the location.

Now, create a new directory called lcdMenu in the root of the Pico's file system (you can do that in the "magic" /lib folder too, makes no difference), and after that save the file there (with `__init__.py` being the file name).

Now you can use the library using `import lcdMenu` in any of your scripts!


# Usage

For basic usage, you just have to create an LCD object, use it to create a lcdMenu along with some other arguments. On this newly created object, run the `setup()` method with your menu item list. Then, start the menu by calling the (blocking) `run()` method on it.

To stop a running instance of lcdMenu (started by `run()`), call the method `stop()` on it!

For further usage, see the comments above the respective method definition in question in the [__init__.py](__init__.py) file. These try to describe the behaviour of each parameter pretty precise. Also, have a look into the examples which can be found in the [examples](examples/) folder.


## Gallery

Here are some of examples of how a lcdMenu will look, showcasing the amount of options you have with lcdMenu. Currently, as the library is only tested with 2x16 displays, these are the only ones showing up below - but on 4x20, it should look the same except it's bigger!


<table>
    <tr>
        <th>Scroll direction</th>
        <th>Cycling</th>
        <th>Title shown</th>
        <th>Initial selection</th>
        <th>Result</th>
    </tr>
    <tr>
        <td>horizontal</td>
        <td>yes</td>
        <td>yes</td>
        <td>first</td>
        <td><img src="images/2x16-title-horizontal.jpg" alt="With title, middle item -> forward and backward, horizontal scrolling"></td>
    </tr>
    <tr>
        <td>vertical</td>
        <td>yes</td>
        <td>no</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>
    </tr>
    <tr>
        <td>vertical</td>
        <td>no</td>
        <td>no</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>
    </tr>
    <tr>
        <td>vertical</td>
        <td>no</td>
        <td>no</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>
    </tr>
    <tr>
        <td>vertical</td>
        <td>no</td>
        <td>no</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>
    </tr>
    <tr>
        <td>vertical</td>
        <td>no</td>
        <td>yes</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>
    </tr>
    <tr>
        <td>vertical</td>
        <td>no</td>
        <td>yes</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>
    </tr>
    <tr>
        <td>vertical</td>
        <td>no</td>
        <td>yes</td>
        <td>middle</td>
        <td><img src="images/2x16-title-vertical-up-down.jpg" alt="With title, middle item -> up & down, vertical scrolling"></td>
    </tr>
    <tr>
        <td>vertical</td>
        <td>no</td>
        <td>yes</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>
    </tr>
</table>


## License

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