Lumiera  0.pre.03
»edit your freedom«
List of all members | Public Member Functions | Classes | Private Member Functions | Private Attributes
UICoordResolver Class Reference

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

Description

Query and mutate UICoord specifications in relation to actual UI topology.

This specialised builder uses a location query facility to retrieve information about the current actual UI topology. The UI coordinate spec given as initialisation acts as a pattern, to be queried and resolved against that actual UI topology in various ways

  • determine the anchor point, where this UI coordinate pattern will be rooted in the UI
  • determine to which extent this UI coordinate pattern can be _"covered"_ (= supported) by the exiting UI. To resolve this query, it is necessary to perform a matching search with backtracking, in order to find the best possible coverage ** the coverage can be complete, which means that all components mentioned explicitly within the pattern in fact exist in the actual UI ** a partial coverage means that there is a prefix actually supported, while some extraneous tailing components do not (yet) exist in the UI. Moreover, the pattern can be mutated to conform with the existing UI topology:
  • the anchor point can be made explicit, which means to replace the meta specifications ** firstWindow ** currentWindow
  • the calculated coverage solution can be interpolated into the pattern, thereby binding and replacing any placeholders ("wildcards", i.e. components designated as "*")
  • we may extend the pattern by attaching further elements, behind the covered part.
    Note
    this is a coordinate builder, which means that it works on a copy of the UI coordinate pattern provided at initialisation. The result, a possibly reworked UI coordinate spec can be moved out into a new target UI coordinate (which is then immutable). The various query and binding operations work by side-effect on the internal state encapsulated within this builder.
    Warning
    computing a coverage solution for a sparsely defined pattern against a large UI topology can be expensive, since in worst case we have to perform a depth-first scan of the whole tree structure

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

Public Member Functions

 UICoordResolver (UICoord const &uic, LocationQuery &queryAPI)
 
 UICoordResolver (UICoord &&uic, LocationQuery &queryAPI)
 
UICoordResolver && anchor ()
 mutate the window part of the path such as to make the anchorage explicit, if possible More...
 
bool canAnchor () const
 determine if a mutation is possible to anchor the path explicitly More...
 
bool canCover () const
 determine if a mutation is possible to get the path (partially) covered. More...
 
UICoordResolver && cover ()
 mutate the path to get it totally covered More...
 
size_t coverDepth () const
 
UICoordResolver && coverPartially ()
 mutate the path by resolving all wildcards to achieve partial coverage More...
 
UICoordResolver && existentiallyQuantify (size_t pos)
 mutate to turn a wildcard into existentially quantified. This means to assume (or require) that an element actually exists at the given position, without knowing or caring about its actual name. More...
 
UICoordResolver && extend (Literal pathExtension)
 mutate the path to extend it while keeping it partially covered More...
 
UICoordResolver && extend (UICoord const &partialExtensionSpec)
 mutate the path and extend it with components at fixed positions More...
 
bool isAnchored () const
 is this path explicitly anchored at an existing window? More...
 
bool isCovered () const
 this path is completely covered by the currently existing UI structure; More...
 
bool isCoveredPartially () const
 is this path at least partially covered? A covered path describes an access path through widgets actually existing in the UI. More...
 
bool isCoveredTotally () const
 synonymous to isCovered()
 
 operator string () const
 diagnostics
 
- Public Member Functions inherited from UICoord::Builder
 Builder (Builder &&)=default
 
Builder && append (Literal elm)
 augment UI coordinates by appending a further component at the end. More...
 
LocationClause create ()
 interprets the current (inline) builder contents as create clause, which has the meaning "create a new element XYZ when possible"
 
bool empty () const
 
Builder && noTab ()
 augment UI coordinates to indicate that no tab specification is necessary More...
 
 operator LocationClause ()
 support for use in the ViewSpec-DSL More...
 
Builder && panel (Literal panelID)
 augment UI coordinates to indicate a specific view to be used
 
Builder && path (Literal pathDef)
 augment UI coordinates to define a complete local path More...
 
Builder && persp (Literal perspectiveID)
 augment UI coordinates to mandate a specific perspective to be active within the window
 
