diff --git a/doc/technical/gui/CodePolicy.txt b/doc/technical/gui/CodePolicy.txt index cc1fa7cf4..dbf547ad9 100644 --- a/doc/technical/gui/CodePolicy.txt +++ b/doc/technical/gui/CodePolicy.txt @@ -1,5 +1,6 @@ Coding Policies within UI-Layer =============================== +:Toc: NOTE: for the time being, this is a loose collection of Conventions and Policies deemed adequate for work @@ -40,6 +41,40 @@ should prefer using `lib::Depend`, and install the correspondi via `lib::DependInject::ServiceInstance`. +Behaviour patterns +------------------ + +Parent Containers +~~~~~~~~~~~~~~~~~ +A _Parent Container_ is an object managing a collection of children, with respect to +the structure of _tangible UI elements._ Irrespective if this container is also a +`Gtk::Container` widget, or ``just'' a controller. The key point to turn something +into a _Parent Container_ is the fact that this entity creates the children +in response to a (population) diff message. + +.Responsibilities +- a _Parent Container_ has to wire each child properly, so to enable the adequate + use of the UI element protocol. This includes + + ** to ensure the child is attached to the UI-Bus (usually enforced by ctor call) + ** to install a suitable `Expander` functor if the child supports expand/collapse + ** to install a suitable `Revealer` when it is relevant for the child to be brought + into sight in response to some message (e.g. to indicate error state). + +- whenever a child is detached from the container, you need to _ensure it is destroyed_ + right away, before there is any chance of processing some other UI event.footnote:[ + Invoking the destructor triggers a lot of magic here, especially it causes the child + to be properly detached from signals. We want to ensure this happens as soon as the + child is taken out of service. Do not use an ``can collect garbage later'' approach.] + +Error handling +~~~~~~~~~~~~~~ +Be aware that GTK is written in C. And while GTKmm has some safeguards in place, +better be sure no exception can emanate from event handling code. + +WARNING: [red]#TODO#: probably we'll need a common wrapper to do so... + + Code organisation ----------------- GTK is massive and compilation times tend to be problematic in the UI-Layer. diff --git a/src/gui/model/expander-revealer.hpp b/src/gui/model/expander-revealer.hpp new file mode 100644 index 000000000..d61fc3857 --- /dev/null +++ b/src/gui/model/expander-revealer.hpp @@ -0,0 +1,93 @@ +/* + EXPANDER-REVEALER.hpp - functor components for standard UI element actions + + Copyright (C) Lumiera.org + 2018, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + + +/** @file expander-revealer.hpp + ** Helper components to implement some standard UI-element actions by installing a functor. + ** + ** ## Interactions + ** + ** @see [UI-Element protocol](\ref tangible.hpp) + ** @see \ref BusTerm_test + ** + */ + + +#ifndef GUI_MODEL_EXPANDER_REVEALER_H +#define GUI_MODEL_EXPANDER_REVEALER_H + + +#include "lib/error.hpp" +//#include "lib/idi/entry-id.hpp" +//#include "lib/symbol.hpp" + +#include +//#include +//#include + + +namespace gui { +namespace model { + +// using std::string; +// using lib::Symbol; + + + /** + * Functor component to support the default implementation of expanding/collapsing. + */ + class Expander + { + public: + protected: + + + Expander() + { } + + public: + + protected: + }; + + + /** + * Functor component to support the default implementation of revealing an UI-Element. + */ + class Revealer + { + public: + protected: + + + Revealer() + { } + + public: + + protected: + }; + + + +}} // namespace gui::model +#endif /*GUI_MODEL_EXPANDER_REVEALER_H*/ diff --git a/src/gui/model/tangible.hpp b/src/gui/model/tangible.hpp index 393ba06b7..9ca3c0c99 100644 --- a/src/gui/model/tangible.hpp +++ b/src/gui/model/tangible.hpp @@ -105,7 +105,7 @@ ** - **act**: send a \ref GenNode representing the action ** - **note**: _send_ a GenNode representing the _state mark_ ** - **mark**: _receive_ a GenNode representing the _feedback,_ a replayed _state mark_ or _generic message._ - ** - **diff**: ask to retrieve a diff, which + ** - **diff**: prompt the element to retrieve a diff, which ** - either is an incremental status update ** - or is a from-scratch reconfiguration ** @@ -133,6 +133,7 @@ #include "lib/error.hpp" #include "lib/nocopy.hpp" #include "gui/ctrl/bus-term.hpp" +#include "gui/model/expander-revealer.hpp" #include "lib/diff/diff-mutable.hpp" #include "lib/idi/entry-id.hpp" #include "lib/symbol.hpp" diff --git a/wiki/thinkPad.ichthyo.mm b/wiki/thinkPad.ichthyo.mm index 0d18cd4e4..f3f2a9ee7 100644 --- a/wiki/thinkPad.ichthyo.mm +++ b/wiki/thinkPad.ichthyo.mm @@ -1789,15 +1789,15 @@

der Parent-Container ist für das expand/collapse zuständig

- - + + - + @@ -1908,10 +1908,38 @@ + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + @@ -1966,13 +1994,25 @@ + + + + + - + - + + + + + + + + @@ -18544,17 +18584,97 @@ - - + + - - - - + + + + + + +

+ nicht bool-Testbar +

+ + + + + + + + +

+ ganz bewußt verzichten wir darauf, +

+

+ festzustellen, ob ein Kind gegenwärtig zugänglich (revealed) ist. +

+

+ Denn dies auf dem API zu exponieren bringt keinen Mehrwehrt. +

+

+ Letztlich ist das ein lokales Detail des Layout-Managers. +

+

+ +

+

+ Es ist nicht Sache des client-Codes, auf einem Widget ein anderes Verhalten auszulösen, +

+

+ wenn es nicht sichtbar ist. Denn Sichtbarkeit gehört zur UI-Mechanik und geht den Client nix an +

+ + + - - + + + + + + + + + + + + + + + + + + + +

+ ...denn dort fehlt noch die konkrete Implementierung, +

+

+ welche die Monaden-Baum-Repräsentation schließlich +

+

+ auf konkrete Widgets abbildet. Das ist viel Arbeit, und es ließe sich vereinfachen, +

+

+ wenn für gewisse Knoten erkannt werden kann, daß sie einen NavScope darstellen; +

+

+ denn dann gäbe es eine Implementierung "von der Stange" +

+ + + + + + + + + + + @@ -18562,8 +18682,26 @@ + + + + + + +

+ aber die Operationen sind der Sache nach nicht symmetrisch +

+ + + + - + + + + + + @@ -18602,40 +18740,75 @@ + + + + + + + + - - - - + + + + + + + + + + + + + + - - + + + + + - - - - - - -

- ...denn dort fehlt noch die konkrete Implementierung, -

-

- welche die Monaden-Baum-Repräsentation schließlich -

-

- auf konkrete Widgets abbildet. Das ist viel Arbeit, und es ließe sich vereinfachen, -

-

- wenn für gewisse Knoten erkannt werden kann, daß sie einen NavScope darstellen; -

-

- denn dann gäbe es eine Implementierung "von der Stange" -

- - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +