Sample for a custom integration with a QML UI

This sample integration demonstrates the QML UI module functionality for custom integrations.

QML (Qt Modeling Language) is a user interface markup language. It is a declarative language (similar to CSS and JSON) for designing user interface–centric applications. Inline JavaScript code handles imperative aspects. […] A QML document describes a hierarchical object tree. QML modules shipped with Qt include primitive graphical building blocks (e.g., Rectangle, Image), modeling components (e.g., FolderListModel, XmlListModel), behavioral components (e.g., TapHandler, DragHandler, State, Transition, Animation), and more complex controls (e.g., Button, Slider, Drawer, Menu). These elements can be combined to build components ranging in complexity from simple buttons and sliders, to complete internet-enabled programs.

Reference: Wikipedia

Using QML for creating custom UIs allows to:

creating custom UIs with the exact same look and feel as native optiSLang application UI
custom UI be directly embedded into optiSLang application UI
use inline Java scripting for data mining and interaction

Providing QML UI for custom integrations

In order to provide a QML UI for custom integrations it is neccessary to create a …_ci.qml file and place it next to …_ci.py file. No other actions need to be done. optiSLang automatically loads the QML and embeds the UI into custom integration dialog widget.

Get and set custom integration settings from within the QML UI

optiSLang provides a context object to the QML scope. It is called "backend" and resides in the QML root scope.

Backend object synopsis

				
	class QMLBackEnd : public QObject
	{
		const QString & settings() const;
		void setSettings(const QString &_settings);
		void requestCommitSettings();

		void requestReReadReferenceLocations();
		
		QString executeCustom ( const QString & _execute_arg );
		void executeCustom ( const QString & _execute_arg, const QJSValue & _execute_callback );
		
		void emitInfoLogMessage ( const QString & _message );
		void emitWarningLogMessage ( const QString & _message );
		void emitErrorLogMessage ( const QString & _message );

	signals:
		void settingsChanged();
		void commitSettingsRequested();
	};

It can be used to access the custom integration settings:

Settings can be read from and written to backend.settings property
Settings value is a string containing the Json representation of the current custom settings type (dynardo::design_point_type)
Javascript functions JSON.parse and JSON.stringify can be used for conversion
The signals backend.onSettingsChanged and backend.onCommitSettingsRequested can be used to react to external settings changes (from optiSLang scope, i.e. when settings UI is shown the first time) and when the settings ar requested to be commited

The backend.onSettingsChanged and backend.onCommitSettingsRequested signals can for example be used in a QML "Connections" declaration:

				
	Connections {
	    target: backend // sender
	    onSettingsChanged: {
	        var settings_json = JSON.parse(backend.settings);
	        // update controls
	    }
	    onCommitSettingsRequested: {
	        var settings_json = JSON.parse(backend.settings);
	        // update settings_json from controls
	        backend.settings = JSON.stringify(settings_json);
	    }
	}

Trigger reference location re-load

Sometimes it can be neccessary, to trigger a reference location re-load from within the QML scope. this can be done by calling backend.requestReReadReferenceLocations().

Calling custom python functionality

Sometimes it can be neccessary, to execute custom Python functionality from within the QML scope. This can be done by the following procedure:

Add "def ExecuteCustom(args)" function to …_ci.py module
From QML call either:
- (1) QString executeCustom ( const QString & _execute_arg )
- (2) void executeCustom ( const QString & _execute_arg, const QJSValue & _execute_callback )
(1) Blocks main thread and returns result after execution
(2) Calls functionality in separate thread. Result is available via _execute_callback after execution finalizes
_execute_arg is supposed to be an Json arbitrary Json value passed to the python functionality; Result is also an arbitrary Json value returned by the python functionality

Example python code:

				
	def ExecuteCustom(args):
		""" 
		Args:
			args[0]: Path to reference file 
			args[1]: settings
			args[2]: string; Json formated execute args
		Returns:
			string; Json formated execute results
		"""    
		ret = {'success': True, 'args': args[2]}
	    return json.dumps (ret)

Example QML code:

				
	Button {
		id: button1
		text: "Execute custom functionality in a separate thread"
		onClicked: {
			var args = { string_arg: "foobar", bool_arg: false };
	        backend.executeCustom ( JSON.stringify(args), function(result) 
			{
	            console.log(result);
	        })
	    }
	}

Emitting log messages

Use "backend.emitInfoLogMessage(message)" to emit an info message
Use "backend.emitWarningLogMessage(message)" to emit a warning message
Use "backend.emitErrorLogMessage(message)" to emit an error message

Developer mode

Custom integrartions can be set to developer mode. This can be done by setting the "EnableDeveloperMode" attribute in the .._ci.cfg file to "true". When the developer mode is activated, the QML UI can be reloaded during optiSLang application runtime using the settings tab corner button.