TreeView - ObjectVision/GeoDMS GitHub Wiki

User Guide GeoDMS GUI - TreeView

This screenshot predates the 20.17.0 icon set described below.

The Treeview is the main navigation component of the application. It presents the hierarchical structure of a configuration in a view like the Windows Explorer. By default, the first level items are shown (the root item is not shown, its name is presented in the title bar). Each item in the tree (called a Tree item) is presented with a name and an icon.

The selected item in the Treeview is the active item in the application. This is an important concept, as many functions of the application work on the active tree item. By clicking the right mouse button a pop-up menu can be activated, with a set of menu options that work on this active tree item. The Detail pages also present information on this active item.

Since GeoDMS 20.9.0, with Settings > GUI options > Show hidden items activated, a container named prelude shows up among the first-level items of every configuration. It is not part of the configuration and is never written back to it: the GeoDMS adds the standard function definitions it ships in prelude.dms, next to the executable, to each loaded tree as a hidden container, so that sqr, rescale, MakeDefined and their kin can be called without configuring them. They used to be untyped rewrite rules inside the engine -- see GeoDMS GUI, section the standard prelude, for what that means for name resolution and why it changed.

The icon tells you what kind of item you are looking at and, for data items and containers, which default viewer will be used for it. Double-clicking or pressing the Enter key on a selected tree item activates that viewer.

Since GeoDMS 20.17.0 the icon set is larger and the icons are drawn from a font instead of from bitmaps, so they stay sharp when Windows scales the interface. Units now have icons of their own, and which icon an item gets is decided by what the item is rather than by which views can be opened on it. Two long-standing oddities disappear with that:

• a unit that happened to have subitems used to be drawn as a container -- it is now drawn as a unit;
• a container with no subitems at all matched none of the old rules and fell through to the measuring-tape icon, which is why empty containers looked like units. The measuring tape now marks a base unit only.

icon	description
	A data item that can be viewed in a map. This implies the domain unit of the data item has a geographic relation (see how to model for How to configure a coordinate system). Dependent on the geographic domain, the data is visualized in a grid, point, arc or polygon layer
	A data item that cannot be visualised on a map (it has no geographic relation), its default viewer is a table. The icon is one column of the table its domain unit carries, which is the whole table.
	A data item that contains a palette (a set of colour values, corresponding to a classification) or a set of class breaks. Class-break attributes used to get the table icon.
	A container, not containing data items as direct subitems -- also when it has no subitems at all.
	A container, containing data items as direct subitems, whose default viewer is a table.
	A template definition.
	A function definition. A function body is inert like a template body, so before 20.17.0 the two shared the template icon; the box now carries the letter that tells them apart.
	A grid domain: a domain unit over a two-dimensional value type such as spoint or upoint.
	Any other domain unit, i.e. a countable unit such as unit<uint32>. It is drawn as the whole table, the attributes over it being its columns.
	A base unit: a unit whose metric is a single symbol, as BaseUnit(symbol, valuetype) yields. A unit that declares a projected SpatialReference in metres gets this icon too -- see below.
	Any other values unit, i.e. one whose metric is derived (m/s, 1000 * m) or absent. A two-dimensional coordinate unit such as unit<fpoint> rdc is one of these, not a grid domain: it is not countable.

Items within a template are drawn in grey, as they were before.

Since GeoDMS 20.18.0 the Main menu and the title bars of the view windows draw their icons from this same set. A tree icon and a menu icon say different things, though: this one says what an item is, while a menu icon says which view that entry opens.

A unit that declares a projected coordinate reference system measured in metres carries the metric m, and is therefore drawn as the base unit it is -- with the compass badge beside it, since it is also georeferenced:

unit<fpoint> rdc_base : SpatialReference = "EPSG:28992";   // measuring tape + compass

