ui-coord.hpp File Reference

A topological addressing scheme to designate structural locations within the UI. More...

Go to the source code of this file.

Description

A topological addressing scheme to designate structural locations within the UI.

Contrary to screen pixel coordinates, we aim at a topological description of the UI structure. This foundation allows us

• to refer to some "place" or "space" within the interface
• to remember and return to such a location
• to move a work focus structurally within the UI
• to describe and configure the pattern view access and arrangement

As starting point, we'll pick the notion of an access path within a hierarchical structure

• the top-level window
• the perspective used within that window
• the panel within this window
• a view group within the panel

• plus a locally defined access path further down to the actual UI element

  Todo:

  WIP 9/2017 first draft ////////////////////////////////////////////////////////////////////////////TICKET #1106 generic UI coordinate system

Note

UICoord is designed with immutability in mind; possibly we may decide to disallow assignment.

Coordinate Builder

Since UI-Coordinates are conceived as immutable values, we provide a distinct Builder notation for the purpose of defining and assembling coordinate specifications. This notation also helps to keep such specifications more readable, since each component is "tagged" with its intended position within the tree, and thus the order of definition is irrelevant. Relying on that notation, it is also possible to write sparse or incomplete coordinate specifications, since each component not explicitly given is assumed to be a wildcard (*). E.g.

UICoord::currentWindow()
        .path("a/b/c")
        .tab(3)
        .view("Timeline")

is translated into the following UI-Coordinate specification

UI::currentWindow[*]-*.Timeline.#3/a/b/c

which indicates the currently active main window, disregarding the perspective, just some panel, holding the view "Timeline", selecting the third tab/group within this view and there to descend the path of local sub-components "c" nested within "b" nested within "a"

Warning

beware, all the builder functions offer a move reference! These builder expressions are intended for typical inline constant expressions according to the builder pattern; any other use, like assignment of the builder itself to a variable might be dangerous, since, after using the builder result just once, the result has been moved away. Even worse, this fact may remain concealed, since short Coordinate specs use inline storage, which the compiler may choose to copy instead of actually moving; only the heap allocated extension will typically be moved.

See also

UICoord_test

id-scheme.hpp

view-spec-dsl.hpp

view-locator.hpp

Definition in file ui-coord.hpp.

#include "lib/error.hpp"
#include "lib/symbol.hpp"
#include "lib/path-array.hpp"
#include "lib/nocopy.hpp"
#include "lib/util.hpp"
#include <cstring>
#include <string>
#include <vector>
#include <utility>

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

Enumerations
enum	{ UIC_INLINE_SIZE = 8 }
enum	UIPathElm {   UIC_WINDOW ,   UIC_PERSP ,   UIC_PANEL ,   UIC_VIEW ,   UIC_TAB ,   UIC_PATH }

Classes
class	UICoord
	Describe a location within the UI through structural/topological coordinates. More...
class	UICoord::Builder

Variables
const Symbol	UIC_CURRENT_WINDOW {"currentWindow"}
	window spec to refer to the current window
const Symbol	UIC_FIRST_WINDOW {"firstWindow"}
	window spec to refer to the first window of the application
const Symbol	UIC_ELIDED {"."}
	indicate that a component is elided or irrelevant here