Lumiera  0.pre.03
»edityourfreedom«
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Tangible Class Referenceabstract

#include "gui/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 164 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 More...
 
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...
 
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 More...
 
void mark (GenNode const &)
 generic handler for all incoming "state mark" messages More...
 
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 ID () const
 
 operator LuidH () const
 
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 (ID child)
 
- Public Member Functions inherited from DiffMutable
virtual ~DiffMutable ()
 this is an interface More...
 

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)=0
 
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 (ID child)=0
 
virtual void doRevealYourself ()=0
 

Protected Attributes

ctrl::BusTerm uiBus_
 

Additional Inherited Members

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

Member Typedef Documentation

Definition at line 170 of file tangible.hpp.

Definition at line 171 of file tangible.hpp.

using Rec = lib::diff::Rec
protected

Definition at line 173 of file tangible.hpp.

using GenNode = lib::diff::GenNode
protected

Definition at line 174 of file tangible.hpp.

Constructor & Destructor Documentation

Tangible ( ID  identity,
ctrl::BusTerm nexus 
)
inlineprotected

Definition at line 179 of file tangible.hpp.

References BusTerm::attach().

+ Here is the call graph for this function:

~Tangible ( )
virtual

this is an interface

Definition at line 44 of file tangible.cpp.

Member Function Documentation

operator ID ( ) const
inline

Definition at line 186 of file tangible.hpp.

References BusTerm::getID().

+ Here is the call graph for this function:

operator LuidH ( ) const
inline

Definition at line 187 of file tangible.hpp.

References BusTerm::getID().

+ Here is the call graph for this function:

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 60 of file tangible.cpp.

References Tangible::doReset(), BusTerm::note(), and Tangible::uiBus_.

Referenced by BusTerm_test::captureStateMark(), Tangible::doMark(), and AbstractTangible_test::notify().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void clearMsg ( )

invoke the hook to clear notification messages

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

Definition at line 93 of file tangible.cpp.

References Tangible::doClearMsg(), BusTerm::note(), and Tangible::uiBus_.

Referenced by Tangible::doMark().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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 82 of file tangible.cpp.

References Tangible::doClearErr(), BusTerm::note(), and Tangible::uiBus_.

Referenced by Tangible::doMark().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void invoke ( Symbol  cmdID,
ARGS &&  ... 
)

Referenced by Tangible::invoke(), and AbstractTangible_test::invokeCommand().

+ Here is the caller graph for this function:

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 199 of file tangible.cpp.

References BusTerm::act(), and Tangible::uiBus_.

+ Here is the call graph for this function:

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.

Definition at line 153 of file tangible.cpp.

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

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

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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 165 of file tangible.cpp.

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

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

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void slotReveal ( ID  child)
Todo:
12/2015 not clear yet what needs to be done
Remarks
the intention is to request the given child to be brought into sight. We need to set up some kind of children registration, but better not do this in a completely generic fashion, for danger of overengineering. Moreover, it is not clear yet, who will issue this request and at which element the initial request can/will be targeted.

Definition at line 182 of file tangible.cpp.

References Tangible::doReveal(), and Tangible::doRevealYourself().

+ Here is the call graph for this function:

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 105 of file tangible.cpp.

References Tangible::doFlash().

+ Here is the call graph for this function:

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 125 of file tangible.cpp.

References Tangible::doMsg(), BusTerm::note(), and Tangible::uiBus_.

Referenced by Tangible::mark().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void markErr ( string  error)

push an error state tag to the element

Remarks
everything detailed at markMsg applies here too.

Definition at line 136 of file tangible.cpp.

References Tangible::doErr(), BusTerm::note(), and Tangible::uiBus_.

Referenced by BusTerm_test::captureStateMark(), and Tangible::mark().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void mark ( GenNode const &  stateMark)

generic handler for all incoming "state mark" messages

Definition at line 208 of file tangible.cpp.

References GenNode::data, Tangible::doFlash(), Tangible::doMark(), DataCap::get(), BareEntryID::getSym(), GenNode::idi, Tangible::markErr(), and Tangible::markMsg().

Referenced by MockElm::doMark().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

virtual bool doReset ( )
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

Referenced by Tangible::reset().

+ Here is the caller graph for this function:

virtual bool doClearMsg ( )
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

Referenced by Tangible::clearMsg().

+ Here is the caller graph for this function:

virtual bool doClearErr ( )
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

Referenced by Tangible::clearErr().

+ Here is the caller graph for this function:

virtual bool doExpand ( bool  yes)
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

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

+ Here is the caller graph for this function:

virtual void doReveal ( ID  child)
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

Referenced by Tangible::slotReveal().

+ Here is the caller graph for this function:

virtual void doRevealYourself ( )
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

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

+ Here is the caller graph for this function:

virtual bool doMsg ( string  )
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

Referenced by Tangible::markMsg().

+ Here is the caller graph for this function:

virtual bool doErr ( string  )
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

Referenced by Tangible::markErr().

+ Here is the caller graph for this function:

virtual void doFlash ( )
protectedpure virtual

Implemented in MockElm, Controller, and Widget.

Referenced by Tangible::mark(), and Tangible::markFlash().

+ Here is the caller graph for this function:

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()
  • revealYourself 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, Controller, and Widget.

Definition at line 243 of file tangible.cpp.

References Tangible::clearErr(), Tangible::clearMsg(), GenNode::data, Tangible::doExpand(), Tangible::doRevealYourself(), DataCap::get(), BareEntryID::getSym(), GenNode::idi, and Tangible::reset().

Referenced by Tangible::mark().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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 MockElm, InteractionDirector, TimelineController, ClipPresenter, TrackPresenter, MarkerWidget, and AssetController.

void invoke ( Symbol  cmdID,
ARGS &&...  args 
)
inline

convenience shortcut to issue a command with several arguments

Definition at line 240 of file tangible.hpp.

References Tangible::invoke(), and Record< VAL >::TYPE_NIL_SYM.

+ Here is the call graph for this function:

Member Data Documentation

Friends And Related Function Documentation

constexpr size_t treeMutatorSize ( const Tangible )
friend

override default size traits for diff application.

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

Definition at line 229 of file tangible.hpp.

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

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