Description

Evaluation of UI coordinates against a concrete window topology.

UI-Coordinates allow to describe and locate an interface component within the Lumiera GUI through a topological access path. As such these coordinate specifications are abstract, and need to be related, attached or resolved against the actual configuration of widgets in the UI. Through this relation it becomes possible to pose meaningful queries over these coordinates, or to build, rebuild and remould a coordinate specification.

We need to avoid tainting with the intrinsics of the actual UI toolkit though – which indicates the UICoordResolver should be designed as an abstract intermediary, built on top of a command and query interface, provided by the Navigator and backed by the actual UI configuration.

Abstraction

The abstraction used to found this interface is twofold. For one, we rely on the notion of logical, topological Coordinates in User Interface space. And secondly, we rely on a very limited form of navigation: we navigate a tree-shaped (abstracted) structure just by

iteration over siblings, which are children of our previous starting point
the ability, on this iterator, to expand the "current child" and inject the next level of child iteration at its place, similar to the flatMap operation known from functional programming. Together, these two capabilities allow us to build exploring and backtracking evaluations, which is enough to build a secondary helper component on top, the stage::interact::UICoordResolver

UI coordinate path evaluation

Such a resolver can be used to relate and match a given, incomplete UI coordinate specification (a "pattern") against the actual UI topology. Evaluation is accomplished by first constituting an anchoring, followed by traversal of the coordinate spec and matching against a navigation path within the actual UI window configuration. This process might involve interpretation of some meta-symbols and interpolation of wildcards.

As indicated above, the coordinate resolver internally relies on a context query interface, to find out about existing windows, panels, views and tabs and to navigate the real UI structure. The actual implementation of this context query interface is backed by the Navigator component exposed through the InteractionDirector.

Query operations

In addition to the locally decidable properties of a coordinate spec, which are the explicitness and the presence of some component, several contextual predications may be queried:

anchorage ** the way the given coordinate spec is or can be anchored *** it is already explicitly anchored by referring either to a specific window or by generic specification *** it can be a anchored by interpolation of some wildcards *** it is incomplete and need to be extended to allow anchoring *** it is impossible to anchor in the current UI configuration
coverage ** the extent to which a given coordinate spec is backed by the actual UI configuration ** please note: to determine the coverage, the spec needs to be anchored, either explicitly, or by interpolation, or by extension of an incomplete spec *** it is completely covered *** it is partially covered with an remaining, uncovered extension part *** it is possible to cover completely *** it is impossible to cover related to the current UI topology

Some fine points to note: Anchorage and coverage are not the same thing, but coverage implies anchorage. Only when a path is complete (i.e. it starts with the window spec) and explicit (has no wildcards), then anchorage implies also partial coverage (namely at least to depth 1). To determine the possibility of coverage means to perform a resolution with backtracking to pick the maximal solution. Moreover, since "covered" means that the path specification is at least partially supported by the real UI, we establish an additional constraint to ensure this resolution did not just match some arbitrary wildcards. Rather we demand that behind rsp. below the last wildcard there is at least one further explicit component in the path spec, which is supported by the real UI. As a consequence, the coverage resolution may fail altogether, while still providing at least a possible anchor point.

Mutations

In addition to querying the interpretation of a given coordinate spec with respect to the current UI environment, it is also possible to rewrite or extend the spec based on this environment

anchoring ** in correspondence to the possible states of anchorage, we may derive an explicitly anchored spec *** by interpolating the given spec *** by interpretation and extension of the given spec
covering ** we may construct the covered part of a given spec, which includes automatic anchoring
extending ** a given UI coordinate pattern is covered... ** and truncated to the covered part ** the given extension suffix is then attached behind

See also: UICoordResolver_test; UICoord_test; navigator.hpp; view-locator.hpp

Definition in file ui-coord-resolver.hpp.

#include "lib/error.hpp"
#include "lib/symbol.hpp"
#include "lib/format-string.hpp"
#include "stage/interact/ui-coord.hpp"
#include "lib/iter-explorer.hpp"
#include "lib/iter-source.hpp"
#include "lib/depend.hpp"
#include "lib/util.hpp"
#include <utility>
#include <memory>

Classes
class	LocationQuery
	Interface to discover a backing structure for the purpose of path navigation and resolution. More...

struct	UICoordResolver::Resolution

class	TreeStructureNavigator
	Interface to locate and move within a tree shaped structure. More...

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

Namespaces
	stage
	Lumiera GTK UI implementation root.

	stage::interact
	UI interaction control.

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: