Gui scripting - ObjectVision/GeoDMS GitHub Wiki

The GeoDMS GUI (GeoDmsGuiQt.exe) can replay a script of GUI actions, primarily used for automated regression and release testing. The implementation lives in qtgui/exe/src/TestScript.cpp (parser + dispatch) and the matching command codes in qtgui/exe/src/TestScript.h.

invocation

Pass a script file via the /T command-line switch (no space between /T and the path):

GeoDmsGuiQt.exe /TC:\path\to\my.script C:\path\to\config.dms

End every script with SEND 1 3 16 0 0. The log file that /L names is written when the process exits cleanly: kill the GUI instead and the log is left empty, which is a poor way to find out what the run did.

The script runs on the main (GUI) thread after the main window is shown. Each line is executed sequentially; a script line is dispatched as a single posted operation, so commands take effect in the same event-loop turn.

file format

Scripts are plain text, parsed one line at a time:

element rule
line terminator \n (LF). Carriage returns and other whitespace are tolerated by the tokenizer.
comment // starts a comment; the rest of the line is ignored. There is no block-comment syntax.
empty line skipped.
token separator any whitespace (isspace) between tokens.
quoted token "..." keeps a single token together up to the next "; the surrounding quotes are stripped. Use this for paths or names that contain spaces.
max tokens per line 20 (MAX_ARG_COUNT). Excess tokens on a line are silently ignored.

Multiple commands may appear on the same line — the dispatcher iterates over the tokens and executes each command in turn. The exception is WAIT, which returns immediately and pauses before the next line is read.

commands

Token matching is case-sensitive. Where two names appear, both are accepted.

command arguments effect
WAIT <milliseconds> Pause script execution for the given number of milliseconds before processing the next line. (Note: the source error message labels the argument "seconds", but it is actually consumed as milliseconds.)
DefaultView — Open the default view for the currently active tree item (same as the toolbar default-view action).
GOTO / ActivateItem <item-path> Set the active tree item to the given DMS path (e.g. /SomeContainer/SomeItem). Quote paths that contain spaces.
EXPAND / Expand — Expand the currently active tree node by one level.
Collapse — Collapse the currently active tree node.
ExpandAll — Expand the entire tree.
ExpandRecursive — Recursively expand from the current item downward.
DP / ShowDetailPage <page-number> Switch the detail-pages panel to a specific page (see table below).
SAVE_DP / SaveDetailPage <file-path> Save the current detail page contents to a file.
CascadeSubWindows — Cascade the MDI sub-windows.
TileSubWindows — Tile the MDI sub-windows.
SaveValueInfo <file-path> Save the current ValueInfo content to a file.
ExportPrimaryData — Run Export Primary Data on the currently active tree item with the settings the export dialog proposes itself, and press Export. See below.
BringToFront — Raise the main window in the Z-order and give it focus. Handled in the script thread, without a message.
EditConfigSource / EditConfigRootSource — Fire the "edit config source" action for the current item, respectively for the configuration root: the stored DmsEditor command is expanded and launched detached, and the resulting command line is written to the trace log under the commands category, where a headless test can assert on it.
SEND <code> <count> [<dword>...] Low-level escape hatch: post a WM_COPYDATA message with command code <code> and <count> 32-bit unsigned integers as payload. Used for actions not yet wrapped by a named keyword.

Unrecognised tokens are reported on stderr (Unrecognized keyword: <token>) and skipped; the script continues with the next token.

ExportPrimaryData

Since GeoDMS 20.19.0. The verb is the scripted equivalent of right-clicking a tree item, choosing Export Primary Data and pressing Export without touching the dialog: it takes no arguments, and driver, folder and file name are the ones the dialog fills in for the active item. For a mappable item that is the native ESRI Shapefile writer, into %localDataProjDir%/<parent item path>/<item name>.shp; for an item that is not mappable it is CSV. The export writes one line to the event log naming the item, the resulting file and the driver, so a script that redirects the log with /L can assert on where the export went:

Export /Output_PerProvincie to C:/LocalData/scratch/Output_PerProvincie.shp with driver ESRI Shapefile, native