Builder && prepend (Literal elmID)
 augment partially defined UI coordinates by extending them towards the root
 
size_t size () const
 
Builder && tab (Literal tabID)
 augment UI coordinates to indicate a specific tab within the view"
 
Builder && tab (uint tabIdx)
 augment UI coordinates to indicate a tab specified by index number
 
Builder && truncateTo (size_t depth)
 possibly shorten this path specification to a limited depth
 
UICoord const & uiCoord ()
 
Builder && view (Literal viewID)
 augment UI coordinates to indicate a specific view to be used
 
Builder && window (Literal windowID)
 change UI coordinate spec to define it to be rooted within the given window More...
 

Classes

struct  Resolution
 

Private Member Functions

void attempt_trivialResolution ()
 establish a trivial anchorage and coverage, if possible. More...
 
bool pathResolution ()
 Since UICoord path specifications may contain gaps and wildcards, we may attempt to fill in these missing parts by matching against the topological structure of an actual UI. More...
 

Private Attributes

LocationQuery & query_
 
Resolution res_
 

Additional Inherited Members

- Protected Member Functions inherited from UICoord::Builder
template<typename... ARGS>
 Builder (ARGS &&...args)
 
 Builder (UICoord &&anonRef)
 
 Builder (UICoord const &base)
 
Builder && normalise ()
 
Builder && overwrite (size_t depth, Literal newSpec)
 
- Protected Attributes inherited from UICoord::Builder
UICoord uic_
 

Class Documentation

◆ stage::interact::UICoordResolver::Resolution

struct stage::interact::UICoordResolver::Resolution
Class Members
const char * anchor
size_t depth
unique_ptr< UICoord > covfefe
bool isResolved
+ Collaboration diagram for UICoordResolver::Resolution:

Member Function Documentation

◆ isAnchored()

bool isAnchored ( ) const
inline

is this path explicitly anchored at an existing window?

Remarks
this also implies the path is complete and explicit (no wildcards).

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

◆ canAnchor()

bool canAnchor ( ) const
inline

determine if a mutation is possible to anchor the path explicitly

Remarks
basically this either means the path isAnchored(), or we're able to calculate a path resolution, interpolating any wildcards. And while the path resolution as such might fail, it was at least successful to determine an anchor point. The existence of such an anchor point implies the path is not totally in contradiction to the existing UI

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

◆ isCoveredPartially()

bool isCoveredPartially ( ) const
inline

is this path at least partially covered? A covered path describes an access path through widgets actually existing in the UI.

Remarks
this also implies the path is anchored, complete and explicit.
Note
this predicate tests for partial coverage, which means, there might be some extraneous suffix in this path descending beyond existing UI

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

◆ isCovered()

bool isCovered ( ) const
inline

this path is completely covered by the currently existing UI structure;

Remarks
there is no extraneous uncovered suffix in this path spec; moreover, the path is anchored, complete and explicit

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

◆ canCover()

bool canCover ( ) const
inline

determine if a mutation is possible to get the path (partially) covered.

Remarks
in order to be successful, a path resolution must interpolate any gaps in the path spec and reach a point behind / below the gap (wildcards), where an existing explicitly stated component in the path can be confirmed (covered) by the existing UI. The idea behind this definition is that we do not want just some interpolated wildcards, rather we really want to confirm the essence of the path specification. Yet we accept an extraneous suffix in the explicitly given part of the path spec to extend beyond or below what exists currently within the UI.

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

◆ cover()

UICoordResolver&& cover ( )
inline

mutate the path to get it totally covered

  • make the anchorage explicit
  • possibly match and expand any wildcards
  • then truncate the UI-Coordinate spec to that part actually covered by the UI
    Note
    if the coordinate spec can not be covered at all, it will be truncated to zero size

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

◆ coverPartially()

UICoordResolver&& coverPartially ( )
inline

mutate the path by resolving all wildcards to achieve partial coverage

  • anchorage and all wildcards will be resolved against current UI
  • but an extraneous, uncovered, explicit suffix is retained
    Note
    if the coordinate spec can not be (partially) covered at all, it will be truncated to zero size

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

