Runner Model and Runner Item

RunnerModel and RunnerItem are the two classes of most interest for those wanting to write their own QxRunner based program. By subclassing these classes and linking with the QxRunner library one has the program ready.

These sections give some insight into these classes. Please also read the RunnerModel and RunnerItem description .

The Runner Model

The RunnerModel class implements a tree model with the data contained in RunnerItem objects. At initialization time the model gets populated with RunnerItem objects that are linked together in a pointer-based tree structure or in a less complex non-hierarchical list. Thus RunnerModel isn't limited to represent tree strucutures only. A simple non-hierarchical list can be seen as a tree structure with parent items only that have no child items.

Generally, a RunnerItem has a parent item, and can have a number of child items. Each RunnerItem object contains information about its place in the tree structure, it can return its parent item and its row number. The use of a pointer-based tree structure allows to store the runner item object pointer in the QModelIndex which refers to the runner item. Use QModelIndex's internalPointer() method to get the pointer.

There must be a root item in the tree structure of the model which is the top level parent of all runner items. The root item has no parent item. It is never referenced outside the model but defines the number of columns and the column headers for the views attached to the model. Although the root item is automatically assigned a row number of 0, this information is never used by the model.

The model can run code in the runner items and observe their execution. Signals are fired to inform the environment about ongoing execution status. The current model implementation only executes code in items which have no children, but this could change in the future. Therefore the code in a runner item should check whether it is a parent or not. Only selected runner items get executed. Execution is strictly sequential, i.e. the first runner item found for execution in the tree structure is run, or if it has children these are run, then the next selected sibling item is run and so on.

Runner items get executed asynchronously in a separate thread allocated by RunnerModelThread. Stopping item execution is only possible in the moment between termination of a runner item and the start of the next one. The thread isn't stopped the 'hard way' by terminating it which is dangerous and discouraged in the Qt documentation. Instead a flag is set which indicates that the thread must stop. This flag is checked regularly in the method that drives item execution.

Data updates with RunnerModel::setData() are not possible during item execution. Although the code in runner items can do anything thinkable it is recommended to keep the code to a minimum and to forego lengthy operations because a running item can't be interrupted.

Due to the parallelism induced by the thread the item execution must be synchronized with clients that consume item execution related information. The GUI for example displays state information about item execution. If the items are executing faster in the thread than the GUI is able to upate its widgets in its own thread the information shown in the GUI won't be reasonable. Therefore the model waits after each executed item until the signals it emits are completely processed by the signal receivers.

The model can be set to minimal update mode. In this mode only a reduced amount of item data and execution state information is returned. It's up to clients to decide when this is useful. QxRunner uses minimal update mode to speed up item execution because not all item data must be updated in views for an executing runner item.

Data changes from the outside of the model with RunnerModel::setData() are allowed for the selected flag in column 0 only. Of course there occur data changes all the time during item execution but this happens behind the scenes.

The model name uniquely identifies a model which has its unique structure. It is used to identify the settings of a program using the model. Therefore it's not recommended to use a version number or other variable information as part of the model name. Furthermore it is essential that the model name can be part of a valid filename, i.e. no special characters must be used in the name.

Note:

The RunnerModel isn't designed to add additional RunnerItem instances to the model after it is constructed and set up.

The Results Model

The ResultsModel is tightly coupled to the RunnerModel, more precisely, the RunnerModel class creates the ResultsModel to hold the results of its runner items and defines the model structure. The ResultsModel class has mainly been introduced because the RunnerModel class isn't suitable for displaying chronological data as a simple non-hierarchical list instead of in a tree structure.

The Runner Item

All runner items have the same number of columns. The first two columns have a fixed meaning which should not be overriden:

• Column 0 has the name of the item. This column also carries the selected flag which indicates whether a runner item is selected for execution or not. In views this flag is presented as a checkbox.
• Column 1 is the textual representation of the result after a runner item has been executed. In general this result text is set by QxRunner but can also be provided otherwise. In the latter case the semantical meaning should be that of describing a result type.

The other columns, if any, can be used freely.

Note:

It is important that all RunnerItem objects in RunnerModel have the same number of columns otherwise some view manipulations could throw assertions as learned by experience. Therefore the RunnerItem constructor takes care of the correct number of columns for an item.

See also:

Runner Item Index