ui-location-solver.hpp File Reference

Go to the source code of this file.

Description

A solver to match incomplete coordinate specifications against the actual UI topology.

Within the Lumiera UI, a component view is typically created or retrieved to live at some position within the tree-like topology of the interface. Such happens as a consequence of interaction or other events, and the logic as to where and how to place a new UI element shall not be intermingled with the actual event handling code. Rather, the ViewLocator, as a service related to the InteractionDirector, can be invoked to draw on some default configuration plus the actual UI topology present at this time.

Pattern matching against the actual UI-tree

This Location solver is based on the pattern matching algorithm embedded within the UICoordResolver component. This mechanism allows to treat (typically) incomplete coordinate specifications as rules for locating an element. Several such coordinate clauses can be combined into a disjunctive LocationRule, which is evaluated by matching the clauses one by one, in given order, against the currently existing UI tree (topology). Each clause is evaluated individually from scratch (there is no common variable binding); the first clause to produce a successful match is used as solution – with any placeholders replaced by the actually matching UI elements.

Default View location configuration DSL

Whenever a new UI element of a given kind is to be created, we query a standard location configuration to determine it's actual location within the interface. This standard configuration is known as id-scheme.hppViewSpec DSL"" and hard-wired into the UI code. Based on the aforementioned pattern matching rules, it allows to express placement rules dependent on the already existing UI. There are two kinds of location clauses

• the standard rules describe an element required to exist. Typically this is the parent element of the UI widget in question. But it is also possible to write clauses directly mentioning this element, in which case such an element must already exist in the UI and will be retrieved as result.
• the more relaxed create clauses describe a new location / path within the UI-tree, meaning that any (parent) elements not yet present are to be created. A create clause is defined within the DSL by ending a UI coordinate specification with the term .create(). It may still be incomplete (i.e. contain wildcards), which means, that the first explicitly given element after (below) the wildcards must exist in the tree, to allow for an unambiguous pattern match. Otherwise, for creating a new path completely from scratch, all elements have to be given explicitly. As a minimum requirement, each LocationRule should be concluded with such a "catch-all" explicit create clause, which describes the standard location of the element in question.

Todo:

as of 2017 .. 2021, this is a half-finished draft and postponed in favour of building the actually visible timeline display first

See also

UILocationSolver_test

ViewSpecDSL_test

UICoordResolver

view-locator.hpp

Definition in file ui-location-solver.hpp.

#include "lib/error.hpp"
#include "lib/symbol.hpp"
#include "lib/format-util.hpp"
#include "stage/interact/ui-coord.hpp"
#include "stage/interact/ui-coord-resolver.hpp"
#include "lib/nocopy.hpp"
#include <utility>
#include <vector>
#include <string>

Classes
struct	LocationClause
	A single location specification to be matched and fulfilled. More...
class	LocationRule
	A rule to determine some location by matching against the UI-tree. More...
class	UILocationSolver
	Service to determine the location of an UI component view. More...

Typedefs
using	LocationQueryAccess = std::function< LocationQuery &()>

Functions
LocationRule	operator or (UICoord::Builder &&firstRule, UICoord secondRule)
	DSL operator to assemble a sequence of clauses. More...
LocationRule &&	operator or (LocationRule &&ruleSet, UICoord furtherRule)

Namespaces
	stage
	Lumiera GTK UI implementation root.
	stage::interact
	UI interaction control.