diff --git a/src/gui/controller/controller.hpp b/src/gui/controller/controller.hpp index 82050a2aa..7ccd435b7 100644 --- a/src/gui/controller/controller.hpp +++ b/src/gui/controller/controller.hpp @@ -20,8 +20,10 @@ */ -/** @file controller/controller.hpp - ** This file contains the definition of the controller object +/** @file controller.hpp + ** The top level UI controller. + ** + ** @todo as of 1/2015, this needs to be reshaped ////////////////////TICKET #959 */ @@ -40,6 +42,9 @@ class Project; namespace controller { +/** + * @todo needs to be reshaped for communication with Proc-Layer /////////////////TICKET #959 + */ class Controller { public: diff --git a/src/gui/gtk-lumiera.cpp b/src/gui/gtk-lumiera.cpp index 1b587dc3e..61160e15a 100644 --- a/src/gui/gtk-lumiera.cpp +++ b/src/gui/gtk-lumiera.cpp @@ -84,6 +84,9 @@ GtkLumiera::application() +/** + * @remarks this function blocks until shutdown of the UI + */ void GtkLumiera::main (int argc, char *argv[]) { diff --git a/src/gui/gtk-lumiera.hpp b/src/gui/gtk-lumiera.hpp index d1ab75199..e451537d4 100644 --- a/src/gui/gtk-lumiera.hpp +++ b/src/gui/gtk-lumiera.hpp @@ -68,7 +68,7 @@ using std::shared_ptr; /* ====== The Application Class ====== */ /** - * The main application class. + * Top level entry point: The Lumiera GTK UI. */ class GtkLumiera : boost::noncopyable @@ -83,6 +83,7 @@ class GtkLumiera + /** start up the GUI and run the event thread */ void main(int argc, char *argv[]); WindowManager& windowManager(); diff --git a/src/gui/model/project.hpp b/src/gui/model/project.hpp index 8074d9f86..363c73544 100644 --- a/src/gui/model/project.hpp +++ b/src/gui/model/project.hpp @@ -22,7 +22,10 @@ /** @file project.hpp ** This file contains the definition of Project, a class which - ** stores project data, and wraps proc layer data + ** stores project data, and wraps proc layer data. + ** + ** @todo this solution was used to build the first outline of the UI. + ** It needs to be reshaped into a connector to Proc-Layer ///////////////TICKET #959 */ #ifndef PROJECT_HPP @@ -35,6 +38,9 @@ namespace gui { namespace model { +/** + * @deprecated 1/2015 see TICKET #959 + */ class Project { public: diff --git a/wiki/renderengine.html b/wiki/renderengine.html index e0ec56005..9e2054696 100644 --- a/wiki/renderengine.html +++ b/wiki/renderengine.html @@ -2282,7 +2282,7 @@ Thus, the Proc-Layer exposes (one or several) facade interfaces for the GUI to u Probably the most important aspect regarding the GUI integration is how to get [[access to and operate on the Session|SessionInterface]]. More specifically, this includes [[referring to individual objects|MObjectRef]]. On top of these generic access mechanisms, we create a [[proxy GUI model|GuiModel]] for binding. The interface of this GUI model is tailored for display and translation into UI entities. -
+
Building a layered architecture is a challenge, since the lower layer //really// needs to be self-contained, while prepared for usage by the higher layer.
 A major fraction of all desktop applications is written in a way where operational logic is built around the invocation from UI events -- what should be a shell turns into a backbone. One possible way to escape from this common anti pattern is to introduce a mediating entity, to translate between two partially incompatible demands and concerns: Sure, the "tangible stuff" is what matters, but you can not build any significant piece of technology if all you want is to "serve" the user.
 
@@ -2293,10 +2293,10 @@ The GUI model is largely comprised of immutable ID elements, which can be treate
 !synchronisation guarantees
 We acknowledge that the gui model is typically used from within the GUI event dispatch thread. This is //not// the thread where any session state is mutated. Thus it is the responsibility of this proxying model within the GUI to ensure that the retrieved structure is a coherent snapshot of the session state. Especially the {{{gui::model::SessionFacade}}} ensures that there was a read barrier between the state retrieval and any preceding mutation command. Actually, this is implemented down in Proc-Layer, with the help of the ProcDispatcher.
 
-Forwarding the model changes to the GUI widgets is another concern, since notifications from session mutations arrive asynchronous after each [[Builder]] run. In this case, we send a notification to the widgets registered as listeners, but wait for //them// to call back and fetch the [[diffed state|TreeDiffModel]]. This callback will be scheduled by the  widgets to perform in the GUI event  thread.
+The forwarding of model changes to the GUI widgets is another concern, since notifications from session mutations arrive asynchronous after each [[Builder]] run. In this case, we send a notification to the widgets registered as listeners, but wait for //them// to call back and fetch the [[diffed state|TreeDiffModel]]. This callback will be scheduled by the  widgets to perform in the GUI event  thread.
-
+
Considerations regarding the [[structure of custom timeline widgets|GuiTimelineWidgetStructure]] highlight again the necessity of a clean separation of concerns and an "open closed design". For the purpose of updating the timeline(s) to reflect the HighLevelModel in Proc-Layer, several requirements can be identified
 * we need incremental updates: we must not start redrawing each and everything on each tiny change
 * we need recursive programming, since this is the only sane way to deal with tree like nested structures.
@@ -2315,7 +2315,7 @@ Hereby we introduce a new in-layer abstraction.
 * It performs in the GTK event thread.
 * no synchronisation is necessary
 * use constant values as far as possible
-* the UI bus is offered by the GUI model.
+* the UI bus is offered by the GuiModel.
 * it is //owned// by the GUI model.
 * there is a global "kill switch". If toggled "off" any invocation is NOP.
 * thus there is no need for any ownership or resource tracking