Lumiera  0.pre.03
»edit your freedom«
Tangible Class Referenceabstract

#include "stage/model/tangible.hpp"

Description

Interface common to all UI elements of relevance for the Lumiera application.

Any non-local and tangible interface interaction will at some point pass through this foundation element, which forms the joint and attachment to the UI backbone, which is the UI-Bus. Any tangible element acquires a distinct identity and has to be formed starting from an already existing bus nexus.

See also
explanation of the basic interactions
Warning
Tangible is NonCopyable for good reason: the UI-Bus Nexus adds a direct reference into the routing table, tied to the given Tangible's ID (identity. Consequently you must not store tangibles in STL containers, since these might re-allocate and thus change the location in memory.

Definition at line 165 of file tangible.hpp.

Public Types

using ID = ctrl::BusTerm::ID
 
using LuidH = lib::hash::LuidH
 

Public Member Functions

virtual ~Tangible ()
 this is an interface
 
virtual void buildMutator (lib::diff::TreeMutator::Handle)=0
 build a custom implementation of the TreeMutator interface, suitably wired to cause appropriate changes to the opaque data structure, in accordance to the semantics of the tree diff language. More...
 
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
 

Friends

constexpr size_t treeMutatorSize (const Tangible *)
 override default size traits for diff application. More...
 

Protected Types

using GenNode = lib::diff::GenNode
 
using Rec = lib::diff::Rec
 

Protected Member Functions

 Tangible (ID identity, ctrl::BusTerm &nexus)
 
virtual bool doClearErr ()=0
 
virtual bool doClearMsg ()=0
 
virtual bool doErr (string)=0
 
virtual bool doExpand (bool yes)
 generic default implementation of the expand/collapse functionality. More...
 
virtual void doFlash ()=0
 
virtual void doMark (GenNode const &)=0
 default implementation and catch-all handler for receiving »state mark« messages. More...
 
virtual bool doMsg (string)=0
 
virtual bool doReset ()=0
 
virtual void doReveal ()
 generic default implementation of the "reveal" functionality. More...
 

Protected Attributes

Expander expand_
 
Revealer reveal_
 
ctrl::BusTerm uiBus_
 

Additional Inherited Members

- Private Member Functions inherited from NonCopyable
 NonCopyable (NonCopyable const &)=delete
 
NonCopyableoperator= (NonCopyable const &)=delete
 

Member Function Documentation

◆ operator string()

operator string ( ) const

diagnostic representation.

Note
used in exceptions to indicate the origin.

Definition at line 53 of file tangible.cpp.

◆ reset()

void reset ( )

invoke the generic reset hook

Note
the actual subclass has to override the doReset() hook to perform the actual clean-up work.
in case an actual reset happened, the implementation should return true from this doReset() hook. As a consequence, a new "reset" state mark is emitted, which causes the PresentationStateManager to discard any state previously recorded for this element.
Remarks
the intention is that, after invoking reset(), the interface element or controller is in pristine (presentation) state

Definition at line 74 of file tangible.cpp.

References BusTerm::note().

Referenced by Tangible::doMark().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ clearMsg()

void clearMsg ( )

invoke the hook to clear notification messages

Remarks
everything is symmetrical to reset() and clearErr() here...

Definition at line 107 of file tangible.cpp.

References BusTerm::note().

Referenced by Tangible::doMark().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ clearErr()

void clearErr ( )

invoke the hook to clear error markers

Note
the actual subclass has to override the doClearErr() hook...
and similar to the reset() call, also the implementation should return true in case any actual (sticky) error state has been cleared. Again, this causes emitting of a "resetErr" state mark, which will purge any sticky error state remembered within the state manager.
Remarks
usually, most error markers are not sticky, that is, they will be forgotten when the session ends. In this case, the implementation doesn't need to care for anything special. Only in those cases, where actually an error state has to be preserved, the implementation should
  • emit an "Error" state mark, with the sticky error state in payload
  • be prepared to recognise when this sticky error state is fed back
  • actually signal the sticky state has to be purged when it is cleared.

