LocationQuery Class Reference

#include "stage/interact/ui-coord-resolver.hpp"

Description

Interface to discover a backing structure for the purpose of path navigation and resolution.

UICoord are meant to designate a position within the logical structure of an UI – yet in fact they may be resolved against any tree-like topological structure, which can be queried through this interface.

See also

Navigator the implementation used in the Lumiera UI, as backed by actual GUI components

InteractionDirector manages the Navigator and exposes it via lib::Depend<LocationQuery>

GenNodeLocationQuery a dummy/test implementation, where the "UI topology" is hard wired as a tree of GenNode elements. This serves the purpose of unit testing, without having to rely on an actual UI.

Definition at line 200 of file ui-coord-resolver.hpp.

Public Types
using	ChildIter = decltype(TreeStructureNavigator::buildIterator(0))

Public Member Functions
virtual	~LocationQuery ()
	this is an interface
virtual Literal	determineAnchor (UICoord const &path)=0
	make the real anchor point explicit. More...
virtual size_t	determineCoverage (UICoord const &path)=0
	evaluate to what extent a UIcoord spec matches the actual UI More...
virtual ChildIter	getChildren (UICoord const &path, size_t pos)=0
	get the sequence of child components at a designated position in the actual UI More...

Static Public Attributes
static lib::Depend< LocationQuery >	service
	access point to global LocationQuery service implementation More...

Member Function Documentation

determineAnchor()

virtual Literal determineAnchor ( UICoord const &  path )

pure virtual

make the real anchor point explicit.

Parameters

path	an explicit UICoord spec to be anchored in the actual UI

Returns

explicit literal window name, where the path can be anchored Symbol::BOTTOM in case the given path can not be anchored currently.

Remarks

here "to anchor" means to match and thus "attach" the starting point of the UIcoord path, i.e. the window spec, with an actual top-level window existing in the current UI configuration and state. This operation either confirms existence of a window given by explicit ID, or it supplies the current meaning of the meta specs currentWindow and firstWindow, again in the form of an explicit window name

Implemented in GenNodeLocationQuery, and Navigator.

Referenced by UICoordResolver::attempt_trivialResolution().

Here is the caller graph for this function:

determineCoverage()

virtual size_t determineCoverage ( UICoord const &  path )

pure virtual

evaluate to what extent a UIcoord spec matches the actual UI

Returns

the depth to which the given spec is _"covered"_ by the actual UI. Can be zero, in which case the given coordinates can not be resolved and addressed within the currently existing windows, panes and views.

Remarks

a depth > 0 also implies that the path can be anchored.

Note

this operation does not perform any resolution or interpolation of wildcards, it just matches explicit UI component names.

See also

UICoordResolver for a facility to perform such a resolution and to navigate paths.

Implemented in GenNodeLocationQuery, and Navigator.

Referenced by UICoordResolver::attempt_trivialResolution(), and UICoordResolver::extend().

Here is the caller graph for this function:

getChildren()

virtual ChildIter getChildren ( UICoord const &  path, size_t  pos  )

pure virtual

get the sequence of child components at a designated position in the actual UI

Parameters

path	an explicit UIcoord spec, expected to be anchored and at least partially covered within the current configuration and state of the UI
pos	depth where the given path shall be evaluated, starting with 0 at window level

Returns

an iterator to enumerate all child components actually existing in the current UI below the location designated by path and pos.

Remarks

the path is only evaluated up to (not including) the given depth. Especially when pos == 0, then the path is not evaluated and matched at all, rather just the current list of top-level windows is returned.

Exceptions

error::State

when navigating the given path touches a non-existing element

Implemented in GenNodeLocationQuery, and Navigator.

Member Data Documentation

service

lib::Depend< LocationQuery > service

static

access point to global LocationQuery service implementation

storage for the global LocationQuery service access point

Definition at line 206 of file ui-coord-resolver.hpp.

Referenced by LocationQuery::~LocationQuery().

Inheritance diagram for LocationQuery:

Collaboration diagram for LocationQuery:

---

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

• ui-coord-resolver.hpp
• ui-coord-resolver.cpp