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

#include "gui/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
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 198 of file ui-coord-resolver.hpp.

Public Types

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

Public Member Functions

virtual ~LocationQuery ()
 this is an interface More...
 
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...
 

Member Typedef Documentation

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

Constructor & Destructor Documentation

~LocationQuery ( )
virtual

this is an interface

Definition at line 45 of file ui-coord-resolver.cpp.

Member Function Documentation

virtual Literal determineAnchor ( UICoord const &  path)
pure virtual

make the real anchor point explicit.

Parameters
pathan 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:

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(), UICoordResolver::extend(), and UICoordResolver::pathResolution().

+ Here is the caller graph for this function:

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
pathan explicit UIcoord spec, expected to be anchored and at least partially covered within the current configuration and state of the UI
posdepth 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::Statewhen navigating the given path touches a non-existing element

Implemented in GenNodeLocationQuery, and Navigator.

Referenced by UICoordResolver::pathResolution().

+ Here is the caller graph for this function:

+ Inheritance diagram for LocationQuery:
+ Collaboration diagram for LocationQuery:

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