#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.

Classes
struct	Resolution

Public Member Functions
	UICoordResolver (UICoord const &uic, LocationQuery &queryAPI)

	UICoordResolver (UICoord &&uic, LocationQuery &queryAPI)

bool	isAnchored () const
	is this path explicitly anchored at an existing window?

bool	canAnchor () const
	determine if a mutation is possible to anchor the path explicitly

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

bool	isCovered () const
	this path is completely covered by the currently existing UI structure;

bool	isCoveredTotally () const
	synonymous to isCovered()

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

UICoordResolver &&	cover ()
	mutate the path to get it totally covered

UICoordResolver &&	coverPartially ()
	mutate the path by resolving all wildcards to achieve partial coverage

UICoordResolver &&	anchor ()
	mutate the window part of the path such as to make the anchorage explicit, if possible

UICoordResolver &&	extend (Literal pathExtension)
	mutate the path to extend it while keeping it partially covered

UICoordResolver &&	extend (UICoord const &partialExtensionSpec)
	mutate the path and extend it with components at fixed positions

UICoordResolver &&	existentiallyQuantify (size_t pos)
	mutate to turn a wildcard into existentially quantified.

	operator string () const
	diagnostics

size_t	coverDepth () const

Public Member Functions inherited from UICoord::Builder
	Builder (Builder &&)=default

size_t	size () const

bool	empty () const

UICoord const &	uiCoord ()

Builder &&	window (Literal windowID)
	change UI coordinate spec to define it to be rooted within the given window

Builder &&	persp (Literal perspectiveID)
	augment UI coordinates to mandate a specific perspective to be active within the window

Builder &&	panel (Literal panelID)
	augment UI coordinates to indicate a specific view to be used

Builder &&	view (Literal viewID)
	augment UI coordinates to indicate a specific view to be used

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 &&	noTab ()
	augment UI coordinates to indicate that no tab specification is necessary

Builder &&	append (Literal elm)
	augment UI coordinates by appending a further component at the end.

Builder &&	prepend (Literal elmID)
	augment partially defined UI coordinates by extending them towards the root

Builder &&	path (Literal pathDef)
	augment UI coordinates to define a complete local path

Builder &&	truncateTo (size_t depth)
	possibly shorten this path specification to a limited depth

	operator LocationClause ()
	support for use in the ViewSpec-DSL

LocationClause	create ()
	interprets the current (inline) builder contents as create clause, which has the meaning "create a new element XYZ when possible"

Private Member Functions
void	attempt_trivialResolution ()
	establish a trivial anchorage and coverage, if possible.

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.

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_

Constructor & Destructor Documentation

◆ UICoordResolver() [1/2]

UICoordResolver	(	UICoord const &	uic,
		LocationQuery &	queryAPI
	)

inline

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

References UICoordResolver::attempt_trivialResolution().

Here is the call graph for this function:

◆ UICoordResolver() [2/2]

UICoordResolver	(	UICoord &&	uic,
		LocationQuery &	queryAPI
	)

inline

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

References UICoordResolver::attempt_trivialResolution().

Here is the call graph for this function:

Class Documentation

◆ stage::interact::UICoordResolver::Resolution

struct stage::interact::UICoordResolver::Resolution

Class Members
CStr	anchor = nullptr
size_t	depth = 0
unique_ptr< UICoord >	covfefe {}
bool	isResolved = false

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.

References UICoordResolver::Resolution::anchor, Symbol::BOTTOM, and UICoordResolver::res_.

Referenced by UICoordResolver::canAnchor(), and UICoordResolver::pathResolution().

Here is the caller graph for this function:

◆ 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.

References UICoordResolver::Resolution::covfefe, UICoordResolver::isAnchored(), UICoordResolver::Resolution::isResolved, and UICoordResolver::res_.

Referenced by UICoordResolver::anchor().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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.

References UICoordResolver::Resolution::depth, UICoordResolver::Resolution::isResolved, and UICoordResolver::res_.

Referenced by UICoordResolver::cover(), and UICoordResolver::coverPartially().

Here is the caller graph for this function:

◆ 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.

References UICoordResolver::Resolution::depth, UICoordResolver::Resolution::isResolved, UICoordResolver::res_, PathArray< chunk_size >::size(), and UICoord::Builder::uic_.

Referenced by UICoordResolver::canCover(), UICoordResolver::cover(), UICoordResolver::extend(), and UICoordResolver::isCoveredTotally().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isCoveredTotally()

bool isCoveredTotally ( ) const

inline

synonymous to isCovered()

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

References UICoordResolver::isCovered().

Here is the call graph for this function:

◆ 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.

References UICoordResolver::Resolution::covfefe, UICoordResolver::isCovered(), UICoordResolver::Resolution::isResolved, and UICoordResolver::res_.

Referenced by UICoordResolver::cover(), UICoordResolver::coverPartially(), and UICoordResolver::extend().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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.

