QxRunner

QxRunner Library User Guide

This user gide describes how to use the QxRunner library.

QxRunner User Interface

Let's start with a description of the QxRunner GUI. This is what users see and what you will eventually be programming for. The screenshots are taken from the QxRunner demo program which can be used to explore all features of the GUI, this description just highlights the main elements.

The Main Window

The picture below shows the GUI in its 'standard' design with the model name shown in the title bar. Depending on how a QxRunner program is implemented the window might look slightly different. As usual interaction elements can become disabled depending on program state. A QxRunner program saves its window state at program exit and restores it at next start-up.

	Menubar and toolbars. The toolbars can be hidden. Right click on a toolbar to see the corresponding popup menu or go to View->Toolbars.
	The Runner View presents the runner items that can be selected for execution. Group item checkboxes are tri-state to show whether all, none or some of its children are selected. Checking a group item propagates the same check state to its children. Sorting in columns isn't supported.
	The Results View presents the runner item execution results. The results view can be floating, docked at any side of the main window or completely hidden. The filter buttons allow to select which result types should be visible in the view. Sorting in columns is supported when there are results.
	The statusbar shows counters for the runner items presented in the runner view and the number of different result types returned by executed runner items. During item execution the work progress is displayed. The total number of items displayed at the very left doesn't include group items.

	Pressing the start button begins item execution. The currently processed item is highlighted. To speed up item execution the highlighting can be suppressed by setting the GUI in minimal update mode with the View->Minimal Update command. In minimal update mode no results are displayed during ongoing item execution but shown at once at the end of item execution.
	Pressing the stop button tries to interrupt the ongoing item execution. Stopping the execution process is only possible in the moment between termination of a runner item and the start of the next one. If the currently executing item performs lengthy operations or is blocked the GUI shows a dialog to give the user a visual hint as well as a chance to interrupt the stopping:
	Closing the main window during item execution could lead to the following, self-explanatory message box:

Result Types

At the end of its execution a runner item returns a result code to report the execution status. All result types except success and exception should have an accompanying result message. The following list briefly describes the predefinded result types handled by the QxRunner library. Developers of a QxRunner program can limit the expected results to a subset of this list. The concrete meaning of a certain result type mainly depends on the program, the list just gives a general interpretation. The results summary in the statusbar shows a counter for all result types returned from runner items, even for result types that are not expected in a particular application.

	Success	Item completed successfully. This result type isn't displayed in the results view.
	Info	Item completed successfully and has an info.
	Warning	Item completed with a warning.
	Error	Item completed with an error.
	Fatal	Item completed with a fatal error.
	Exception	Item not completed due to an unhandled error which mostly turns out to be a programming error. This result type cannot be filtered out in the results view.

This set of predefined result types is inspired by the VMS condition handling.

Columns Selection Dialog

Initially the runner view has two columns. Column 0 contains the checkbox and the runner item name. Column 1 is used for the result. The runner view initially has as many columns as are defined for the program data. Runner view and results view show the same data thus can have the same columns displayed. The View->Columns command opens the columns selection dialog where users can define which columns should be visible in each view.

The first column in a view is always visible therefore its visibility can't be changed. If the results view is hidden its column visibilities can't be changed.

Settings Dialog

Open the settings dialog with the View->Settings command. At the moment users can only choose whether the views should have alternating row colors or not.

Tips

Clearing all Results

To clear all results, first Unselect All runner items and then click the Start button.

All runner items unselected:

After run completed:

INI File Location

Program settings are saved in INI files located in folder:

%APPDATA%\qxrunner	On Windows.
$HOME/.config/qxrunner	On Linux.

Make sure the program has write permission for the folder.

Restore Initial State of the GUI

Just delete the program INI file. This will cause the GUI to appear in the default design at next program start-up.

Writing a QxRunner Program

The Examples page in the QxRunner API documentation explains in detail how the demo program for the QxRunner library is implemented. Use the basic approach presented there for your own program. It's also worth to look at the QxCppUnit library source code to see a 'real life' implementation of a QxRunner application.

Should the program have its own application icon then provide it to the runner object like this:

QxRunner::Runner runner;
runner.setWindowIcon(QIcon("myappicon.png"));

Once the source code is ready the program can be built. As a prerequisite, of course, the QxRunner library must have been installed as described in QxRunner Installation.

Building the Program on Windows

It's assumed that you know how to build a Qt program on Windows, therefore just a few important points to be considered when using the Visual Studio 2005 IDE with CL version 14.x:

• Make sure the compiler and linker options are compatible with the options used for building the QxRunner and Qt libraries.
• Programs using the QxRunner DLL must be compiled with the QXRUNNER_DLL preprocessor definition. This isn't required when linking with the static QxRunner library.
• Set the appropriate pathnames for the compiler and linker so these tools find the include and library files of QxRunner and Qt. For example:
  
  $(QXRUNNER)\include $(QTDIR)\include $(QTDIR)\include\QtCore
$(QTDIR)\include\QtGui


• Link with the QxRunner, QtCore and QtGui libraries. For example when linking with the static debug libraries:
  
  qxrunnerd.lib qtmaind.lib QtCored4.lib QtGuid4.lib


Building the Program on Linux

It's assumed that you know how to build a Qt program on Linux. Writing a qmake project file probably is the easiest way to go. For example when linking with the static debug libraries:

TEMPLATE     = app
CONFIG      += qt warn_on debug
INCLUDEPATH += $$(QXRUNNER)/include
LIBS        += -L$$(QXRUNNER)/lib -lqxrunnerd
.
.
HEADERS = ...
SOURCES = ...

Running the Program

If the GUI starts with almost all window elements disabled as shown below then either the model's structure is invalid or no model has been set for the runner:

If the program is OK then the window should look similar to those on the Screenshots page.

---