Hacking on UI¶
If you want to change the way ZPUI looks and behaves for you, make a better UI for your application by using more graphics or even design your own UI elements, these directions will help you on your way.
Using the ZPUI emulator¶
ZPUI has an emulator that will allow you to test your applications, UI tweaks and ZPUI logic changes, so that you don’t have to have a ZeroPhone to develop and test your UI.
It will require a Linux computer with a graphical interface running (X forwarding might work, too) and Python 2.7 available. Here are the setup and usage instructions.
Tweaking how the UI looks¶
ZPUI allows you to modify the way UI looks. The main way is tweaking UI element “views” ( a view object defines the way an UI element is displayed ). So, you can change the look of a certain UI element (say, main ZPUI menu), or a group of elements (like, force a certain view for all checkboxes). You can also define your own views, then apply them to UI elements using the same method. To know more about it, read here.
If your needs aren’t covered by this, feel free to modify the ZPUI code - it strives to be straightforward, and the parts that aren’t are either covered with comments and documentation, or will be covered upon request. If you need assistance, contact us on IRC or email!
Modifying ZPUI code directly might result in merge conflicts if you will update using
git pull, or the built-in “Update ZPUI” app. Again, please do consider opening an issue on GitHub proposing your changes to be included in the mainline =)
Making and modifying UI elements¶
If existing UI elements do not cover your usecase, you can also make your own UI elements! Contact us to find out how, or just use the code for existing UI elements as guidelines if you feel confident.
Attaching to the ZPUI instance¶
In case where you need to debug some hiccup or simulate some condition in the
framework itself, you can attach to the ZPUI instance and debug the framework’s
behaviour. This will not allow you to debug individual apps, however,
if you need to attach to an app, you can modify its code in the same way that ZPUI
main.py itself was modified.
First, you need to install
python-rfoo from Debian repositories, if it’s not
installed already. ZeroPhone SD card images will have it installed by default,
otherwise, here’s how you do it:
sudo apt install python-rfoo
If you don’t yet have it installed, it can be done any time before actually launching the debug console. Then, find PID of the current ZPUI instance:
ps ax|grep python
You might have multiple entries, one of them will look like “python main.py”, get the PID from it. PID is the process number, which in our case is likely going to be from 3 to 5 digits long. Once you have the PID number, signal ZPUI to launch the console:
kill -USR2 74856(where
74856is your PID number)
Then, launch a Python interpreter and run the following commands:
from rfoo.utils import rconsole rconsole.interact(port=9377)
pi@zerophone-prototype:~ $ python Python 2.7.13 (default, Sep 26 2018, 18:42:22) [GCC 6.3.0 20170516] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from rfoo.utils import rconsole >>> rconsole.interact(port=9377) Python 2.7.13 (default, Sep 26 2018, 18:42:22) [GCC 6.3.0 20170516] on linux2 Type "help", "copyright", "credits" or "license" for more information. (ProxyConsole) >>>
Tab completion is supported, and don’t be afraid to use
dir() to find out more
TODO: move this into
debugging.rst is brought up to date.
Testing the UI¶
There are two ways to test UI elements:
1. Running existing tests¶
There’s a small amount of tests, they’re being added when bugs are found,
sometimes also when features are added. From
run existing tests like:
python -m unittest TEST_FILENAME(without .py at the end)
For example, try:
python -m unittest test_checkbox
2. Running example applications¶
There are example applications available for you to play with UI elements. You can run ZPUI in single-app mode to try out any UI element before using it:
python main.py -a apps/example_apps/checkbox_test
You can also, of course, use the code from example apps as a reference when developing your own applications.
Contributing your changes¶
Send us a pull request! If your changes affect the UI element logic, please try and make a test that checks whether it really works. If you’re adding a new UI element, add docstrings to it - describing purpose, args and kwargs, as well as an example application to go with it.