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

Description

Describe a location within the UI through structural/topological coordinates.

A UICoord specification is a sequence of Literal tokens, elaborating a path descending through the hierarchy of UI elements down to the specific UI element to refer.

See also: UICoord_test

Definition at line 129 of file ui-coord.hpp.

Classes
class	Builder

Static Public Member Functions
static Builder	firstWindow ()
	Builder: start definition of UI-Coordinates rooted in the `firstWindow`

static Builder	currentWindow ()
	Builder: start definition of UI-Coordinates rooted in the `currentWindow`

static Builder	window (Literal windowID)
	Builder: start definition of UI-Coordinates rooted in given window.

Public Member Functions
template<typename... ARGS>
	UICoord (ARGS &&...args)
	UI-Coordinates can be created explicitly by specifying a sequence of Literal tokens, which will be used to initialise and then normalise the underlying PathArray.

	UICoord (UICoord &&)=default

	UICoord (UICoord const &)=default

	UICoord (UICoord &o)

UICoord &	operator= (UICoord const &)=default

UICoord &	operator= (UICoord &&)=default

	UICoord (Builder &&builder)
	shortcut to allow init from builder expression

Builder	persp (Literal perspectiveID) const

Builder	panel (Literal panelID) const

Builder	view (Literal viewID) const

Builder	tab (Literal tabID) const

Builder	tab (uint tabIdx) const

Builder	noTab () const

Builder	path (Literal pathDefinition) const
	convenience builder function so set a full path definition

Builder	append (Literal elmID) const

Builder	prepend (Literal elmID) const

Builder	rebuild () const

Literal	getWindow () const

Literal	getPersp () const

Literal	getPanel () const

Literal	getView () const

Literal	getTab () const

bool	isIncomplete () const

bool	isComplete () const

bool	isExplicit () const

bool	isPresent (size_t idx) const

bool	isWildcard (size_t idx) const

bool	isExtendedBelow (UICoord const &parent) const
	Check if this coordinate spec can be seen as an extension of the given parent coordinates and thus reaches further down towards specific UI elements in comparison to the parent path This constitutes a partial order, since some paths might just be totally unrelated to each other and thus not comparable.

	operator string () const

string	getComp () const

string	getPath () const

iterator	pathSeq () const
	iterative access to the path sequence section

Public Member Functions inherited from PathArray< UIC_INLINE_SIZE >
	PathArray (ARGS &&...args)

	PathArray (PathArray &&)=default

	PathArray (PathArray const &)=default

	PathArray (PathArray &o)

PathArray &	operator= (PathArray const &)=default

PathArray &	operator= (PathArray &&)=default

size_t	size () const

size_t	leafLevel () const

bool	empty () const

	operator string () const
	joins nonempty content, separated by slash

Literal const &	operator[] (size_t idx) const
	Array style indexed access.

size_t	indexOf (Literal const &content) const
	reverse lookup of actual path content

iterator	begin () const

iterator	end () const

Friends
class	Builder

bool	operator== (UICoord const &l, UICoord const &r)

bool	operator< (UICoord const &l, UICoord const &r)

bool	operator> (UICoord const &l, UICoord const &r)

bool	operator<= (UICoord const &l, UICoord const &r)

bool	operator>= (UICoord const &l, UICoord const &r)

bool	operator!= (UICoord const &l, UICoord const &r)

Private Member Functions
size_t	findStartIdx () const

Literal	accesComponent (UIPathElm idx) const

void	setComponent (size_t idx, Literal newContent)

void	setTailSequence (size_t idx, Literal newContent)
	replace / overwrite existing content starting at given index.

void	setTailSequence (size_t idx, std::vector< Literal > &pathElms)
	replace the existing path information with the given elements

Additional Inherited Members
Public Types inherited from PathArray< UIC_INLINE_SIZE >
using	const_iterator = lib::IterAdapter< Literal const , PathArray const >

using	iterator = const_iterator

using	value_type = Literal

using	reference = Literal &

using	const_reference = Literal const &

Protected Member Functions inherited from PathArray< UIC_INLINE_SIZE >
Literal *	getPosition (size_t idx)

Literal *	expandPosition (size_t idx)

void	setContent (Literal pos, const char val)

void	truncateTo (size_t newSize)

void	normalise ()
	establish the contract of PathArray

Constructor & Destructor Documentation