Definition at line 96 of file tangible.cpp.

References BusTerm::note().

Referenced by Tangible::doMark().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ invoke()

void invoke ( Symbol  cmdID,
Rec &&  arguments 
)

Perform a command or action, once the execution context has been established.

After binding (and recording) the command arguments, as supplied with the record, the command action is executed right away.

Parameters
cmdIDindicates the global command definition to be invoked
argumentssuitable tuple of values, to be used to outfit the prototype
Remarks
may use a previously "opened" instanceID, instead of a global commandID

Definition at line 251 of file tangible.cpp.

References BusTerm::act().

+ Here is the call graph for this function:

◆ slotExpand()

void slotExpand ( )

Expand this element and remember the expanded state.

This is a generic Slot to connect UI signals against.

Note
The concrete Widget or Controller has to override the ::doExpand() extension point to provide the actual UI behaviour. If this virtual method returns true, the state change is deemed relevant and persistent, and thus a "state mark" is sent on the UI-Bus.
Remarks
a default implementation of ::doExpand() is provided, based on installing an Expander functor through the configuration function.

Definition at line 170 of file tangible.cpp.

References Tangible::doExpand(), and BusTerm::note().

Referenced by BusTerm_test::clearStates(), AbstractTangible_test::markState(), and AbstractTangible_test::revealer().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ slotCollapse()

void slotCollapse ( )

Collapse or minimise this element and remember the collapsed state.

This is a generic Slot to connect UI signals against.

Definition at line 182 of file tangible.cpp.

References Tangible::doExpand(), and BusTerm::note().

Referenced by AbstractTangible_test::markState().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ slotReveal()

void slotReveal ( )

Cause the element to be brought into sight.

This is a generic Slot to connect UI signals against; the same action can also be triggered by sending a mark message over the UI-Bus with the symbol "`reveal`".

Note
this is an optional feature and requires the actual widget or controller either to override the ::doReveal() extension point, or to install a suitable closure. Typically this is not in itself a persistent state change; however, it might incur expanding some widgets, which is recorded as persistent UI state.
Remarks
the intention is to make a specific element visible, e.g. to reveal the effect of some operation, or to mark a serious error condition. Implementing this is by no means trivial, since it involves the possibly recursive collaboration with enclosing container widgets, and maybe even to scroll to a given canvas position.

Definition at line 222 of file tangible.cpp.

References Tangible::doReveal().

Referenced by AbstractTangible_test::revealer().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ markFlash()

void markFlash ( )

highlight the element visually to catch the user's attention

Remarks
this is meant as a short transient visual change, just to indicate something of relevance happened here.

Definition at line 119 of file tangible.cpp.

◆ markMsg()

void markMsg ( string  message)

push a notification (or warning) message to the element.

Parameters
messagenotification text
Note
the actual interface response need to be coded in the concrete subclass within doMsg().
Remarks
the intention is for this message to be somehow visible at this element, e.g. as mouse over. When this notification is meant to be "sticky" / permanent, then the mentioned doMsg() implementation function should return true; in this case we'll emit a "state mark notification", which will be recorded by the PresentationStateManager, under the property name "`Message`" for this UI-Element. This mechanism allows to persist such UI states.

Definition at line 139 of file tangible.cpp.

References BusTerm::note().

Referenced by Tangible::mark().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ markErr()

void markErr ( string  error)

push an error state tag to the element

Remarks
everything detailed at markMsg applies here too.

Definition at line 150 of file tangible.cpp.

References BusTerm::note().

Referenced by Tangible::mark().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ installExpander()

void installExpander ( Expander::ProbeFun  detectCurrExpansionState,
Expander::ChangeFun  howto_expand_collapse 
)
inline

Configure the (optional) functionality to expand or collapse the UI-Element.

Parameters
detectCurrExpansionStatea lambda or function<bool()> to retrieve if the element is currently expanded
howto_expand_collapsea lambda or function<void(bool)> to switch the element's expansion state
Note
unless this setup function is invoked, the expand/collapse functionality remains disabled; invoking the slotExpand() or sending mark "`expand`" messages via UI-Bus has no effect then.

