TimelineController Class Reference

#include "stage/timeline/timeline-controller.hpp"

Description

Controller to supervise the timeline display.

As a tangible element, it is attached to the UI-Bus.

Todo:

WIP-WIP-rewrite as of 12/2016

Remarks

a Timeline always has an attached Sequence, which in turn has a single mandatory root track. This in turn might hold further child tracks, thus forming a fork of nested scopes.

Definition at line 87 of file timeline-controller.hpp.

Public Member Functions
	TimelineController (ID identity, ID trackID, ctrl::BusTerm &nexus, TimelineLayout &)
virtual void	buildMutator (lib::diff::TreeMutator::Handle) override
	set up a binding to respond to mutation messages via UiBus More...
string const &	getName () const
Public Member Functions inherited from Tangible
virtual	~Tangible ()
	this is an interface
void	clearErr ()
	invoke the hook to clear error markers More...
void	clearMsg ()
	invoke the hook to clear notification messages More...
ID	getID () const
void	installExpander (Expander::ProbeFun, Expander::ChangeFun)
	Configure the (optional) functionality to expand or collapse the UI-Element. More...
void	installRevealer (Revealer::RevealeItFun)
	Configure the (optional) functionality to bring the UI-Element into sight. More...
template<typename... ARGS>
void	invoke (Symbol cmdID, ARGS &&...)
void	invoke (Symbol cmdID, Rec &&arguments)
	Perform a command or action, once the execution context has been established. More...
template<typename... ARGS>
void	invoke (Symbol cmdID, ARGS &&... args)
	convenience shortcut to issue a command with several arguments
void	mark (GenNode const &)
	generic handler for all incoming "state mark" messages
void	markErr (string error)
	push an error state tag to the element More...
void	markFlash ()
	highlight the element visually to catch the user's attention More...
void	markMsg (string message)
	push a notification (or warning) message to the element. More...
	operator LuidH () const
	operator string () const
	diagnostic representation. More...
void	reset ()
	invoke the generic reset hook More...
void	slotCollapse ()
	Collapse or minimise this element and remember the collapsed state. More...
void	slotExpand ()
	Expand this element and remember the expanded state. More...
void	slotReveal ()
	Cause the element to be brought into sight. More...
Public Member Functions inherited from DiffMutable
virtual	~DiffMutable ()
	this is an interface

Private Attributes
std::unique_ptr< TrackPresenter >	fork_
vector< unique_ptr< MarkerWidget > >	markers_
string	name_

Additional Inherited Members
Public Types inherited from Tangible
using	ID = ctrl::BusTerm::ID
using	LuidH = lib::hash::LuidH
Protected Types inherited from Tangible
using	GenNode = lib::diff::GenNode
using	Rec = lib::diff::Rec
Protected Member Functions inherited from Controller
virtual void	doMark (GenNode const &mark) override
	default handler for all generic mark messages. More...
Protected Member Functions inherited from Tangible
	Tangible (ID identity, ctrl::BusTerm &nexus)
virtual bool	doExpand (bool yes)
	generic default implementation of the expand/collapse functionality. More...
virtual void	doReveal ()
	generic default implementation of the "reveal" functionality. More...
Protected Attributes inherited from Tangible
Expander	expand_
Revealer	reveal_
ctrl::BusTerm	uiBus_

Constructor & Destructor Documentation

TimelineController()

TimelineController	(	ID	identity,
		ID	trackID,
		ctrl::BusTerm &	nexus,
		TimelineLayout &	layoutManager
	)

Parameters

identity	used to refer to a corresponding timeline element in the Session
trackID	the mandatory root track used in the associated Sequence
nexus	some established connection to the UI-Bus, used for registration.

Definition at line 85 of file timeline-controller.cpp.

Member Function Documentation

buildMutator()

void buildMutator ( lib::diff::TreeMutator::Handle  buffer )

overridevirtual

set up a binding to respond to mutation messages via UiBus

this method is invoked by the UI-Bus when dispatching a MutationMessage...

Remarks

this is likely the first occasion a casual reader sees such a binding function, thus some explanations might be helpful. This is part of the »diff framework«: we use messages to communicate changes on structured data. A allegedly more direct solution would be to dance on a shared data or object model in the Session — yet we refrain from this kind of naive implementation, to avoid tight coupling, here between the Session core logic and the structures in the UI. Rather we assume that both sides share a roughly compatible understanding regarding the structure of the session model. Exchanging just diff messages allows us to use private implementation data structures in the UI as we see fit, without the danger of breaking anything in the core. And vice versa. You may see this as yet another way to build a data binding between model and view. The TreeMutator helps to accomplish this binding between a generic structure description, in our case based on GenNode elements, and the private data structure, here the private object fields and the collection of child objects within TimelineController. To ease this essentially "mechanic" and repetitive task, the TreeMutator offers some standard building blocks, plus a builder DSL, allowing just to fill in the flexible parts with some lambdas. Yet still, the technical details of getting this right can be tricky, especially since it is very important to set up those bindings in the right order. Basically we build a stack of decorators, so what is mentioned last will be checked first. Effectively this creates a structure of "onion layers", where each layer handles just one aspect of the binding. This works together with the convention that the diff message must mention all changes regarding one group (or kind) of elements together and completely. This is kind of an object description protocol, meaning that the diff has to mention the metadata (the object type) first, followed by the "attributes" (fields) and finally nested child objects. And nested elements can be handled with a nested diff, which recurses into some nested scope. In the example here, we are prepared to deal with two kinds of nested scope:

• the fork (that is the tree of tracks) is a nested structure
• we hold a collection of marker child objects, each of which can be entered as a nested scope. For both cases we prepare a way to build a nested mutator, and in both cases this is simply achieved by relying on the common interface of all those "elements", which is stage::model::Tangible and just happens to require each such "tangible" to offer a mutation building method, just like this one here. Plain recursive programming.

in fact the .buildChildMutator binding could have been omitted here, since it is precisely the default, which will be provided for a DiffMutable target object automatically (the TimelineController is a stage::model::Tangible, and thus implements the DiffMutable interface, with abstract buildMutator method.

See also

DiffComplexApplication_test

Implements Tangible.

Definition at line 142 of file timeline-controller.cpp.

References TreeMutator::build(), lib::diff::anonymous_namespace{tree-mutator-collection-binding.hpp}::collection(), PlantingHandle< BA, DEFAULT >::emplace(), and DataCap::isNested().

Here is the call graph for this function:

Inheritance diagram for TimelineController:

Collaboration diagram for TimelineController:

---

The documentation for this class was generated from the following files:

• timeline-controller.hpp
• timeline-controller.cpp