References UICoordResolver::Resolution::anchor, UICoordResolver::canCover(), UICoordResolver::Resolution::covfefe, UICoordResolver::Resolution::depth, UICoordResolver::isCovered(), UICoordResolver::isCoveredPartially(), UICoordResolver::Resolution::isResolved, UICoordResolver::res_, UICoord::Builder::truncateTo(), UICoord::Builder::uic_, and UICoord::Builder::window().

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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.

References UICoordResolver::Resolution::anchor, UICoordResolver::canCover(), UICoordResolver::Resolution::covfefe, UICoordResolver::Resolution::depth, UICoord::Builder::empty(), UICoordResolver::isCoveredPartially(), UICoord::isExplicit(), UICoordResolver::Resolution::isResolved, UICoord::Builder::overwrite(), UICoordResolver::res_, PathArray< chunk_size >::size(), UICoord::Builder::truncateTo(), UICoord::Builder::uic_, and UICoord::Builder::window().

Here is the call graph for this function:

◆ 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.

References UICoordResolver::Resolution::anchor, UICoordResolver::canAnchor(), UICoord::Builder::normalise(), UICoordResolver::res_, and UICoord::Builder::window().

Here is the call graph for this function:

◆ extend() [1/2]

UICoordResolver && extend ( Literal pathExtension )

inline

mutate the path to extend it while keeping it partially covered

Parameters

pathExtension a 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 UICoord::Builder::append(), UICoordResolver::cover(), UICoordResolver::Resolution::depth, LocationQuery::determineCoverage(), UICoordResolver::isCovered(), UICoordResolver::query_, UICoordResolver::res_, and UICoord::Builder::uic_.

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

partialExtensionSpec UI coordinates used as extension

Exceptions

if	the 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 UICoordResolver::attempt_trivialResolution(), PathArray< chunk_size >::begin(), UICoordResolver::canCover(), UICoordResolver::cover(), UICoordResolver::Resolution::covfefe, UICoordResolver::Resolution::depth, PathArray< chunk_size >::indexOf(), UICoordResolver::Resolution::isResolved, UICoord::Builder::normalise(), UICoord::Builder::overwrite(), UICoord::rebuild(), UICoordResolver::res_, UICoord::Builder::truncateTo(), and UICoord::Builder::uic_.

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 UICoord::isPresent(), UICoord::Builder::overwrite(), PathArray< chunk_size >::size(), UICoord::Builder::uic_, and stage::interact::UIC_ELIDED.

Referenced by UILocationSolver::preprocess().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator string()

operator string ( ) const

inline

diagnostics

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

References UICoord::Builder::uic_.

◆ coverDepth()

size_t coverDepth ( ) const

inline

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

References UICoordResolver::Resolution::depth.

◆ 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 UICoordResolver::Resolution::anchor, util::contains(), UICoordResolver::Resolution::depth, LocationQuery::determineAnchor(), LocationQuery::determineCoverage(), UICoord::isExplicit(), UICoordResolver::Resolution::isResolved, UICoordResolver::query_, UICoordResolver::res_, UICoord::Builder::uic_, and stage::interact::UIC_ELIDED.

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

Here is the call graph for this function:

Here is the caller 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 UICoordResolver::Resolution::anchor, Symbol::ANY, UICoordResolver::Resolution::covfefe, UICoordResolver::Resolution::depth, LocationQuery::determineCoverage(), Symbol::EMPTY, LocationQuery::getChildren(), UICoordResolver::isAnchored(), UICoordResolver::Resolution::isResolved, UICoordResolver::query_, UICoordResolver::res_, PathArray< chunk_size >::size(), UICoord::Builder::uic_, stage::interact::UIC_ELIDED, and stage::interact::UIC_WINDOW.

Here is the call graph for this function:

Member Data Documentation

◆ query_

LocationQuery& query_

private

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

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

◆ res_

Resolution res_

private

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

Referenced by UICoordResolver::anchor(), UICoordResolver::attempt_trivialResolution(), UICoordResolver::canAnchor(), UICoordResolver::canCover(), UICoordResolver::cover(), UICoordResolver::coverPartially(), UICoordResolver::extend(), UICoordResolver::extend(), UICoordResolver::isAnchored(), UICoordResolver::isCovered(), UICoordResolver::isCoveredPartially(), and UICoordResolver::pathResolution().

Inheritance diagram for UICoordResolver:

Collaboration diagram for UICoordResolver:

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

Description

Classes

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ UICoordResolver() [1/2]

◆ UICoordResolver() [2/2]

Class Documentation

◆ stage::interact::UICoordResolver::Resolution

Member Function Documentation

◆ isAnchored()

◆ canAnchor()

◆ isCoveredPartially()

◆ isCovered()

◆ isCoveredTotally()

◆ canCover()

◆ cover()

◆ coverPartially()

◆ anchor()

◆ extend() [1/2]

◆ extend() [2/2]

◆ existentiallyQuantify()

◆ operator string()

◆ coverDepth()

◆ attempt_trivialResolution()

◆ pathResolution()

Member Data Documentation

◆ query_

◆ res_