#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

NonCopyable &	operator= (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

cmdID	indicates the global command definition to be invoked
arguments	suitable 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

message notification 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

detectCurrExpansionState	a lambda or function<bool()> to retrieve if the element is currently expanded
howto_expand_collapse	a 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_element a 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

buffer a 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:

Description

Public Types

Public Member Functions

Friends

Protected Types

Protected Member Functions

Protected Attributes

Additional Inherited Members

Member Function Documentation

◆ operator string()

◆ reset()

◆ clearMsg()

◆ clearErr()

◆ invoke()

◆ slotExpand()

◆ slotCollapse()

◆ slotReveal()

◆ markFlash()

◆ markMsg()

◆ markErr()

◆ installExpander()

◆ installRevealer()

◆ doExpand()

◆ doReveal()

◆ doMark()

◆ buildMutator()

Friends And Related Function Documentation

◆ treeMutatorSize