1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
Title: Getting started with Phosh development
Slug: gettingstarted
# Getting started with Phosh development
## Overview
Phosh is a graphical shell for
[Wayland](https://wayland.freedesktop.org/). It's target at mobile
devices with small screens like Purism's Librem 5 running adaptive
[GNOME](https://gitlab.gnome.org/) applications.
It's purpose is to provide a graphical user interface to launch
applications, display status information (time, battery status, ...),
to provide a lock screen and to make often used functionality quickly
accessible. It's also meant to provide a proper interface when either
connecting a keyboard and monitor to a phone or (but to a lesser
extend) when running on a laptop.
Since it acts as a Wayland client it needs a compositor to function
that provides the necessary protocols (most notably
wlr-layer-shell). It's usually used with
[phoc](https://gitlab.gnome.org/World/Phosh/phoc) (the PHOne Compositor).
On the GNOME side it interfaces with the usual components
(e.g. [gnome-settings-daemon](https://gitlab.gnome.org/GNOME/gnome-settings-daemon),
[upower](https://gitlab.freedesktop.org/upower/upower),
[iio-sensor-proxy](https://gitlab.freedesktop.org/hadess/iio-sensor-proxy/))
via DBus. For haptic feedback it uses
[feedbackd](https://source.puri.sm/Librem5/feedbackd/).
It uses [GTK](https://www.gtk.org/) as it's GUI toolkit and
[libhandy](https://gitlab.gnome.org/GNOME/libhandy) for adaptive
widgets.
Although targeted at touch devices Phosh does not implement a
on screen keyboard (OSK) but leaves this to separate on-screen
keyboards like [stevia](https://gitlab.gnome.org/World/Phosh/stevia)
or [squeekboard](https://gitlab.gnome.org/World/Phosh/squeekboard).
The above combination of software is also often (a bit imprecisely)
named Phosh. For a high level overview see [Phosh Overview](https://honk.sigxcpu.org/con/phosh_overview.html).
### Wayland protocols
Since Phoc (in contrast to some other solutions) aims to be a minimal
Wayland compositor that manages rendering, handle physical and virtual
input and display devices but not much more it needs to provide some
more protocols to enable graphical shells like Phosh. These are usually
from [wlr-protocols](https://github.com/swaywm/wlr-protocols) and
Phoc uses the [wlroots](https://github.com/swaywm/wlroots) library for
implementing them.
These are the most prominent ones use by Phosh:
- wlr-layer-shell: Usually Wayland clients have little influence on where
the compositor places them. This protocol gives Phosh enough room
to build the top bar via #PhoshTopPanel, the home bar #PhoshHome at
the bottom, system modal dialogs e.g. #PhoshSystemPrompt and
lock screens via #PhoshLockscreen.
- wlr-foreign-toplevel-management: This allows the management of
toplevels (windows). Phosh uses this to build an application switcher
called #PhoshOverview.
- wlr-output-management: This allows to manage a monitors power
state (to e.g.turn it off when unused).
Besides those Phosh uses a number of "regular" Wayland client
protocols like `xdg_output`, `wl_output` or `wl_seat` (see
`PhoshWayland` for the full list).
### Session startup
Since Phosh is in many aspects a regular GTK application it's started
as part GNOME session so the start sequence looks like
```
phoc (compositor) -> gnome-session -> phosh (and other session components)
```
## Running and Testing Phosh
The following might useful when you want to make changes to Phosh and
test the changes:
### Running phosh
For development purposes you can run phosh nested on your desktop. See
[this blog post](https://phosh.mobi/posts/phosh-dev-part-0/) for
details. You can use several helper scripts to test the running
instance:
### Checking DBus Interfaces
The `tools/` directory contains short snippets to test various DBus interfaces
e.g. `check-osd` to test the OSD overlay (`PhoshOsdWindow`) or `check-screenshot`
to check the screenshot API (`PhoshScreenshotManager`).
### Mocking DBus Services
To mock DBus services used by phosh like `org.freedesktop.ModemManager`
or `net.hadess.SensorProxy` you can use [python-dbusmock][].
`tests/mock-mm-nm.py` uses this to mock `ModemManager` and
`NetworkManager` to simulate a mobile data connection:
```
sudo tests/mock-mm-nm.py
```
Make sure you stop `ModemManager` and `NetworkManager` before running
the above.
You can also use the mocks from `python-dbusmock` directly, e.g. to mock
settings daemon's rfkill state:
```
python3 -m dbusmock --template gsd_rfkill
```
to e.g. mock `gsd-rfkill`. To simulate airplane mode you could use:
```
gdbus call --session -d org.gnome.SettingsDaemon.Rfkill \
-o /org/gnome/SettingsDaemon/Rfkill \
-m org.freedesktop.DBus.Mock.SetAirplaneMode true
```
### GTK Inspector
Since phosh is a GTK application you can use
[GtkInspector](https://developer.gnome.org/documentation/tools/inspector.html).
You can use the `GTK_INSPECTOR_DISPLAY` environment variable to use a different
Wayland display for the inspector window. This can be useful to have the
inspector windows outside of a nested Wayland session.
## Development Hints
### Manager Objects
Phosh uses several manager objects e.g. `PhoshBackgroundManager`,
`PhoshMonitorManager`, `PhoshLockscreenManager` to keep track
of certain objects (monitors, lock screens, backgrounds) and to
trigger events on those when needed. They're usually created and
disposed by #PhoshShell. Some of them like
`PhoshWayland` are singletons so you can access them from basically
anywhere in the codebase.
### Status Information Widgets
Several widgets listen to changes on DBus objects in order to e.g. display the
current connectivity - see #PhoshConnectivityInfo for an example that monitors
network connectivity.
Sometimes it is no longer useful to show the widget (since
e.g. the corresponding DBus service went away). In that case the
widget should flip a boolean property so the parent container can
hide the object via #g_object_bind_property().
### Screen Locking and Blanking
For details see PhoshScreenSaverManager.
[python-dbusmock]: https://github.com/martinpitt/python-dbusmock
|
