{"id":13802164,"url":"https://github.com/peterhinch/micropython-tft-gui","last_synced_at":"2025-06-19T11:37:32.228Z","repository":{"id":86072669,"uuid":"57951113","full_name":"peterhinch/micropython-tft-gui","owner":"peterhinch","description":"Simple GUI for Pyboard and TFT touch panel displays","archived":false,"fork":false,"pushed_at":"2020-06-16T17:03:57.000Z","size":1261,"stargazers_count":94,"open_issues_count":2,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-30T15:33:23.169Z","etag":null,"topics":["display","embedded","micropython"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peterhinch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-05-03T07:47:02.000Z","updated_at":"2025-03-01T00:17:19.000Z","dependencies_parsed_at":"2023-04-20T20:32:21.989Z","dependency_job_id":null,"html_url":"https://github.com/peterhinch/micropython-tft-gui","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/peterhinch/micropython-tft-gui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-tft-gui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-tft-gui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-tft-gui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-tft-gui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peterhinch","download_url":"https://codeload.github.com/peterhinch/micropython-tft-gui/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-tft-gui/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260744213,"owners_count":23056109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["display","embedded","micropython"],"created_at":"2024-08-04T00:01:37.868Z","updated_at":"2025-06-19T11:37:27.208Z","avatar_url":"https://github.com/peterhinch.png","language":"Python","readme":"# micropython-gui\n\nProvides a simple touch driven event based GUI interface for the Pyboard when\nused with a TFT display. The latter should be based on SSD1963 controller with\nXPT2046 touch controller. Such displays are available in electronics stores\n[e.g.]( http://www.buydisplay.com/default/) and on eBay. The software is based\non drivers for the TFT and touch controller from Robert Hammelrath.\n\nIt now uses and requires `uasyncio` V3.\n\nIt is targeted at hardware control and display applications.\n\n![Image](pictures/IMG_2441_small.JPG)\n\nFor hardware notes see this [reference](./HARDWARE.md). An extension for\nplotting simple graphs is described [here](./PLOT.md).\n\nFor sample images, go [here](./IMAGES.md).\nA video may be seen [here](http://hinch.me.uk/tft_gui/tft_gui.mp4).\n\n# Contents\n\n1. [Release notes](./README.md#1-release-notes-for-existing-users)  \n2. [Pre requisites](./README.md#2-pre-requisites)  \n  2.1 [Pre installation](./README.md#21-pre-installation)  \n  2.2 [Library Documentation](./README.md#22-library-documentation)  \n  2.3 [Python files](./README.md#23-python-files)  \n  2.4 [Running the demos](./README.md#24-running-the-demos)  \n3. [Icons](./README.md#3-icons)  \n4. [Concepts](./README.md#4-concepts)  \n  4.1 [Terminology](./README.md#41-terminology)  \n  4.2 [Coordinates](./README.md#42-coordinates)  \n  4.3 [Colors](./README.md#43-colors)  \n  4.4 [Callbacks](./README.md#44-callbacks)  \n  4.5 [Screens](./README.md#45-screens)  \n5. [Program Structure](./README.md#5-program-structure)  \n6. [Class Screen](./README.md#6-class-screen)  \n  6.1 [Class methods](./README.md#61-class-methods)  \n  6.2 [Constructor](./README.md#62-constructor)  \n  6.3 [Callback methods](./README.md#63-callback-methods)  \n  6.4 [Method](./README.md#64-method)  \n7. [Display Widgets](./README.md#7-display-widgets) Non touch sensitive displayable objects.  \n  7.1 [Class Label](./README.md#71-class-label)  \n  7.2 [Class Dial](./README.md#72-class-dial)  \n  7.3 [Class LED](./README.md#73-class-led)  \n  7.4 [Class Meter](./README.md#74-class-meter)  \n  7.5 [Class IconGauge](./README.md#75-class-icongauge)  \n  7.6 [Vector display](./README.md#76-vector-display)  \n8. [Control Widgets](./README.md#8-control-widgets) Touch sensitive displayable objects  \n  8.1 [Class Slider](./README.md#81-class-slider)  \n  8.2 [Class Knob](./README.md#82-class-knob)  \n  8.3 [Class Checkbox](./README.md#83-class-checkbox)  \n  8.4 [Class Button](./README.md#84-class-button)  \n  8.5 [Class ButtonList: emulate a button with multiple states](./README.md#85-class-buttonlist-emulate-a-button-with-multiple-states)  \n  8.6 [Class RadioButtons](./README.md#86-class-radiobuttons)  \n  8.7 [Class IconButton also checkbox](./README.md#87-class-iconbutton-also-checkbox)  \n  8.8 [Class IconRadioButtons](./README.md#88-class-iconradiobuttons)  \n  8.9 [Class Listbox](./README.md#89-class-listbox)  \n  8.10 [Class Dropdown](./README.md#810-class-dropdown)  \n9. [Dialog Boxes](./README.md#9-dialog-boxes)  \n  9.1 [Class Aperture](./README.md#91-class-aperture)  \n  9.2 [Class DialogBox](./README.md#92-class-dialogbox)  \n10. [Developer Notes](./README.md#10-developer-notes)  \n\n# 1. Release notes for existing users\n\nRelease 0.7 16th Jun 2020 Refactored as a Python package (see below). Add\nvector display widgets.\nRelease 0.6 15th Jun 2020 Uses (and requires) `uasyncio` V3.\nRelease 0.51 14th Feb 2017 add `Screen.after_open` method.\nRelease 0.5 7th Jan 2017. Uses `uasyncio` in place of `usched`.\nRelease 0.2 17th Nov 2016. Uses fonts created with the `font_to_py.py` utility.\n\n### V0.7 note\n\nThis has been refactored as a Python package. This enables a modular design and\nreduces RAM use to the point where frozen bytecode is not usually required. All\ntest scripts apart from the icon test will run without frozen code.\n\nApplications will require changes to import statements.\n\n###### [Jump to Contents](./README.md#contents)\n\n# 2. Pre requisites\n\n## 2.1 Pre installation\n\nBefore running the GUI the hardware should be tested. The display may\noptionally be calibrated according to the instructions on Robert Hammelrath's\n[site](https://github.com/robert-hh/XPT2046-touch-pad-driver-for-PyBoard.git).\nResistive touch panels work best when activated by a stylus or fingernail. They\nare also subject to jitter to a degree which varies between display models: the\ntouch library uses digital filtering to reduce the effect of jitter. This uses\ntwo values `confidence` and `margin` which may be fine tuned to the unit in\nuse prior to running the GUI. The optimum values, together with calibration\ndata, should be stored in the file `tft_local.py` listed below.\n\nSome familiarity with callbacks and event driven programming will be of help in\ndeveloping applications. The GUI classes are in two categories, those rendered\nusing icons and those drawn by means of graphics primitives. Either (or both)\nmay be used in a project.\n\nSmaller applications not using icon controls will run without frozen bytecode.\nUsers planning larger applications should familiarise themselves with building\nMicropython from source, and with the technique for installing Python modules\nas frozen bytecode. Official instructions on how to do this may be found\n[here](http://docs.micropython.org/en/latest/reference/packages.html). At the\ntime of writing these did not reflect the new \"manifest\" system, which is\ndescribed\n[here](https://github.com/peterhinch/micropython-samples/tree/master/fastbuild).\n\n#### Firmware\n\nTo ensure the correct version of `uasyncio` firmware must be a daily build or a\nrelease build later than V1.12.\n\n## 2.2 Library Documentation\n\nDocumentation for the underlying libraries may be found at these sites.  \nRobert Hammelrath's drivers:  \n[XPT2046 driver](https://github.com/robert-hh/XPT2046-touch-pad-driver-for-PyBoard.git)  \n[TFT driver](https://github.com/robert-hh/SSD1963-TFT-Library-for-PyBoard.git)  \nOther references:  \n[Proposed standard font format](https://github.com/peterhinch/micropython-font-to-py)  \n[TFT driver fork](https://github.com/peterhinch/SSD1963-TFT-Library-for-PyBoard.git)\nRobert Hammelrath's driver adapted for above font format.  \n[uasyncio libraries and notes](https://github.com/peterhinch/micropython-async)  \n\n## 2.3 Python files\n\nThe simplest way to install this library is to copy the `tft` directory and all\nits contents to the Pyboard's filesystem.\n\nHardware driver in tft/driver:\n 1. `TFT_io.py` Low level TFT driver. Cannot be frozen.\n\nCore files in tft/driver:\n 1. `tft.py` TFT driver.\n 2. `touch_bytecode.py` Touch panel driver.\n 3. `ugui.py` The micro GUI library.\n 4. `constants.py` Constants such as colors and shapes (import using\n `from tft.driver.constants import *`)\n 5. `tft_local.py` Local hardware definition (user defined settings including\n optional calibration  data). This file should be edited to match your hardware.\n\nSynchronisation primitives in tft/primitives:\n 1. `delay_ms` A software retriggerable timer.\n\nOptional files used by test programs:\n\nFonts in tft/fonts:\n 1. `font10.py` Font file.\n 2. `font14.py` Ditto.\n\nIcons in tft/icons:\n 1. `radiobutton.py` Icon file for icon radio buttons\n 2. `checkbox.py` Icon file for icon checkboxes.\n 3. `iconswitch.py` Icon file for an on/off switch.\n 4. `traffic.py` Icons for traffic light button\n 5. `gauge.py` Icons for linear gauge\n 6. `flash.py` Icons for flashing button\n 7. `threestate.py` Icon for 3-state checkbox\n\nTest/demo programs in tft/demos:\n 1. `vst.py` A test program for vertical linear sliders.\n 2. `hst.py` Tests horizontal slider controls, meters and LED.\n 3. `buttontest.py` Pushbuttons and checkboxes.\n 4. `knobtest.py` Rotary controls, a dropdown list, a listbox. Also shows the\n two styles of \"greying out\" of disabled controls.\n 5. `screentest.py` Test of multiple screens.\n 6. `dialog.py` A modal dialog box.\n 7. `ibt.py` Test of icon buttons.\n 8. `vtest.py` Vector display: clock and compass displays.\n\nIf you don't intend to use icons, icon files and demo 7 may be ignored.\n\nBy the standards of the Pyboard this is a large library. All test scripts will\nrun without frozen bytecode with the exception of `ibt.py`. Larger applications\nand any using icons will require freezing some modules to conserve RAM.\n\nWhen freezing files create the same directory structure in your frozen modules\ndirectory. For example, create the directory 'tft/icons' and copy all icons\nthere. This allows the import statements to be unchanged.\n\nPreferred candidates for freezing are icons (if used), fonts and drivers. The\nhardware driver listed above cannot be frozen as it uses inline assembler and\nViper code. It's probably unwise to freeze `tft_local.py` as it may need to be\nedited for calibration values etc.\n\nInstructions on creating icon files may be found in the\n[TFT driver README](https://github.com/robert-hh/SSD1963-TFT-Library-for-PyBoard.git). Fonts\nshould be created using\n[font_to_py.py](https://github.com/peterhinch/micropython-font-to-py.git). The\n`-x` argument should be employed.\n\n## 2.4 Running the demos\n\nDemos run on import, which is done using the following syntax:\n```python\nfrom tft.demos import hst\n```\nIf you experience memory errors after running more than one demo, issue ctrl-d\nto reset the board.\n\n###### [Jump to Contents](./README.md#contents)\n\n# 3. Icons\n\nMost classes use graphics primitives to draw objects on the screen. A few\nemploy icons: this is arguably prettier but less \"micro\". It uses large icon\nfiles which must be frozen as bytecode. By contrast objects drawn with graphics\nprimitives are scalable. Further, properties such as colors can efficiently be\nchanged at runtime: to achieve this with an icon-based object would require a\nset of colored icons to be created at design time. The library is usable\nwithout the icon classes.\n\nInstructions and a utility for creating icon files may be found in Robert\nHammelrath's\n[TFT driver README](https://github.com/robert-hh/SSD1963-TFT-Library-for-PyBoard.git).\n\n###### [Jump to Contents](./README.md#contents)\n\n# 4. Concepts\n\n## 4.1 Terminology\n\nGUI objects are created on a `Screen` instance which normally fills the entire\nphysical screen. Displayable GUI objects comprise `control` and `display`\ninstances. The former can respond to touch (e.g. Pushbutton instances) while\nthe latter cannot (LED or Dial instances).\n\n## 4.2 Coordinates\n\nIn common with most displays, the top left hand corner of the display is (0, 0)\nwith increasing values of x to the right, and increasing values of y downward.\nDisplay objects exist within a rectangular bounding box; in the case of touch\nsensitive controls this corresponds to the sensitive region. Locations are\ndefined as a 2-tuple (x, y). The location of an object is defined as the\nlocation of the top left hand corner of the bounding box.\n\n## 4.3 Colors\n\nThese are defined as a 3-tuple (r, g, b) with values of red, green and blue in\nrange 0 to 255. The interface and this document uses the American spelling\n(color) throughout for consistency with the TFT library.\n\n## 4.4 Callbacks\n\nThe interface is event driven. Controls may have optional callbacks which will\nbe executed when a given event occurs. A callback function receives positional\narguments. The first is a reference to the object raising the callback.\nSubsequent arguments are user defined, and are specified as a tuple or list of\nitems. Callbacks are optional, as are the argument lists - a default null\nfunction and empty list are provided. Callbacks are usually bound methods - see\nthe Screens section for a reason why this is useful.\n\nAll controls and displays have a `tft` property. This enables callbacks to\naccess drawing primitives.\n\n## 4.5 Screens\n\nGUI controls and displays are rendered on a `Screen` instance. A user program\nmay instantiate multiple screens, each with its own set of GUI objects. The\n`Screen` class has class methods enabling runtime changes of the screen being\nrendered to the physical display. This enables nested screens. The feature is\ndemonstrated in `screentest.py`.\n\nApplications should be designed with a `Screen` subclass for each of the\napplication's screens (even if the app uses only a single screen). This\nfaciitates sharing data between GUI objects on a screen, and also simplifies\nthe handling of control callbacks. These will be methods bound to the user\nscreen. They can access the screen's bound variables via `self` and the\ncontrol's bound methods via the callback's first argument (which is a reference\nto the control). A simple example can be seen in the `KnobScreen` example in\n`screentest.py`.\n\nThe `Screen` class has 3 null methods which may be implemented in subclasses:\n`on_open` which runs when a screen is opened but prior to its display,\n`after_open` which is called after display, and `on_hide` which runs when a\nscreen change is about to make the screen disappear. These may be used to\ninstantiate or control tasks and to retrieve results from a modal dialog box.\n\nThe `Screen` class is configured in `tft_local.py`.\n\n###### [Jump to Contents](./README.md#contents)\n\n# 5. Program Structure\n\nThe following illustrates the structure of a minimal program:\n```python\nfrom tft.driver.ugui import Screen\nfrom tft.driver.constants import *\nfrom tft.driver.tft_local import setup\n\nfrom tft.fonts import font14\nfrom tft.widgets.buttons import Button\n\nclass BaseScreen(Screen):\n    def __init__(self):\n        super().__init__()\n        Button((10, 10), font = font14, fontcolor = BLACK, text = 'Hi')\nsetup()\nScreen.change(BaseScreen)\n```\n\nThe last line causes the Screen class to instantiate your `BaseScreen` and to\nstart the scheduler using that screen object. Control then passes to the\nscheduler: any code following this line will not run until the GUI is shut down\nand the scheduler is stopped (by calling `Screen.shutdown()`).\n\n###### [Jump to Contents](./README.md#contents)\n\n# 6. Class Screen\n\nThe `Screen` class presents a full-screen canvas onto which displayable objects\nare rendered. Before instantiating GUI objects a `Screen` instance must be\ncreated. This will be the current one until another is instantiated. When a GUI\nobject is instantiated it is associated with the current screen.\n\nThe best way to use the GUI, even in single screen programs, is to create a\nuser screen by subclassing the `Screen` class. GUI objects are instantialited\nin the constructor after calling the `Screen` constructor. This arrangement\nfacilitates communication between objects on the screen. The following presents\nthe outline of this approach:\n\n```python\ndef backbutton(x, y):\n    def back(button):\n        Screen.back()\n    Button((x, y), height = 30, font = font14, fontcolor = BLACK, callback = back,\n           fgcolor = CYAN,  text = 'Back', shape = RECTANGLE, width = 80)\n\nclass Screen_0(Screen):\n    def __init__(self):\n        super().__init__()\n        Label((0, 0), font = font14, width = 400, value = 'Test screen')\n        backbutton(390, 242)\nsetup()\nScreen.change(Screen_0)\n```\n\nNote that the GUI is started by issuing `Screen.change` with the class as its\nargument rather than an instance. This assists in multi-screen programs:\nscreens are only instantiated when they are to be displayed. This allows RAM to\nbe reclaimed by the garbage collector when the screen is closed.\n\n## 6.1 Class methods\n\nIn normal use the following methods only are required:  \n * `change` Change screen, refreshing the display. Mandatory positional\n argument: the new screen class name. This must be a class subclassed from\n `Screen`. The class will be instantiated and displayed. Optional keyword\n arguments: `args=[]`, `kwargs={}`. These are arguments for the subclass\n constructor.\n * `back` Restore previous screen.\n * `shutdown` Clear the screen and shut down the GUI.\n * `set_grey_style` Sets the way in which disabled ('greyed-out') objects are\n displayed. The colors of disabled objects are dimmed by a factor and\n optionally desaturated (turned to shades of grey). Optional keyword arguments:\n `desaturate` default `True` and `factor` default 2. A `ValueError` will result\n if `factor` is \u003c= 1. The default style is to desaturate and dim by a factor of\n 2.\n\nOther method:  \n * `get_tft` Return the `TFT` instance. This allows direct drawing to the\n physical screen. Anything so drawn will be lost when the screen is changed. In\n normal use the `TFT` instance is acquired via a GUI object's `tft` property.\n\nSee `screentest.py` and `dialog.py` for examples of multi-screen design.\n\n## 6.2 Constructor\n\nThis takes no arguments.\n\n## 6.3 Callback methods\n\nThese do nothing, and are intended to be defined in subclasses if required.\n\n * `on_open` Called when a screen is displayed.\n * `after_open` Called after a screen has been displayed.\n * `on_hide` Called when a screen ceases to be current.\n\n## 6.4 Method\n\n * `reg_task` args `task`, `on_change=False`. The first arg may be a `Task`\n instance or a coroutine. It is a convenience method which provides for the\n automatic cancellation of tasks. If a screen runs independent coros it can opt\n to register these. On shudown, any registered tasks of the base screen are\n cancelled. On screen change, registered tasks with `on_change` `True` are\n cancelled. For finer control applications can ignore this method and handle\n cancellation explicitly in code.\n\n###### [Jump to Contents](./README.md#contents)\n\n# 7. Display Widgets\n\nThese classes provide ways to display data and are not touch sensitive.\n\n## 7.1 Class Label\n\nDisplays text in a fixed length field. The height of a label is determined\nby the metrics of the specified font.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nKeyword only arguments:  \n * `font` Mandatory. Font object to use.\n * `width` The width of the object in pixels. Default: `None` - width is\n determined from the dimensions of the initial text.\n * `border` Border width in pixels - typically 2. If omitted, no border will be\n drawn.\n * `fgcolor` Color of border. Defaults to system color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `fontcolor` Text color. Defaults to system text color.\n * `value` Initial text. Default: `None`.\n\nMethod:\n * `value` Argument `val` string, default `None`. If provided, refreshes the\n label with the passed text otherwise clears the text in the label.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 7.2 Class Dial\n\nDisplays angles in a circular dial. Angles are in radians with zero represented\nby a vertical pointer. Positive angles appear as clockwise rotation of the\npointer. The object can display multiple angles using pointers of differing\nlengths (e.g. clock face).\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nKeyword only arguments (all optional):  \n * `height` Dimension of the square bounding box. Default 100 pixels.\n * `fgcolor` Color of border. Defaults to system color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `border` Border width in pixels - typically 2. If omitted, no border will be\n drawn.\n * `pointers` Tuple of floats in range 0 to 0.9. Defines the length of each\n pointer as a  proportion of the dial diameter. Default (0.9,) i.e. one pointer\n of length 0.9.\n * `ticks` Defines the number of graduations around the dial. Default 4.\n\nMethod:\n * `value` Arguments: `angle` (mandatory), `pointer` (optional) the pointer\n index. Displays an angle. A `ValueError` will be raised if the pointer index\n exceeds the number of pointers defined by the constructor `pointers` argument.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 7.3 Class LED\n\nDisplays a boolean state. Can display other information by varying the color.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nKeyword only arguments (all optional):\n * `height` Dimension of the square bounding box. Default 30 pixels.\n * `fgcolor` Color of border. Defaults to system color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `border` Border width in pixels - typically 2. If omitted, no border will be\n drawn.\n * `color` The color of the LED. Default RED.\n\nMethods:\n * `value` Argument `val` boolean, default `None`. If provided, lights or\n extinguishes the LED. Always returns its current state.\n * `color` Argument `color`. Change the LED color without altering its state.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 7.4 Class Meter\n\nThis displays a single value in range 0.0 to 1.0 on a vertical linear meter.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nKeyword only arguments:\n * `height` Dimension of the bounding box. Default 200 pixels.\n * `width` Dimension of the bounding box. Default 30 pixels.\n * `font` Font to use in any legends. Default: `None` No legends will be\n displayed.\n * `legends` A tuple of strings to display on the centreline of the meter.\n These should be short to physically fit. They will be displayed equidistantly\n along the vertical scale, with string 0 at the bottom. Default `None`: no\n legends will be shown.\n * `divisions` Count of graduations on the meter scale. Default 10.\n * `fgcolor` Color of border. Defaults to system color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `fontcolor` Text color. Defaults to system text color.\n * `pointercolor` Color of meter pointer. Defaults to `fgcolor`.\n * `value` Initial value to display. Default 0.\n\nMethods:\n * `value` Optional argument `val`. If provided, refreshes the meter display\n with a new value.  \n Range 0.0 to 1.0: out of range values will be constrained to full scale or 0.\n Always returns its current value. \n\n###### [Jump to Contents](./README.md#contents)\n\n## 7.5 Class IconGauge\n\nThis can display any one of a set of icons at a location. The icon to be\ndisplayed can be selected by an integer index. Alternatively a float in range\n0.0 to 1.0 can be displayed: the control shows the nearest icon.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nMandatory keyword only argument:\n * `icon_module` The name of the (already imported) icon file.\n\nOptional keyword only argument:\n * `initial_icon` Default 0. The index of the initial icon to be displayed.\n\nMethods:\n * `icon` Mandatory argument: index of an icon. Displays that icon.\n * `value` Optional argument `val`. Range 0.0 to 1.0. If provided, selects the\n nearest icon and displays it. Always returns the control's current value.\n\n## 7.6 Vector display\n\nProvides a means of displaying one or more vectors. A vector is a `complex`\nwith magnitude in the range of 0 to 1.0. In use a `VectorDial` is instantiated,\nfollowed by a `Pointer` instance for each vector to be displayed on it. The\n`VectorDial` can display its vectors as lines (as on a clock face) or as arrows\n(as on a compass).\n\nBy contrast with the `Dial` class the pointers have lengths and colors which\ncan vary dynamically.\n```python\nfrom micropython_ra8875.widgets.vectors import Pointer, VectorDial\n```\n\n### Class VectorDial\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nKeyword only arguments (all optional):  \n * `height=100` Dimension of the square bounding box.\n * `fgcolor=None` Foreground color. Defaults to system color.\n * `bgcolor=None` Background color of object. Defaults to system background.\n * `border=None` Border width in pixels - typically 2. Default: no border.\n * `ticks=4` Defines the number of graduations around the dial.\n * `arrow=False` If `True` vectors will appear as arrows.\n * `pip=None` By default a small circular \"pip\" is drawn at the centre of the\n dial. If `False` is passed this is omitted. If a color is passed, it will be\n drawn using that color. If the shortest pointer has a length below a threshold\n the \"pip\" is omitted to ensure visibility.\n\n### Class Pointer\n\nConstructor mandatory positional arg:\n * `dial` The dial on which it is to be displayed.\n\nMethod:\n * `value` Args `v=None, col=None`. Returns the current value. If a `complex`\n is passed as the value `v` it is scaled to ensure its magnitude is \u003c= 1 and\n the pointer is redrawn. If a color is passed as `col` the pointer's color is\n updated.\n\n\n###### [Jump to Contents](./README.md#contents)\n\n# 8. Control Widgets\n\nThese classes provide touch-sensitive objects capable of both the display and\nentry of data. If the user moves the control, its value will change and an\noptional callback will be executed. If another control's callback or a task\nalters a control's value, its appearance will change to reflect this.\n\nButtons and checkboxes are provided in two variants, one drawn using graphics\nprimitives, and the other using icons.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.1 Class Slider\n\nThese emulate linear potentiometers. Vertical `Slider` and horizontal\n`HorizSlider` variants are available. These are constructed and used similarly.\nThe short forms (v) or (h) are used below to identify these variants. See the\nnote above on callbacks.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nOptional keyword only arguments:\n * `font` Font to use for any legends. Default `None`: no legends will be\n drawn.\n * `height` Dimension of the bounding box. Default 200 pixels (v), 30 (h).\n * `width` Dimension of the bounding box. Default 30 pixels (v), 200 (h).\n * `divisions` Number of graduations on the scale. Default 10.\n * `legends` A tuple of strings to display near the slider. These `Label`\n instances will be distributed evenly along its length, starting at the bottom\n (v) or left (h).\n * `fgcolor` Color of foreground (the control itself). Defaults to system\n color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `fontcolor` Text color. Defaults to system text color.\n * `slidecolor` Color for the slider. Defaults to the foreground color.\n * `border` Width of border. Default `None`: no border will be drawn. If a\n value (typically 2)\n is provided, a border line will be drawn around the control.\n * `cb_end` Callback function which will run when the user stops touching the\n control.\n * `cbe_args` A list or tuple of arguments for the above callback. Default\n `[]`.\n * `cb_move` Callback function which will run when the user moves the slider or\n the value is changed programmatically.\n * `cbm_args` A list or tuple of arguments for the above callback. Default\n `[]`.\n * `value` The initial value. Default 0.0: slider will be at the bottom (v),\n left (h).\n\nMethods:\n * `greyed_out` Optional boolean argument `val` default `None`. If `None`\n returns the current 'greyed out' status of the control. Otherwise enables or\n disables it, showing it in its new state.\n * `value` Optional arguments `val` (default `None`). If supplied the slider\n moves to reflect the new value and the `cb_move` callback is triggered. The\n method constrains the range to 0.0 to 1.0. Always returns the control's value.\n * `color` Mandatory arg `color` The control is rendered in the selected color.\n This supports dynamic color changes  \n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.2 Class Knob\n\nThis emulates a rotary control capable of being rotated through a predefined\narc.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nOptional keyword only arguments:\n * `height` Dimension of the square bounding box. Default 100 pixels.\n * `arc` Amount of movement available. Default 2*PI radians (360 degrees).\n * `ticks` Number of graduations around the dial. Default 9.\n * `fgcolor` Color of foreground (the control itself). Defaults to system\n color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `color` Fill color for the control knob. Default: no fill.\n * `border` Width of border. Default `None`: no border will be drawn. If a\n value (typically 2) is provided, a border line will be drawn around the\n control.\n * `cb_end` Callback function which will run when the user stops touching the\n control.\n * `cbe_args` A list or tuple of arguments for the above callback. Default\n `[]`.\n * `cb_move` Callback function which will run when the user moves the knob or\n the value is changed.\n * `cbm_args` A list or tuple of arguments for the above callback. Default\n `[]`.\n * `value` Initial value. Default 0.0: knob will be at its most\n counter-clockwise position.\n\nMethods:\n * `greyed_out` Optional boolean argument `val` default `None`. If `None`\n returns the current 'greyed out' status of the control. Otherwise enables or\n disables it, showing it in its new state.\n * `value` Optional argument `val`. If set, adjusts the pointer to correspond\n to the new value. The move callback will run. The method constrains the range\n to 0.0 to 1.0. Always returns the control's value.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.3 Class Checkbox\n\nDrawn using graphics primitives. This provides for boolean data entry and\ndisplay. In the `True` state the control can show an 'X' or a filled block of\ncolor.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nOptional keyword only arguments:\n * `height` Dimension of the square bounding box. Default 30 pixels.\n * `fillcolor` Fill color of checkbox when `True`. Default `None`: an 'X' will\n be drawn.\n * `fgcolor` Color of foreground (the control itself). Defaults to system\n color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `border` Width of border. Default `None`: no border will be drawn. If a\n value (typically 2) is provided, a border line will be drawn around the\n control.\n * `callback` Callback function which will run when the value changes.\n * `args` A list or tuple of arguments for the above callback. Default\n `[]`.\n * `value` Initial value. Default `False`.\n\nMethods:\n * `greyed_out` Optional boolean argument `val` default `None`. If `None`\n returns the current 'greyed out' status of the control. Otherwise enables or\n disables it, showing it in its new state.\n * `value` Optional boolean argument `val`. If the provided value does not\n correspond to the control's current value, updates it; the checkbox is\n re-drawn and the callback executed. Always returns the control's value.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.4 Class Button\n\nDrawn using graphics primitives. This emulates a pushbutton, with a callback\nbeing executed each time the button is pressed. Buttons may be any one of three\nshapes: `CIRCLE`, `RECTANGLE` or `CLIPPED_RECT`.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nMandatory keyword only argument:\n * `font` Font for button text\n\nOptional keyword only arguments:\n * `shape` CIRCLE, RECTANGLE or CLIPPED_RECT. Default CIRCLE.\n * `height` Height of the bounding box. Default 50 pixels.\n * `width` Width of the bounding box. Default 50 pixels.\n * `fill` Boolean. If `True` the button will be filled with the current\n `fgcolor`.\n * `fgcolor` Color of foreground (the control itself). Defaults to system\n color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `fontcolor` Text color. Defaults to system text color.\n * `litcolor` If provided the button will display this color for one second\n after being pressed.\n * `text` Shown in centre of button. Default: an empty string.\n * `callback` Callback function which runs when button is pressed.\n * `args` A list of arguments for the above callback. Default `[]`.\n * `onrelease` Default `True`. If `True` the callback will occur when the\n button is released otherwise it will occur when pressed.\n * `lp_callback` Callback to be used if button is to respond to a long press.\n Default `None`.\n * `lp_args` A list of arguments for the above callback. Default `[]`.\n\nMethod:\n * `greyed_out` Optional boolean argument `val` default `None`. If `None`\n returns the current 'greyed out' status of the control. Otherwise enables or\n disables it, showing it in its new state.\n\nClass variables:\n * `lit_time` Period in seconds the `litcolor` is displayed. Default 1.\n * `long_press_time` Press duration for a long press. Default 1 second.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.5 Class ButtonList emulate a button with multiple states\n\nDrawn using graphics primitives.\n\nA `ButtonList` groups a number of buttons together to implement a button which\nmoves between states each time it is pressed. For example it might toggle\nbetween a green Start button and a red Stop button. The buttons are defined and\nadded in turn to the `ButtonList` object. Typically they will be the same size,\nshape and location but will differ in color and/or text. At any time just one\nof the buttons will be visible, initially the first to be added to the object.\n\nButtons in a `ButtonList` should not have callbacks. The `ButtonList` has its\nown user supplied callback which will run each time the object is pressed.\nHowever each button can have its own list of `args`. Callback arguments\ncomprise the currently visible button followed by its arguments.\n\nConstructor argument:\n * `callback` The callback function. Default does nothing.\n\nMethods:\n * `add_button` Adds a button to the `ButtonList`. Arguments: as per the\n `Button` constructor. Returns the button object.\n * `greyed_out` Optional boolean argument `val` default `None`. If `None`\n returns the current 'greyed out' status of the control. Otherwise enables or\n disables it, showing it in its new state.\n * `value` Optional argument: a button in the set. If supplied and the button\n is not active the currency changes to the supplied button and its callback is\n run. Always returns the active button.\n\nTypical usage is as follows:\n```python\nfrom tft.driver.constants import *\nfrom tft.widgets.buttons import ButtonList\nfrom tft.fonts import font14\n\ndef callback(button, arg):\n    print(arg)\n\ntable = [\n     {'fgcolor' : GREEN, 'shape' : CLIPPED_RECT, 'text' : 'Start', 'args' : ['Live']},\n     {'fgcolor' : RED, 'shape' : CLIPPED_RECT, 'text' : 'Stop', 'args' : ['Die']},\n]\nbl = ButtonList(callback)\nfor t in table: # Buttons overlay each other at same location\n    bl.add_button((10, 10), font = font14, fontcolor = BLACK, **t)\n```\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.6 Class RadioButtons\n\nDrawn using graphics primitives.\n\nThese comprise a set of buttons at different locations. When a button is\npressed, it becomes highlighted and remains so until another button is pressed.\nA callback runs each time the current button is changed.\n\nConstructor positional arguments:\n * `highlight` Color to use for the highlighted button. Mandatory.\n * `callback` Callback when a new button is pressed. Default does nothing.\n * `selected` Index of initial button to be highlighted. Default 0.\n\nMethods:\n * `add_button` Adds a button. Arguments: as per the `Button` constructor.\n Returns the Button instance.\n * `greyed_out` Optional boolean argument `val` default `None`. If `None`\n returns the current 'greyed out' status of the control. Otherwise enables or\n disables it, showing it in its new state.\n * `value` Optional argument: a button in the set. If supplied, and the button\n is not currently active, the currency changes to the supplied button and its\n callback is run. Always returns the currently active button.\n\nTypical usage:\n```python\ndef callback(button, arg):\n    print(arg)\n\ntable = [\n    {'text' : '1', 'args' : ['1']},\n    {'text' : '2', 'args' : ['2']},\n    {'text' : '3', 'args' : ['3']},\n    {'text' : '4', 'args' : ['4']},\n]\nx = 0\nrb = RadioButtons(callback, BLUE) # color of selected button\nfor t in table:\n    rb.add_button((x, 180), font = font14, fontcolor = WHITE,\n                    fgcolor = LIGHTBLUE, height = 40, **t)\n    x += 60 # Horizontal row of buttons\n```\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.7 Class IconButton also checkbox\n\nDrawn using an icon file which must be imported before instantiating. A\ncheckbox may be implemented by setting the `toggle` argument `True` and using\nan appropriate icon file. An `IconButton` instance has a state representing the\nindex of the current icon being displayed. User callbacks can interrogate this\nby means of the `value` method described below.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nMandatory keyword only argument:\n * `icon_module` Name of the imported icon module.\n\nOptional keyword only arguments:\n * `flash` Numeric, default 0. If `value` \u003e 0, button will display icon[1] for\n `value` secs.\n * `toggle` Boolean, default False. If True, each time the button is pressed it\n will display each icon in turn (modulo number of icons in the module).\n * `state` Initial button state (index of icon displayed). Default 0.\n * `callback` Callback function which runs when button is pressed. Default does\n nothing.\n * `args` A list of arguments for the above callback. Default `[]`.\n * `onrelease` Default `True`. If `True` the callback will occur when the\n button is released.\n * `lp_callback` Callback to be used if button is to respond to a long press.\n Default `None`.\n * `lp_args` A list of arguments for the above callback. Default `[]`.\n\nMethods:\n * `greyed_out` Optional boolean argument `val` default `None`. If `None`\n returns the current 'greyed out' status of the control. Otherwise enables or\n disables it. If greyed out, the button is displayed with colors dimmed.\n * `value` Argument `val` default `None`. If the argument is provided and is a\n valid index not corresponding to the current button state, changes the button\n state and displays that icon. The callback will be executed. Always returns\n the button state (index of the current icon being displayed).\n\nClass variables:\n * `long_press_time` Press duration for a long press. Default 1 second.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.8 Class IconRadioButtons\n\nDrawn using an icon file which must be imported before instantiating. These\ncomprise a set of buttons at different locations. When initially drawn, all but\none button will be in state 0 (i.e. showing icon[0]). The selected button will\nbe in state 1. When a button in state 0 is pressed, the set of buttons changes\nstate so that it is the only one in state 1 (showing icon[1]). A callback runs\neach time the current button changes.\n\nConstructor positional arguments:\n * `callback` Callback when a new button is pressed. Default does nothing.\n * `selected` Index of initial button to be highlighted. Default 0.\n\nMethods:\n * `add_button` Adds a button to the set. Arguments: as per the `IconButton`\n constructor. Returns the button instance.\n * `value` Argument `val` default `None`. If the argument is provided which is\n an inactive button in the set, that button becomes active and the callback is\n executed. Always returns the button which is currently active.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.9 Class Listbox\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nMandatory keyword only arguments:\n * `font`\n * `elements` A list or tuple of strings to display. Must have at least one\n entry.\n\nOptional keyword only arguments:\n * `width` Control width in pixels, default 250.\n * `value` Index of currently selected list item. Default 0.\n * `border` Space between border and contents. Default 2 pixels. If `None` no\n border will be drawn.\n * `fgcolor` Color of foreground (the control itself). Defaults to system\n color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `fontcolor` Text color. Defaults to system text color.\n * `select_color` Background color for selected item in list. Default\n `LIGHTBLUE`.\n * `callback` Callback function which runs when a list entry is picked.\n * `args` A list of arguments for the above callback. Default `[]`.\n\nMethods:\n * `value` Argument `val` default `None`. If the argument is provided which is\n a valid index into the list that entry becomes current and the callback is\n executed. Always returns the index of the currently active entry.\n * `textvalue` Argument `text` a string default `None`. If the argument is\n provided and is in the control's list, that item becomes current. Returns the\n current string, unless the arg was provided but did not correspond to any list\n item. In this event the control's state is not changed and `None` is returned.\n\nThe callback is triggered whenever a listbox item is pressed, even if that item\nis already currently selected.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 8.10 Class Dropdown\n\nA dropdown list. The list, when active, is drawn below the control. The height\nof the control is determined by the height of the font in use.\n\nConstructor mandatory positional argument:\n 1. `location` 2-tuple defining position.\n\nMandatory keyword only arguments:\n * `font`\n * `elements` A list or tuple of strings to display. Must have at least one\n entry.\n\nOptional keyword only arguments:\n * `width` Control width in pixels, default 250.\n * `value` Index of currently selected list item. Default 0.\n * `fgcolor` Color of foreground (the control itself). Defaults to system\n color.\n * `bgcolor` Background color of object. Defaults to system background.\n * `fontcolor` Text color. Defaults to system text color.\n * `select_color` Background color for selected item in list. Default\n `LIGHTBLUE`.\n * `callback` Callback function which runs when a list entry is picked.\n * `args` A list of arguments for the above callback. Default `[]`.\n\nMethods:\n * `value` Argument `val` default `None`. If the argument is provided which is\n a valid index into the list that entry becomes current and the callback is\n executed. Always returns the index of the currently active entry.\n * `textvalue` Argument `text` a string default `None`. If the argument is\n provided and is in the control's list, that item becomes current. Returns the\n current string, unless the arg was provided but did not correspond to any list\n item. In this event the control's state is not changed and `None` is returned.\n\nThe callback is triggered if an item on the dropdown list is touched and that\nitem is not currently selected (i.e. when a change occurs).\n\n###### [Jump to Contents](./README.md#contents)\n\n# 9. Dialog Boxes\n\nIn general `Screen` objects occupy the entire physical display. The principal\nexception to this is modal dialog boxes: these are rendered in a window which\naccepts all touch events until it is closed. Dialog boxes are created by\ninstantiating an `Aperture` which is a `Screen` superclass. In effect this is a\nwindow, but a 'micro' implementation lacking chrome beyond a simple border and\noccupying a fixed location on the screen.\n\nIn use the user program creates a class subclassed from `Aperture`. This is\npopulated in the same way as per `Screen` subclasses. The class name can then\nbe passed to `Screen.change` to invoke the dialog box. The GUI provides a\nsimple way to build dialog boxes based on a small set of pushbuttons such as\n'Yes/No/Cancel' in the form of the `DialogBox` class.\n\nA convenience method `locn` is provided to assist in populating dialog boxes.\nGiven coordinates relative to the dialog box, it provides an absolute\n`location` 2-tuple suitable as a constructor argument for `control` or\n`display` classes. See `dialog.py` for example usage.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 9.1 Class Aperture\n\nProvides a window for objects in a modal dialog box.\n\nConstructor mandatory positional args:  \n 1. `location` 2-tuple defining the window position.\n 2. `height` Dimensions in pixels.\n 3. `width`\n\nOptional keyword only args:  \n * `draw_border` Boolean, default `True`. If set a single pixel window border\n will be drawn.\n * `bgcolor`  Background color of window. Defaults to system background.\n * `fgcolor` Color of border. Defaults to system foreground.\n\nInstance variables:  \n * `location` 2-tuple defining the window position.\n * `height` Dimensions in pixels.\n * `width`\n\nMethod:\n * `locn` Args: x, y. Returns an absolute location 2-tuple given a pair of\n coordinates relative to the dialog box.\n\nClass method:  \n * `value` Optional arg `val` default `None`. Provides a mechanism for\n returning the outcome of a dialog box which can be queried by the calling\n object. If the arg is provided, the value is set. The arg may be any Python\n object. Returns the value of the `Aperture` class. The calling `Screen` can\n query this by implementing an `on_open` method which calls `Aperture.value()`.\n\n###### [Jump to Contents](./README.md#contents)\n\n## 9.2 Class DialogBox\n\nSimplifies building simple dialog boxes based on a set of pushbuttons. Any\nbutton press will close the dialog. The caller can determine which button was\npressed. The size of the buttons and the width of the dialog box are calculated\nfrom the strings assigned to the buttons. This ensures that buttons are evenly\nspaced and identically sized.\n\nConstructor mandatory positional args:\n 1. `font` The font for buttons and label.\n \nOptional keyword only args:  \n * `elements` A list or tuple of 2-tuples. Each defines the text and color of a\n pushbutton, e.g. `(('Yes', RED), ('No', GREEN))`.\n * `location` 2-tuple defining the dialog box location. Default (20, 20).\n * `label` Text for an optional label displayed in the centre of the dialog\n box. Default `None`.\n * `bgcolor` Background color of window. Default `DARKGREEN`.\n * `buttonwidth` Minimum width of buttons. Default 25. In general button\n dimensions are calculated from the size of the strings in `elements`.\n * `closebutton` Boolean. If set, a `close` button will be displayed at the top\n RH corner of the dialog box.\n\nPressing any button closes the dialog and sets the `Aperture` value to the text\nof the button pressed or 'Close' in the case of the `close` button.\n\n###### [Jump to Contents](./README.md#contents)\n\n# 10. Developer Notes\n\nFor developers wishing to extend the library with new controls or displays, see\nthis [reference](./DEVELOPER.md).\n\n###### [Jump to Contents](./README.md#contents)\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Display"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterhinch%2Fmicropython-tft-gui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeterhinch%2Fmicropython-tft-gui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterhinch%2Fmicropython-tft-gui/lists"}