◆ UICoord() [1/5]

template<typename... ARGS>

UICoord ( ARGS &&... args )

inlineexplicit

UI-Coordinates can be created explicitly by specifying a sequence of Literal tokens, which will be used to initialise and then normalise the underlying PathArray.

Warning: Literal means _"literal"_ with guaranteed storage during the whole execution.

Remarks

- in case you need to construct some part, then use Symbol to intern the resulting string into the global static SymbolTable.

usually the Builder API leads to more readable definitions, explicitly indicating the meaning of the coordinate's parts.

Definition at line 145 of file ui-coord.hpp.

◆ UICoord() [2/5]

UICoord ( UICoord && )

default

◆ UICoord() [3/5]

UICoord ( UICoord const & )

default

◆ UICoord() [4/5]

UICoord ( UICoord & o )

inline

Definition at line 149 of file ui-coord.hpp.

◆ UICoord() [5/5]

UICoord ( Builder && builder )

inline

shortcut to allow init from builder expression

Note: this ctor is used to "fix" and normalise the contents established in the Builder thus far.

Definition at line 659 of file ui-coord.hpp.

Member Function Documentation

◆ operator=() [1/2]

UICoord & operator= ( UICoord const & )

default

◆ operator=() [2/2]

UICoord & operator= ( UICoord && )

default

References UICoord::panel(), and UICoord::path().

Here is the call graph for this function:

◆ firstWindow()

UICoord::Builder firstWindow ( )

inlinestatic

Builder: start definition of UI-Coordinates rooted in the firstWindow

Definition at line 676 of file ui-coord.hpp.

References stage::interact::UIC_FIRST_WINDOW, and UICoord::window().

Referenced by UICoordResolver_test::verify_backingQuery(), UILocationSolver_test::verify_cornerCases(), UICoordResolver_test::verify_mutateAnchor(), UICoordResolver_test::verify_mutateCoverage(), and UICoordResolver_test::verify_queryAnchor().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ currentWindow()

UICoord::Builder currentWindow ( )

inlinestatic

Builder: start definition of UI-Coordinates rooted in the currentWindow

Returns: a minimally defined Builder, allowing to define further parts; to finish the definition, cast / store it into UICoord, which itself is immutable.

Definition at line 670 of file ui-coord.hpp.

References stage::interact::UIC_CURRENT_WINDOW, and UICoord::window().

Referenced by UICoordResolver_test::verify_backingQuery(), UILocationSolver_test::verify_cornerCases(), UICoordResolver_test::verify_mutateAnchor(), UICoordResolver_test::verify_mutateCoverage(), UICoordResolver_test::verify_mutateCoverPartially(), UICoordResolver_test::verify_mutateExtend(), UICoordResolver_test::verify_queryAnchor(), UILocationSolver_test::verify_standardSituations(), and ViewSpecDSL_test::verify_standardUsage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ window()

UICoord::Builder window ( Literal windowID )

inlinestatic

Builder: start definition of UI-Coordinates rooted in given window.

Returns: a Builder with just the windowID defined

Definition at line 683 of file ui-coord.hpp.

Referenced by UICoord::currentWindow(), UICoord::firstWindow(), UICoordResolver_test::verify_backingQuery(), UICoord_test::verify_builder(), UILocationSolver_test::verify_cornerCases(), UICoordResolver_test::verify_mutateAnchor(), UICoordResolver_test::verify_mutateCoverage(), UICoordResolver_test::verify_queryAnchor(), and UILocationSolver_test::verify_standardSituations().

Here is the caller graph for this function:

◆ persp()

UICoord::Builder persp ( Literal perspectiveID ) const

inline

Returns: a Builder holding a clone copy of the original UICoord, with the perspective information set to a new value.

Remarks: This Builder can then be used do set further parts independently of the original. When done, store it as new UICoord object. To achieve real mutation, assign it to the original variable.

Definition at line 696 of file ui-coord.hpp.

References UICoord::Builder::persp().

