Graphical User Interface (GUI)

The graphical user interface program groopsGui enables the convenient creation of GROOPS config files. It uses the Qt5 framework for cross-platform support.

gui_overview
Figure: Overview of the GUI (components mentioned below marked in red)

Settings and first-time setup

The GUI depends on an XSD schema file containing the complete formal (computer readable) description of a GROOPS config file. This schema file can be created with the command: 

  groops --xsd <groopsDir>/groops.xsd
At least one schema file has to be set via the menu Settings - Default Paths and Files. Setting more than one schema files enables the schema selector in the toolbar. The selected schema will be used when (re-)opening or creating a config file. This feature is useful when working with different versions of GROOPS at the same time.

It is possible to set a template file via the menu Settings - Default Paths and Files. This can be any GROOPS config file. Whenever a new config file is created via the GUI, all global elements and programs defined in the template file are automatically created in the new config file. It is highly recommended to create a template file containing at least the global element groopsDataDir of type filename. This element is used as a variable in most default file paths throughout many GROOPS programs. Thus, setting the path to the base directory containing all GROOPS data once in the template file, for example as groopsDataDir=/home/<user>/groops/data, is the most convenient way to handle default paths in GROOPS. The template file can also contain other often-used global elements, for example tmpDir or timeStart and timeEnd.

A working directory can be set via Settings - Default Paths and Files. This directory is used as the default directory in the save dialog of new config files.

The GUI offers the option to open the GROOPS documentation for a selected program. To use this feature, the GROOPS documentation must be generated (if not already present) with the command: 

  groops --doc <groopsDir>/docs/
In the menu Settings - Default Paths and Files the path to the HTML version of the documentation must be set (i.e. <groopsDir>/docs/html). Selecting any program and pressing F1 opens the documentation for this program in an external browser. Pressing F1 without having any program selected opens the main page of the GROOPS documentation.

Executing a config file from the GUI requires the setup of a run command in the menu Settings - Commands. It is recommended for this command to open a new terminal in which GROOPS is executed with the config file given as an argument. The placeholders %w and %f are replaced by the directory and file name of the selected config file, respectively. Multiple commands can be set up, with the option to choose one of them in the run dialog.

Example commands:

Basic features

Most basic features used to manipulate a config element are accessible via the context menu, for example attributing loops and conditions or setting an element global. Global elements automatically appear in the dropdown value list of config elements of the same type. Selecting a global element from the dropdown list as a value links this config element to the global element. In case the global element is removed, all linked elements' values are replaced by the value of the deleted global element.

The sidebar features three widgets:

In case the names of programs or config elements change over time, the GUI offers a rename feature to update outdated config files. The changes must be documented in the schema using GROOPS' rename feature. Affected elements will be marked with an icon and the context menu item Update name will be available to change the element to the new name defined in the schema.

Additional keyboard shortcuts