That metric is what makes area(geom, m2) work over such a chain (GeoDMS #1119). A geographic CRS such as EPSG:4326 is measured in degrees and deliberately carries no metric, so it shows the values-unit icon instead. A unit derived from a CRS-bearing one -- range(rdc_base, …), gridset(rdc, …) -- carries the projection rather than the metric, so it keeps its own icon and inherits only the compass.

Starting from version 19.2.0, the TreeView utilises a combination of text colours, background colours, and status badges to provide detailed information about data provenance, calculation states, and integrity.

The colour of the tree item name indicates the origin of the data:

The background colour represents the current status of the calculation process and the application's "interest" in the item:

Since GeoDMS 20.19.2 the active tree item -- the item the Detail pages describe and the item every menu option acts on -- is marked by tinting its background colour with the selection colour of the desktop theme, and, while the TreeView has the keyboard focus, by a dotted caret drawn around it.

Before, nothing marked the active item at all: no colour change and no caret. A thin blue outline was meant to mark it, but the item background was painted over that outline before it ever reached the screen, so in practice the TreeView gave no sign of which item it was on. After clicking in a Map View, a Table View or the Eventlog there was likewise nothing to say which item the Detail pages were still describing.

The state colour is tinted rather than replaced, because a full selection fill would hide the calculation state that the background colour stands for. Where a state colour happens to be the selection colour itself -- a blue standby item under the default Windows theme -- the tint is lightened or darkened instead, so that an active item never ends up looking like an inactive one.

The colours are taken from the desktop theme rather than being fixed, so they follow the accent colour and dark mode, with Settings > GUI options > Follow OS layout either on or off. On a machine on which GeoDMS has never run, that option is off.

Small icons (badges) provide additional context regarding data integrity and storage status.

These badges indicate the results of configured integrity checks:

• Red Cross: The integrity check failed on this specific item.
• Orange Cross: An integrity check failed somewhere in the supply chain (upstream) of this item.
• Green Checkmark: The integrity check for this item passed successfully.
• Green Ring: All integrity checks in the supply chain passed successfully.
• Three Dots (...): Integrity checks exist in the supply chain, but not all have been evaluated yet.

These badges indicate the status of data persistence and external access:

Diskette Icons (Data Targets)

• Grey Diskette: A data target is configured, but the data has not been saved yet.
• Black Diskette: Data is successfully saved (Committed).
• Red Diskette: A write error occurred while trying to save the data.

Database Icons (Data Sources)

• Grey DB: Data is available to be read but has not been accessed yet.
• Black DB: Data has been successfully read from the source.
• Red DB: A read error occurred while accessing the external data source.

Since GeoDMS 20.17.0. A compass next to the name of a unit means the unit is in a coordinate reference system: it either declares a SpatialReference of its own, or inherits one through its projection -- a gridset() over a CRS-bearing coordinate unit carries the compass as well. Hovering the item shows which CRS it is.

Unlike the badges above this one says nothing about a state; it is a property of the unit. It is a badge rather than part of the icon because being georeferenced is independent of what the unit is: both a grid domain and an fpoint coordinate unit can carry a CRS, and each keeps its own icon.

Older versions:

The color used for a tree item name indicates its status. Three statuses are distinguished:

1. Not yet calculated: an item is not yet calculated.
2. Valid: the results are calculated successfully and the integrity checks configured for the item and its suppliers are met.
3. Failed: the application failed in updating the results or the integrity checks are not met. In the first case, the results are not available; an error is raised indicating what problem occurred while updating the tree item. In the second case, the results are available and can be presented in a view; a warning color indicates the results are not valid.

The colors for these statuses can be viewed or edited with the Settings > GUI options dialog, section TreeView, Show state colors.

The application controls when and how to update tree items. If a user requests a view on a data item, the required tree items are first updated, before the results are presented in the view. If a tree item has become valid, this status is ‘stored’ until changes are made in the calculation rules. This means the second time the same view (or another view requiring the same data items) is requested, the data item is already valid and the results can be visualized immediately.

With a right mouse click, a pop-up menu can be requested for actions on the active tree item. This menu contains the following options, some options are only available for data items or for items with the status: failed. In the screenshot the item right-clicked is a polygon attribute, so the four chart options are disabled: a chart needs numeric or boolean values.

• Export primary data : exports the contents of the active data item (or the subitems of a container) with the export dialog.
• Step up to FailReason: if a data item is failed, this option activates the first failed supplier.
• Run up to Causa Prima (i.e. repeated Step up): if a data item is failed, the GeoDMS tries to find the item for which the first error occurs.
• Open in Editor: Opens the current item in the Configuration File Editor as configured in the Settings > Local machine options dialog, section Configuration File Editor.
• Update TreeItem: update the tree item, without showing the result in a view. The process is visualized with a process scheme.
• Update SubTree: update the tree item and all it's subitems, without showing the result in a view. The process is visualized with a process scheme.
• Code Analysis: Four options to find out if the item configured is used in calculating results
  • set source: set the item as source item to be analysed
  • set target: set the item as target item for the calculation process
  • add target: add the item as target item for the calculation process
  • clear target: clear the item as target item for the calculation process
• Default View: calculate the results and use the default view to present them. Since GeoDMS 20.18.0 the entry carries the icon of the view it is going to open on this item, so it shows the same icon as the Table View or the Map View entry below it.
• Table View: calculate the results and present the results in a table view
• Map View: calculate the results and present the results in a map view
• Statistics: calculate the results and present the results in a statistics window
• Histogram Chart, Scatter Chart, Line Chart, Bar Chart: calculate the results and present them as a chart. Each of the four has an icon of its own -- up to and including GeoDMS 20.17.x all four wore the Statistics icon -- and so does the window it opens; see Main menu, section View, for what each of the four draws.

The eight view entries above are the same menu entries as the View menu of the Main menu holds; they act on the tree item you right-click. Since GeoDMS 20.18.0 they are named after the view they open: Default View, Table View and Map View were named Default, Table and Map, and the four chart entries lost their leading Create.