# LOMIRI NOTIFICATIONS - EXAMPLES


## GOALS

This is a collection of short Python programs demonstrating
the use of Lomiri notifications and the compatibility with the Freedesktop standard.

Note that these scripts can be run on e.g. a standard UT phone
without modifications - a Fairphone 5 running 24.04-1.1 stable has
been used.

Disclaimer - these tests are intended to help developers understand notifications.
Although they can run in a normal environment, they may interfere with it.
After using them, it may be necessary to reboot the phone to get back to normal use.
Don't use them if you are waiting for an urgent call.


## HOW TO USE

Most of these scripts use notify2, a deprecated replacement of the vanished
pynotify library used in the original Ubuntu version.

https://bitbucket.org/takluyver/pynotify2

Since the Python3 version installed with UT does not support pip when called
normally from the command line, installing notify2 the standard way (`python3 -m pip install notify2`)
is not easy if at all possible.

Instead, it's easier to download the source from

https://bitbucket.org/takluyver/pynotify2/downloads/

extract `notify.py` and 'install' it manually. The simple way is to copy
the `notify.py` file to the script directory (the one where this file is).
As Python's `sys.path` includes the current directory, this will work
if the current directory is the one where the scripts are.

To run a script, `normal-urgency.py` for example, use:

```
python3 normal-urgency.py
```

The notification should appear at the top of the phone screen and
disappear after a few seconds.
Some scripts have more complicated user interactions.

--> The `example.py` is a library of common functions and is not
a test file, don't try to launch it directly.

3 tests...

  * `sd-example-password-entry.py`,
  * `sd-example-user-auth.py` and
  * `sd-example-simunlock.py`

... do not use pynotify2 but instead Notify, the GObject implementation.
They will start only if the Notify.typelib (and the GdkPixbuf-2.0 .typelib on
which it depends) can be found; if the UT version you use doesn't have them,
they can be extracted from the archives:

  *  `gir1.2-gdkpixbuf-2.0_2.42.10+dfsg-3ubuntu3.2_arm64.deb`
  *  `gir1.2-notify-0.7_0.8.3-1build2_arm64.deb` -> Notify-0.7.typelib

Place them into a directory and add them to the path with:

```
export GI_TYPELIB_PATH=/home/phablet/typelibs
```

`sd-example-simunlock.py` can make you believe that your phone rebooted!
The PIN entry you see when run is a fake.

The tests under `./unsupported` have been modernized but they
mostly don't work.

Note that since the library triggers notifications via DBus and doesn't
interfere directly with the phone screen, it is possible to run them
from an ssh session and the notifications will appear on the phone screen
(any acknowledgment of the alarms has to be done on the phone itself).

The `trigger_sds.sh` script demonstrates how multiple concurrent notifications overlay
on the phone's screen when not acknowledged fast enough.


## UNDER THE HOOD

These scripts are calling into the DBus system via the DBus Python module
(included in the system Python installation).
The DBus calls are received by Lomiri (the shell) that uses libnotify (a
standard glib2.0-based library also used in other desktop environments) to
handle them.
