control.hpp File Reference

Go to the source code of this file.

Description

Manipulating and monitoring time entities with life changes.

This is an control- and callback element to handle any kind of "running" time entities. This element is to be provided by the client and then attached to the target time entity as a time::Mutation. Internally, a life connection to the target is built, allowing both to

• to manipulate the target by invoking the function operator
• to receive change notifications by installing a callback functor.

The actual type of the changes and modifications is specified as template parameter; when later attached to some time entity as a Mutation, the actual changes to be performed depend both on this change type and the type of the target time entity (double dispatch). The behaviour is similar to applying a static time::Mutation

relevance

This control element is intended to be used for all kinds of editing and monitoring of time-like entities – be it the running time display in a GUI widget, a ruler marker which can be dragged, a modifiable selection or the animated playhead cursor.

Usage scenarios

The time::Control element provides mediating functionality, but doesn't assume or provide anything special regarding the usage pattern or the lifecycle, beyond the ability to attach listeners, attach to a (different) target and to detach from all connections. Especially, no assumptions are made about which side is the server or the client and who owns the time::Control element.

Thus an interface might accept a time::Control element reference (e.g. the lumiera::Play::Controller uses this pattern) – meaning that the client owns the Control element and might attach listeners, while the implementation (server side) will attach the Control to mutate a time value entity otherwise not disclosed (e.g. the playhead position of the playback process). Of course, in this case the client is responsible for keeping the Control element and all listeners alive, and to invoke Control::disconnect prior to destroying the element.

Of course, the reversed usage situation would be possible as well: an interface may expose a time::Control, thus allowing to attach target and listeners, while the actual changes will originate somewhere within the opaque service implementation.

Another usage pattern would be to expose a time::Control const&, allowing only to impose changes, but not to change the target or listener attachments. To the contrary, exposing only a time::Mutation const& through some interface allows only to attach new target elements, but not to change listeners or feed any value changes.

Using time::Control as an implementation building block and just exposing the change (function) operators or the listener attachment through an forwarding sub interface is another option.

Note

time::Control is default constructible and freely copyable.

Changing quantised (grid aligned) time entities

The time::Control element includes the functionality to handle grid aligned time values, both as target and as change/notification value. This ability is compiled in conditionally, as including mutation.hpp causes several additional includes, which isn't desirable when it comes just to changing plain time values. Thus, to get these additional specialisations, the LIB_TIME_TIMEQUANT_H header guard needs to be defined, which happens automatically if lib/time/mutation.hpp is included prior to lib/time/control.hpp.

implementation notes

• the validity of a given combination of change and target is checked immediately, when connecting to the target. Depending on the situation, the actual changes later are subject to specific treatment (e.g. frame quantisation)
• by default time::Control is not threadsafe. But, as each change is basically processed within its own call context (function invocation), parallelism is only a concern with respect to the value finally visible within the target.
• the change notification is processed right away, after applying the change to the target; of course there is a race between applying the value and building the response value passed on as notification. In all cases, the effective change notification value is built from the state of the target after applying the change, which might or might not reflect the change value passed in.

Todo:

include support for QuTimeSpan values ////////////////////TICKET #760

See also

TimeControl_test

Definition in file control.hpp.

#include "lib/time/mutation.hpp"
#include "lib/time/timevalue.hpp"
#include "lib/time/control-impl.hpp"

Classes
class	Control< TI >
	Frontend/Interface: controller-element to retrieve and change running time values. More...

Namespaces
	lib
	Implementation namespace for support and library code.