Definition at line 282 of file tangible.hpp.

Referenced by MockElm::buildMutator(), and NotificationHub::doMark().

+ Here is the caller graph for this function:

◆ installRevealer()

void installRevealer ( Revealer::RevealeItFun  how_to_uncover_the_element)
inline

Configure the (optional) functionality to bring the UI-Element into sight.

Parameters
how_to_uncover_the_elementa lambda or function<void()> to actually cause the necessary actions.
Note
unless this setup function is invoked, the "`reveal`" functionality remains disabled. Typically this setup will be done by an owning parent container, binding to some internals and also recursively invoking the "`reveal`" action on the container.

Definition at line 297 of file tangible.hpp.

Referenced by NotificationHub::doMark(), and AbstractTangible_test::revealer().

+ Here is the caller graph for this function:

◆ doExpand()

bool doExpand ( bool  yes)
protectedvirtual

generic default implementation of the expand/collapse functionality.

Based on the #expand_ functor, which needs to be configured explicitly to enable this functionality.

Returns
true if the actual expansion state has been changed.

Reimplemented in MockElm.

Definition at line 196 of file tangible.cpp.

Referenced by Tangible::doMark(), Tangible::slotCollapse(), and Tangible::slotExpand().

+ Here is the caller graph for this function:

◆ doReveal()

void doReveal ( )
protectedvirtual

generic default implementation of the "reveal" functionality.

Based on the #reveal_ functor, which needs to be configured explicitly to enable this functionality.

Reimplemented in MockElm.

Definition at line 234 of file tangible.cpp.

Referenced by Tangible::doMark(), and Tangible::slotReveal().

+ Here is the caller graph for this function:

◆ doMark()

void doMark ( GenNode const &  stateMark)
protectedpure virtual

default implementation and catch-all handler for receiving »state mark« messages.

Such messages serve either to cause a presentation state effect specific to this element, or they are used to re-play a former state change to restore some specific UI state captured within a past working session. Events handled here:

  • expand with a bool argument calls the doExpand(bool) virtual function. It is up to the concrete element to give this a tangible meaning, e.g. a track might switch to detail view and a clip might reveal attached effects.
  • reset restores the element to the hard wired default, by invoking doReset()
  • reveal prompts the element to take the necessary actions to bring itself into view. There is no requirement for an element to even implement this call, but those which do typically know some kind of _"parent object"_ to forward this request, by invoking doReveal(myID) on this parent. For instance, a clip might ask the enclosing track, which in turn might call the enclosing timeline display for help, resulting in a scroll action to bring the clip into sight.
    Note
    this is a default implementation for a virtual function declared abstract with the intention for derived classes to tail-call this default handler.

Implemented in MockElm, NotificationHub, Controller, and Widget.

Definition at line 295 of file tangible.cpp.

References Tangible::clearErr(), Tangible::clearMsg(), Tangible::doExpand(), Tangible::doReveal(), BusTerm::note(), and Tangible::reset().

Referenced by Controller::doMark(), and Tangible::mark().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ buildMutator()

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

build a custom implementation of the TreeMutator interface, suitably wired to cause appropriate changes to the opaque data structure, in accordance to the semantics of the tree diff language.

Parameters
buffera buffer handle, which can be used to placement-construct

Implements DiffMutable.

Implemented in TrackPresenter, MockElm, ClipPresenter, InteractionDirector, TimelineController, RulerTrack, NotificationHub, AssetController, and MarkerWidget.

Friends And Related Function Documentation

◆ treeMutatorSize

constexpr size_t treeMutatorSize ( const Tangible )
friend

override default size traits for diff application.

Remarks
this value here is hard coded, based on what can be expected for diff application to UI elements.

Definition at line 238 of file tangible.hpp.

+ Inheritance diagram for Tangible:
+ Collaboration diagram for Tangible:

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