Referenced by UICoord_test::verify_builder(), UILocationSolver_test::verify_cornerCases(), UICoordResolver_test::verify_mutateCoverage(), UICoordResolver_test::verify_mutateExtend(), UILocationSolver_test::verify_standardSituations(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ panel()

UICoord::Builder panel ( Literal panelID ) const

inline

Definition at line 702 of file ui-coord.hpp.

References UICoord::Builder::panel().

Referenced by UICoord::operator=(), UILocationSolver_test::simple_usage_example(), and UICoordResolver_test::verify_mutateCoverage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ view()

UICoord::Builder view ( Literal viewID ) const

inline

Definition at line 708 of file ui-coord.hpp.

References UICoord::Builder::view().

Referenced by UICoord_test::verify_builder(), UICoordResolver_test::verify_mutateAnchor(), UICoordResolver_test::verify_mutateCoverage(), UICoordResolver_test::verify_mutateExtend(), UICoordResolver_test::verify_queryAnchor(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ tab() [1/2]

UICoord::Builder tab ( Literal tabID ) const

inline

Definition at line 714 of file ui-coord.hpp.

References UICoord::Builder::tab().

Referenced by UICoord_test::verify_builder(), UICoordResolver_test::verify_mutateCoverage(), ViewSpecDSL_test::verify_standardUsage(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ tab() [2/2]

UICoord::Builder tab ( uint tabIdx ) const

inline

Definition at line 720 of file ui-coord.hpp.

References UICoord::Builder::tab().

Here is the call graph for this function:

◆ noTab()

UICoord::Builder noTab ( ) const

inline

Definition at line 726 of file ui-coord.hpp.

References UICoord::Builder::noTab().

Referenced by UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ path()

UICoord::Builder path ( Literal pathDefinition ) const

inline

convenience builder function so set a full path definition

Note: the given path string will be split at ‘’/'` and the resulting components will be stored/retrieved as Symbol

Definition at line 737 of file ui-coord.hpp.

References UICoord::Builder::path().

Referenced by UICoord::operator string(), UICoord::operator=(), UICoord_test::verify_builder(), UILocationSolver_test::verify_cornerCases(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ append()

UICoord::Builder append ( Literal elmID ) const

inline

Definition at line 743 of file ui-coord.hpp.

References UICoord::Builder::append().

Referenced by UICoord_test::verify_builder(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ prepend()

UICoord::Builder prepend ( Literal elmID ) const

inline

Definition at line 749 of file ui-coord.hpp.

References UICoord::Builder::prepend().

Referenced by UICoord_test::verify_builder(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rebuild()

UICoord::Builder rebuild ( ) const

inline

Definition at line 755 of file ui-coord.hpp.

Referenced by ElementAccess::access(), UICoordResolver::extend(), ElementAccess::locate_or_create(), and UILocationSolver_test::verify_cornerCases().

Here is the caller graph for this function:

◆ getWindow()

Literal getWindow ( ) const

inline

Definition at line 190 of file ui-coord.hpp.

References UICoord::accesComponent(), and stage::interact::UIC_WINDOW.

Referenced by GenNodeLocationQuery::determineAnchor(), UICoord::getComp(), UICoord::isComplete(), UICoord::isIncomplete(), and UICoord_test::verify_builder().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getPersp()

Literal getPersp ( ) const

inline

Definition at line 191 of file ui-coord.hpp.

References UICoord::accesComponent(), and stage::interact::UIC_PERSP.

Referenced by UICoord::getComp(), and UICoord_test::verify_builder().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getPanel()

Literal getPanel ( ) const

inline

Definition at line 192 of file ui-coord.hpp.

References UICoord::accesComponent(), and stage::interact::UIC_PANEL.

Referenced by UICoord::getComp(), and UICoord_test::verify_builder().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getView()

Literal getView ( ) const

inline

Definition at line 193 of file ui-coord.hpp.

References UICoord::accesComponent(), and stage::interact::UIC_VIEW.

Referenced by UICoord::getComp(), UICoord_test::verify_builder(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getTab()

Literal getTab ( ) const

inline

Definition at line 194 of file ui-coord.hpp.

References UICoord::accesComponent(), and stage::interact::UIC_TAB.

Referenced by UICoord::getComp(), UICoord_test::verify_builder(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isIncomplete()

bool isIncomplete ( ) const

inline

Remarks: incomplete UI-Coordinates have some fragment of the path defined, but lacks the definition of an anchor point, i.e. it has no window ID

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

References PathArray< UIC_INLINE_SIZE >::empty(), and UICoord::getWindow().

Referenced by UICoord::Builder::prepend(), and UICoord_test::verify_localPredicates().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isComplete()

bool isComplete ( ) const

inline

Definition at line 213 of file ui-coord.hpp.

References PathArray< UIC_INLINE_SIZE >::empty(), and UICoord::getWindow().

Referenced by UICoord::isExplicit(), UILocationSolver::preprocess(), and UICoord_test::verify_localPredicates().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isExplicit()

bool isExplicit ( ) const

inline

Remarks: an explicit coordinate spec does not use wildcards and is anchored in a window spec

Definition at line 225 of file ui-coord.hpp.

References Symbol::ANY, util::contains(), and UICoord::isComplete().

Referenced by UICoordResolver::attempt_trivialResolution(), UICoordResolver::coverPartially(), and UICoord_test::verify_localPredicates().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isPresent()

bool isPresent ( size_t idx ) const

inline

Definition at line 233 of file ui-coord.hpp.

References Symbol::ANY.

Referenced by GenNodeLocationQuery::determineAnchor(), GenNodeLocationQuery::drillDown(), UICoordResolver::existentiallyQuantify(), and GenNodeLocationQuery::resolveElm().

Here is the caller graph for this function:

◆ isWildcard()

bool isWildcard ( size_t idx ) const

inline

Definition at line 242 of file ui-coord.hpp.

References Symbol::ANY.

◆ isExtendedBelow()

bool isExtendedBelow ( UICoord const & parent ) const

inline

Check if this coordinate spec can be seen as an extension of the given parent coordinates and thus reaches further down towards specific UI elements in comparison to the parent path This constitutes a partial order, since some paths might just be totally unrelated to each other and thus not comparable.

Note: we tolerate (but not demand) expansion/interpolation of the given parent, i.e. parent may be incomplete or contain ‘’*'` placeholders.

Todo:: 10/2017 have to verify suitability of this definition

Definition at line 262 of file ui-coord.hpp.

References Symbol::ANY, PathArray< chunk_size >::size(), and PathArray< UIC_INLINE_SIZE >::size().

Here is the call graph for this function:

◆ operator string()

operator string ( ) const

inlineexplicit

Definition at line 286 of file ui-coord.hpp.

References UICoord::getComp(), UICoord::getPath(), and UICoord::path().

Here is the call graph for this function:

◆ getComp()

string getComp ( ) const

inline

Definition at line 304 of file ui-coord.hpp.

References PathArray< UIC_INLINE_SIZE >::begin(), PathArray< UIC_INLINE_SIZE >::empty(), PathArray< UIC_INLINE_SIZE >::end(), UICoord::getPanel(), UICoord::getPersp(), UICoord::getTab(), UICoord::getView(), UICoord::getWindow(), PathArray< UIC_INLINE_SIZE >::indexOf(), PathArray< UIC_INLINE_SIZE >::size(), stage::interact::UIC_ELIDED, stage::interact::UIC_PANEL, stage::interact::UIC_PATH, stage::interact::UIC_PERSP, stage::interact::UIC_TAB, stage::interact::UIC_VIEW, and stage::interact::UIC_WINDOW.

Referenced by UICoord::operator string(), UICoord_test::verify_builder(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getPath()

string getPath ( ) const

inline

Definition at line 345 of file ui-coord.hpp.

References PathArray< UIC_INLINE_SIZE >::begin(), UICoord::pathSeq(), PathArray< UIC_INLINE_SIZE >::size(), and stage::interact::UIC_PATH.

Referenced by UICoord::operator string(), UICoord_test::verify_builder(), and UICoord_test::verify_stringRepr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ pathSeq()

iterator pathSeq ( ) const

inline

iterative access to the path sequence section

Definition at line 373 of file ui-coord.hpp.

References PathArray< UIC_INLINE_SIZE >::end(), PathArray< UIC_INLINE_SIZE >::size(), and stage::interact::UIC_PATH.

Referenced by UICoord::getPath().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ findStartIdx()

size_t findStartIdx ( ) const

inlineprivate

Definition at line 385 of file ui-coord.hpp.

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

Referenced by UICoord::Builder::prepend().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ accesComponent()

Literal accesComponent ( UIPathElm idx ) const

inlineprivate

Definition at line 392 of file ui-coord.hpp.

References Symbol::EMPTY.

Referenced by UICoord::getPanel(), UICoord::getPersp(), UICoord::getTab(), UICoord::getView(), and UICoord::getWindow().

Here is the caller graph for this function:

◆ setComponent()

void setComponent	(	size_t	idx,
		Literal	newContent
	)

inlineprivate

Definition at line 399 of file ui-coord.hpp.

References PathArray< UIC_INLINE_SIZE >::expandPosition(), and PathArray< UIC_INLINE_SIZE >::setContent().

Referenced by UICoord::Builder::noTab(), UICoord::Builder::panel(), UICoord::Builder::persp(), UICoord::Builder::prepend(), UICoord::Builder::tab(), UICoord::Builder::tab(), UICoord::Builder::view(), and UICoord::Builder::window().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setTailSequence() [1/2]

void setTailSequence	(	size_t	idx,
		Literal	newContent
	)

inlineprivate

replace / overwrite existing content starting at given index.

Parameters

idx	where to start adding content; storage will be expanded to accommodate
newContent	either a single element, or several elements delimited by ‘’/' `@note - a path sequence will be split at`'/'` and the components interned any excess elements will be cleared

Warning: need to invoke PathArray::normalise() afterwards

Definition at line 414 of file ui-coord.hpp.

References UICoord::setTailSequence().

Referenced by UICoord::Builder::append(), UICoord::Builder::path(), and UICoord::setTailSequence().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setTailSequence() [2/2]

void setTailSequence	(	size_t	idx,
		std::vector< Literal > &	pathElms
	)

inlineprivate

replace the existing path information with the given elements

Note

- storage will possibly be expanded to accommodate

the individual path elements are required to persist
any excess elements will be cleared
the pathElms can be empty in which case just any content starting from idx will be cleared

Warning: need to invoke PathArray::normalise() afterwards

Definition at line 454 of file ui-coord.hpp.

References PathArray< UIC_INLINE_SIZE >::end(), PathArray< UIC_INLINE_SIZE >::expandPosition(), PathArray< UIC_INLINE_SIZE >::setContent(), and PathArray< UIC_INLINE_SIZE >::size().

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ Builder

friend class Builder

friend

Note: Builder allowed to manipulate stored data

Definition at line 382 of file ui-coord.hpp.

◆ operator==

bool operator==	(	UICoord const &	l,
		UICoord const &	r
	)

friend

Definition at line 469 of file ui-coord.hpp.

◆ operator<

bool operator<	(	UICoord const &	l,
		UICoord const &	r
	)

friend

Definition at line 474 of file ui-coord.hpp.

◆ operator>

bool operator>	(	UICoord const &	l,
		UICoord const &	r
	)

friend

Definition at line 480 of file ui-coord.hpp.

◆ operator<=

bool operator<=	(	UICoord const &	l,
		UICoord const &	r
	)

friend

Definition at line 481 of file ui-coord.hpp.

◆ operator>=

bool operator>=	(	UICoord const &	l,
		UICoord const &	r
	)

friend

Definition at line 482 of file ui-coord.hpp.

◆ operator!=

bool operator!=	(	UICoord const &	l,
		UICoord const &	r
	)

friend

Definition at line 483 of file ui-coord.hpp.

Inheritance diagram for UICoord:

Collaboration diagram for UICoord:

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

ui-coord.hpp

Description

Classes

Static Public Member Functions

Public Member Functions

Friends

Private Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ UICoord() [1/5]

◆ UICoord() [2/5]

◆ UICoord() [3/5]

◆ UICoord() [4/5]

◆ UICoord() [5/5]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ firstWindow()

◆ currentWindow()

◆ window()

◆ persp()

◆ panel()

◆ view()

◆ tab() [1/2]

◆ tab() [2/2]

◆ noTab()

◆ path()

◆ append()

◆ prepend()

◆ rebuild()

◆ getWindow()

◆ getPersp()

◆ getPanel()

◆ getView()

◆ getTab()

◆ isIncomplete()

◆ isComplete()

◆ isExplicit()

◆ isPresent()

◆ isWildcard()

◆ isExtendedBelow()

◆ operator string()

◆ getComp()

◆ getPath()

◆ pathSeq()

◆ findStartIdx()

◆ accesComponent()

◆ setComponent()

◆ setTailSequence() [1/2]

◆ setTailSequence() [2/2]

Friends And Related Symbol Documentation

◆ Builder

◆ operator==

◆ operator<

◆ operator>

◆ operator<=

◆ operator>=

◆ operator!=