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 78 of file timeline-controller.hpp.

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

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

Additional Inherited Members
Public Types inherited from Tangible
using	ID = ctrl::BusTerm::ID
using	LuidH = lib::hash::LuidH
Protected Types inherited from Tangible
using	Rec = lib::diff::Rec
using	GenNode = lib::diff::GenNode
Protected Member Functions inherited from Controller
virtual void	doMark (GenNode const &mark) override
	default handler for all generic mark messages.
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.
virtual void	doReveal ()
	generic default implementation of the "reveal" functionality.
Protected Attributes inherited from Tangible
ctrl::BusTerm	uiBus_
Expander	expand_
Revealer	reveal_

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 76 of file timeline-controller.cpp.

References TimelineController::fork_, and TimelineLayout::setupStructure().

Here is the call graph for this function:

~TimelineController()

~TimelineController

(

)

Definition at line 86 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 133 of file timeline-controller.cpp.

References stage::ATTR_name, TreeMutator::build(), GenNode::data, PlantingHandle< BA, DEFAULT >::emplace(), TimelineController::fork_, GenNode::idi, DataCap::isNested(), TimelineController::markers_, and TimelineController::name_.

Here is the call graph for this function:

getName()

string const & getName ( ) const

inline

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

References TimelineController::name_.

Member Data Documentation

name_

string name_

private

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

Referenced by TimelineController::buildMutator(), and TimelineController::getName().

markers_

vector<unique_ptr<MarkerWidget> > markers_

private

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

Referenced by TimelineController::buildMutator().

fork_

std::unique_ptr<TrackPresenter> fork_

private

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

Referenced by TimelineController::TimelineController(), and TimelineController::buildMutator().

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