Timeline: pick up work on the track drawing logic

...there was a long intermission, first caused by some contribution to Yoshimi,
then by a private project related to Kubernetes

src/stage/timeline/body-canvas-widget.cpp

@@ -170,12 +170,12 @@ namespace timeline {
   void
   TimelineCanvas::drawGrounding (Cairo::RefPtr<Cairo::Context> const& cox)
   {
-    /////////////////////////////////////////////TICKET #1139 : placeholder drawing
+    /////////////////////////////////////////////TICKET #1039 : placeholder drawing
     cox->set_source_rgb(0.8, 0.0, 0.0);
     cox->set_line_width (5.0);
     cox->rectangle(0,0, 80, 40);
     cox->stroke();
-    /////////////////////////////////////////////TICKET #1139 : placeholder drawing 
+    /////////////////////////////////////////////TICKET #1039 : placeholder drawing
   }
   
   
@@ -186,7 +186,7 @@ namespace timeline {
   void
   TimelineCanvas::drawOverlays (Cairo::RefPtr<Cairo::Context> const& cox)
   {
-    /////////////////////////////////////////////TICKET #1139 : placeholder drawing
+    /////////////////////////////////////////////TICKET #1039 : placeholder drawing
     auto alloc = get_allocation();
     int w = alloc.get_width();
     int h = alloc.get_height();
@@ -196,7 +196,7 @@ namespace timeline {
     cox->set_line_width (2.0);
     cox->arc(rad, rad, rad, 0.0, 2.0*M_PI); // full circle
     cox->stroke();
-    /////////////////////////////////////////////TICKET #1139 : placeholder drawing 
+    /////////////////////////////////////////////TICKET #1039 : placeholder drawing
   }
   
   

src/stage/timeline/patchbay-widget.hpp

@@ -27,7 +27,9 @@
  ** the timeline display as a system of nested tracks. For each of these tracks we get a header
  ** section, allowing to control its placement parameters, including start time, output routing
  ** level and panning. The _Patch Bay_ is the container holding all those track header controls,
- ** arranged into a recursively nested structure.
+ ** arranged into a recursively nested structure. Besides that, the Patch Bay serves a secondary
+ ** concern, namely to present this nested structure with proper vertical scrolling, so to keep
+ ** each Track Head aligned with the display of the corresponding track's content.
  ** 
  ** @todo WIP-WIP-WIP as of 10/2018
  ** 
@@ -55,11 +57,15 @@ namespace timeline {
 
   
   /**
-   * Header pane control area corresponding to a Track with nested child Tracks.
-   * This structure is used recursively to build up the Fork of nested Tracks.
-   * - first row: Placement + Property pane
-   * - second row: content or nested tracks.
-   * @todo WIP-WIP as of 12/2016
+   * Header pane control area corresponding to fork of nested tracks.
+   * The structure of child tracks is built up recursively, starting with a single
+   * top level TrackHeadWidget corresponding to the »fork root«. The actual controls
+   * for the individual tracks are managed by those TrackHeadWidget elements, while
+   * the PatchbayWidget corresponds to the whole structure and is responsible for
+   * presenting the proper vertical scrolling, as dictated by the actual track
+   * content within the BodyCanvasWidget sitting at the right side of the
+   * HeaderPaneWidget (which is the enclosing container of this PatchbayWidget).
+   * @todo WIP-WIP as of 4/2019
    */
   class PatchbayWidget
     : public Gtk::Viewport

src/stage/timeline/track-body.cpp

@@ -67,6 +67,7 @@ namespace timeline {
     : overviewHeight_{DEFAULT_OVERVIEW_HEIGHT_px}
     , contentHeight_{DEFAULT_CONTENT_HEIGHT_px}
     , subTracks_{}
+    , rulers_{}
     { }
   
   

src/stage/timeline/track-body.hpp

@@ -78,8 +78,8 @@ namespace timeline {
       
       using SubTracks = std::vector<TrackBody*>;
       
-      Rulers    rulers_;
       SubTracks subTracks_;
+      Rulers    rulers_;
       
     public:
       TrackBody();
@@ -99,7 +99,7 @@ namespace timeline {
        * are only relevant for the immediate display and interaction mechanics,
        * thus we store them right here, close to usage site.
        * @note Ruler entries can be added and removed by diff message, but since
-       *       the UI is performed single threaded, these mutations never interfer
+       *       the UI is performed single threaded, these mutations never interfere
        *       with display evaluation passes.
        */ 
       Rulers&

src/stage/timeline/track-head-widget.hpp

@@ -35,7 +35,8 @@
  **   + video or audio _level_ (=fader)
  ** - how to locate this content in time (e.g. relative to some marker)
  ** For each track, we show a patchbay in the timeline header pane, which serves to control
- ** such aspects relevant for all content contained within the scope of this track.
+ ** such aspects relevant for all content contained within the scope of this track, including
+ ** the sub-tracks nested therein.
  ** 
  ** @todo WIP-WIP-WIP as of 10/2018
  ** 

src/stage/timeline/track-presenter.cpp

@@ -72,11 +72,12 @@ namespace timeline {
   
   
   /**
-   * @note we distinguish between the contents of our three nested child collections
+   * @note we distinguish between the contents of our four nested child collections
    *       based on the symbolic type field sent in the Record type within the diff representation
    *       - "Marker" designates a Marker object
    *       - "Clip" designates a Clip placed on this track
    *       - "Fork" designates a nested sub-track
+   *       - "Ruler" designates a nested ruler (timescale, overview,....) belonging to this track
    * @see TimelineController::buildMutator() for a basic explanation of the data binding mechanism
    */
   void

src/stage/timeline/track-presenter.hpp

@@ -72,6 +72,9 @@ namespace timeline {
   
   /**
    * Reference frame to organise the display related to a specific Track in the Timeline-GUI.
+   * With the help of such a common frame of reference, we solve the problem that each individual
+   * track display needs to hook into two distinct UI presentation structures: the track head controls
+   * and the presentation of track contents on the BodyCanvasWidget.
    */
   struct DisplayFrame
     : util::NonCopyable