◆ anchor()

UICoordResolver&& anchor ( )
inline

mutate the window part of the path such as to make the anchorage explicit, if possible

Remarks
if the path starts with meta specs like firstWindow or currentWindow, they will be replaced by their current meaning. If the path is incomplete, but can somehow be resolved, we use the anchorage as indicated by that resolution, without interpolating the rest of the path.

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

◆ extend() [1/2]

UICoordResolver&& extend ( Literal  pathExtension)
inline

mutate the path to extend it while keeping it partially covered

Parameters
pathExtensiona literal specification, which is extended immediately behind the actually covered part of the path, irrespective of the depth
Note
the extension may contain '/', which are treated as component separators

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

References LocationQuery::determineCoverage().

+ Here is the call graph for this function:

◆ extend() [2/2]

UICoordResolver&& extend ( UICoord const &  partialExtensionSpec)
inline

mutate the path and extend it with components at fixed positions

Parameters
partialExtensionSpecUI coordinates used as extension
Exceptions
ifthe extension would overwrite the covered part.
Remarks
this is the typical use case, where we want to place some component explicitly at a given depth (e.g. a new view or tab)

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

References PathArray< chunk_size >::begin(), and PathArray< chunk_size >::indexOf().

+ Here is the call graph for this function:

◆ existentiallyQuantify()

UICoordResolver&& existentiallyQuantify ( size_t  pos)
inline

mutate to turn a wildcard into existentially quantified. This means to assume (or require) that an element actually exists at the given position, without knowing or caring about its actual name.

This becomes relevant when matching for partially covered path; normal wildcards are only accepted to build a solution, when the matching can be confirmed by an explicit element after (below) the wildcard part. While this restriction serves to prevent ambiguous and surprising arbitrary matches, it can sometimes defeat any solution, e.g. when creating a new panel on top of an existing but irrelevant perspective.

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

References stage::interact::UIC_ELIDED.

Referenced by UILocationSolver::preprocess().

+ Here is the caller graph for this function:

◆ attempt_trivialResolution()

void attempt_trivialResolution ( )
inlineprivate

establish a trivial anchorage and coverage, if possible.

Note
when the UICoord contains wildcards or is incomplete, a full resolution with backtracking is necessary to determine anchorage and coverage. The same is true when the pattern uses an elided element, since such an existentially quantified item must be interpolated.

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

References LocationQuery::determineAnchor(), LocationQuery::determineCoverage(), and stage::interact::UIC_ELIDED.

+ Here is the call graph for this function:

◆ pathResolution()

bool pathResolution ( )
private

Since UICoord path specifications may contain gaps and wildcards, we may attempt to fill in these missing parts by matching against the topological structure of an actual UI.

algorithm to resolve this UICoord path against the actual UI topology.

Returns
true if total coverage is possible (by interpolating wildcards)
Remarks
after invoking this function, res_.isResolved and possible coverage are set.

In the general case, finding a solution requires a depth-first exponential brute-force search over the whole structure tree, since we have to try every possible branch until we can disprove the possibility of a match. Implemented as depth-first search with backtracking, this scanning pass produces a list of possible matches, from which we pick the first one with maximum coverage, to yield a single solution.

Remarks
the search and matching is based on an iterator pipeline builder, with the special ability to expand and recurse into the children of the current element on demand: when expandChildren() was invoked, the next iteration will continue with the first child element; there is a stack of such "child expansions" – meaning that the search will backtrack and explore further possibilities later on. Each position where the pattern matches the actual tree is marked as possible solution. As a sideeffect, a new coordinate spec to reflect the actual coverage is built and re-written, while the algorithm proceeds. Thus, at any point marked as solution, the current (partial) solution can be retrieved and copied from this PathManipulator buffer. An additional filter layer discriminates the first maximal solutions seen thus far.

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

References stage::interact::UIC_ELIDED.

+ Inheritance diagram for UICoordResolver:
+ Collaboration diagram for UICoordResolver:
The documentation for this class was generated from the following files: