ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

DOC: start a documentation page with coding policies for the UI-Layer

Browse source
This commit is contained in:
Fischlurch 2018-08-31 17:41:42 +02:00
parent 17bcdd952a
commit 1f98895a89
2 changed files with 62 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
doc/technical/gui/CodePolicy.txt Normal file
View file

@ -0,0 +1,59 @@
Coding Policies within UI-Layer
===============================
NOTE: for the time being, this is a loose collection of
Conventions and Policies deemed adequate for work
on the Lumiera UI-Layer
Architecture
------------
The UI is loaded as Plug-In, which instantiates a `GtkLumiera` object.
All of the UI activity happens within the blocking function `GtkLumiera::run()`.
This UI activity boils down to run the GTK event loop; we use a dedicated thread,
and all of the GUI thus performs single-threaded and need not be thread-safe.
All UI activities thus need to be short running and with deterministic outcome.
It is strictly prohibited to spawn other threads from within the event loop.
We hold up a strict distinction between the _UI mechanics_ and the _core editing
concerns_. The latter _must not be implemented within the UI-Layer._ Rather, you need
to send an `act(CommandID)` message over the UI-Bus, which causes the corresponding
Proc-Layer command script to be dispatched within the Session thread. It is good
practice to give an immediate visual clue regarding the fact of sending such
a command (e.g. pressing a button). But be prepared that the actual feedback
of invoking a command happens asynchronously.
UI-Model
~~~~~~~~
In short: _there is no dedicated UI-Model._ Stateful working data goes directly
into the widgets. However, some widgets or controllers are special, insofar they
correspond to and reflect some entities within the _Session model._ These special
entities must be implemented as subclasses of `gui::model::Tangible`. These are
always connected to the UI-Bus, and they are populated and mutated by receiving
diff messages pushed up from the Proc-Layer.
There is an _inner circle_ of UI backbone services. These are all mutually dependent
on each other and their start-up sequence is intricate. Implement global and cross-cutting
concerns here. In case some widget or controller needs access to such a service, then you
should prefer using `lib::Depend<ServiceInterface>`, and install the corresponding service
via `lib::DependInject<ServiceInterface>::ServiceInstance<ServiceImpl>`.
Code organisation
-----------------
GTK is massive and compilation times tend to be problematic in the UI-Layer.
Thus you should be diligent with the organisation of includes. Try to confine the
more heavyweight includes within the implementation translation units. Use forward
declarations and PImpl if possible. However, it is fine to write a mere implementation
widget in header-only fashion, in case this improves the locality and readability of code.
NOTE: `using namespace Gtk` and similar wildcard includes are prohibited.
We are forced to observe a tricky include sequence, due to NoBug's `ERROR` macro,
and also in order to get I18N right.
Thus any actual translation unit should ensure that effectively the first include
is that of 'gui/gtk-base.hpp'.footnote:[you need not include it literally. It is
perfectly fine if you can be sure the first included header somehow drags in
'gtk-base.hpp' before any other header.]

4
doc/technical/gui/guiTheme.txt
View file

@ -1,8 +1,10 @@
Lumiera GUI style and theming
=============================
//Menu: label Theme/Style
_this page collects some pieces of information regarding the visual appearance of the Lumiera GTK UI_
'this page collects some pieces of information regarding the visual appearance of the Lumiera GTK GUI'
GTK-3 styles
------------