Two things to know when scripting it:

  • Follow it with a WAIT. The verb queues the dialog and the export on the event loop rather than running them inside the message handler, so the script has to give the GUI its turn. A few seconds is enough for a small table; an export that has to calculate first needs more.
  • Open a view on the item first (DefaultView plus a WAIT) when the item is a unit defined as an alias of another unit that carries a calculated attribute. Opening the export dialog on such an item cold parks the GUI in the view-style query the dialog does while filling in its driver list. See #1226.
  • An export that fails leaves a modal box saying so, and a modal box swallows the WM_CLOSE that ends the script, so the process stays alive and the run looks like a hang. Dismiss the box with SEND 2 3 256 13 0 (a Return to the focused window) before closing, and the script ends normally with the failure in the log.

detail-page numbers

Used as the argument to ShowDetailPage / DP. Values come from the ActiveDetailPage enum in qtgui/exe/src/DmsDetailPages.h:

value page
0 GENERAL
1 EXPLORE
2 PROPERTIES
3 CONFIGURATION
4 SOURCEDESCR
5 METADATA
6 STATISTICS
7 VALUE_INFO
8 NONE

SEND command codes

The SEND keyword takes a numeric command code matching the CommandCode enum (qtgui/exe/src/TestScript.h). The dedicated keywords listed above are preferred; codes are documented for completeness.

code name notes
0 SendApp Send a Windows message without an explicit HWND. Payload: {message, wParam, lParam}.
1 SendMain Send to the main window. Payload: {message, wParam, lParam}.
2 SendFocus Send to the currently focused window. Payload: {message, wParam, lParam}.
3 SendActiveDmsControl Send to the active DMS view-area HWND. Payload: {message, wParam, lParam}.
4 WmCopyActiveDmsControl Send a WM_COPYDATA to the active DMS view. Payload: {cmd, data...}.
5 DefaultView Equivalent to the DefaultView keyword.
6 ActivateItem Equivalent to ActivateItem.
7 miExportViewPorts Export viewports menu action (currently a stub on Qt).
8 Expand Payload {1} expand, {0} collapse.
9 ShowDetailPage Payload {pageNumber}.
10 SaveDetailPage Payload: zero-terminated path.
11 miDatagridView Datagrid-view menu action (stub).
12 miHistogramView Histogram-view menu action (stub).
13 CascadeSubWindows
14 TileSubWindows
15 ExpandAll
16 ExpandRecursive
17 SaveValueInfo Payload: zero-terminated path.
18 ExportPrimaryData No payload. Equivalent to the ExportPrimaryData keyword.

linux

On non-Windows builds, the same command vocabulary works, but commands are invoked by direct method calls on the main window rather than through WM_COPYDATA. Most SEND codes are not implemented on Linux; only WM_CLOSE (via SendMain with message 16), WM_KEYDOWN (256), WM_CHAR (258), and WM_COMMAND (273) are dispatched, plus WmCopyActiveDmsControl data forwarded to DataView::OnCopyData.

example

// open a configuration first via the command line; the script drives the GUI from there.
ActivateItem  /SomeContainer/SomeItem
ExpandRecursive
WAIT          250
ShowDetailPage 5                      // METADATA
SaveDetailPage "C:\TestOut\meta.html"
DefaultView
WAIT          1000
SaveValueInfo "C:\TestOut\valueinfo.html"
TileSubWindows
ExportPrimaryData                     // writes the item out, see the log line
WAIT          3000

requested / not yet implemented

Items previously listed as desired GUI-scripting capabilities, not yet wired up:

  • Goto cell in table
  • Activate ValueInfo (for active cell in table)
  • Select range of cells
  • Copy active range to clipboard

see also

  • Release Testing System — uses GUI scripts in t1630, t1640, t1642 regression tests.
  • qtgui/exe/src/TestScript.cpp / TestScript.h — authoritative implementation.

GeoDMS ©Object Vision BV. Source code distributed under GNU GPL-3. Documentation distributed under CC BY-SA 4.0.

⚠️ **GitHub.com Fallback** ⚠️