The ExperimentManager class. More...

Inherits QObject, and QScriptable.

Public Types
enum	ExperimentState { ExperimentManager_NoState = 0, ExperimentManager_Constructed = 1, ExperimentManager_Loaded = 2, ExperimentManager_PreParsed = 3, ExperimentManager_Configured = 4, ExperimentManager_Initialized = 5, ExperimentManager_IsStarting = 6, ExperimentManager_Started = 7, ExperimentManager_IsStopping = 8, ExperimentManager_Stopped = 9 }

Public Slots
void	abortExperiment ()
	Aborts the current Experiment that is running. More...

int	createExperimentTimer ()
	Use this function to create a Experiment Timer object. More...

double	elapsedExperimentTimerTime (int nIndex)
	Use this function to retrieve the current elapsed Experiment Timer time. More...

QScreen *	getActiveStimuliOutputScreen ()
	Returns a QScreen object representing the active Stimuli Output Screen. More...

static QString	getAvailableScreensInformation ()
	Returns various Screen information from all available screens. More...

QString	getCurrentDateTimeStamp (const QString &sFormat=MainAppInfo::stdDateTimeFormat())
	Use this function to retrieve the current date/time. More...

QString	getCurrentExperimentState ()
	Use this function to retrieve the current Experiment State. More...

bool	getDebugMode ()
	Get the debug mode for the experiment. More...

QString	getExperimentFileName ()
	Returns the path to the current set experiment file. More...

QString	getExperimentName ()
	Returns the current experiment name. More...

bool	getExperimentObjectBlockParameter (const int nObjectID, const QString sName, ParsedParameterDefinition &strcParDef)
	Returns a boolean value that determines if a specified named object parameter from the current experiment block could be retrieved and set. More...

cExperimentStructure *	getExperimentStructure (const bool bCreateIfUndefined=false)
	Returns the current in-memory Experiment Structure. More...

bool	insertExperimentObjectBlockParameter (const int nObjectID, const QString sName, const QString sValue, bool bIsInitializing=true, bool bIsCustom=false)
	Inserts a specified object parameter for the current experiment block. More...

bool	loadExperiment (QString strSource="", const bool bIsFile=true, const bool bSkipXMLValidation=false)
	Loads the Experiment from a file path into the memory. More...

bool	logExperimentObjectData (const int &nObjectIndex, const int &nTimerIndex, const QString &strFunction="", const QString &strTag="", const QString &strMessage="", const QString &strValue="")
	Use this function to append a experiment data log to the default BrainStim log file. More...

bool	parseCurrentExperimentStructure ()
	Forces a Parse of the current Internal Experiment Structure. More...

double	restartExperimentTimer (int nIndex)
	Use this function to retrieve the current elapsed Experiment Timer time and restart a Experiment Timer object. More...

bool	runExperiment (const bool bSkipXMLValidation=false)
	Runs the current Experiment available in memory. More...

bool	saveExperiment (QString strFile="")
	Saves the current experiment file from memory to a file. More...

void	sendToMainAppLogOutput (const QString &strText2Write)
	Sends a text string to the BrainStim Log output pane. More...

bool	setActiveStimuliOutputScreen (int nScreenNumber)
	Sets a Screen referred by it's Screen Number as the current active Stimuli Output Screen. More...

void	setDebugMode (bool mode)
	Sets the debug mode for the experiment. More...

bool	setExperimentFileName (const QString sExpFileName)
	Sets the path for the experiment file. More...

void	setExperimentName (QString sName)
	Sets the experiment name for the current experiment. More...

void	setExperimentOutputFilePostString (const QString &sPostString)
	Sets the configurable part of the automatic generated experiment Output filename. More...

bool	showTreeviewExperimentDialog (ExperimentTreeModel *expTreeModel=NULL, const QString &sExpTreeModelCanonFilePath="")
	Shows the Experiment in a Tree-view Experiment Editor dialog. More...

bool	showVisualExperimentDialog (ExperimentTreeModel *expTreeModel=NULL, const QString &sExpTreeModelCanonFilePath="")
	Shows the Experiment in a Visual Experiment Editor dialog. More...

bool	startExperimentTimer (int nIndex)
	Use this function to start a Experiment Timer object. More...

void	stopExperiment ()
	Stops the current Experiment that is running. More...

bool	validateExperiment (const bool bSkipXMLValidation=false)
	Validates the current experiment available in memory. More...

Signals
void	ExperimentStateHasChanged (int nExperimentMainState, QString timeTextStamp)
	The ExperimentStateHasChanged Signal. More...

void	WriteToLogOutput (const QString &strText2Write)
	The WriteToLogOutput Signal. More...

Public Member Functions
	ExperimentManager (QObject parent=NULL, QScriptEngine engine=NULL)
	The ExperimentManager constructor. More...

	~ExperimentManager ()
	The ExperimentManager destructor. More...

Detailed Description

The ExperimentManager class.

The Experiment Manager can be used configure, open and execute experiment (*.exml) files.

Member Enumeration Documentation

enum ExperimentManager::ExperimentState

The enum ExperimentState represents the main state of the ExperimentManager object, access in script e.g. : ExperimentManager.ExperimentState.ExperimentManager_Configured

Enumerator
ExperimentManager_NoState	this state is only internally used by the object while it is constructing, thus not yet fully available and therefore cannot be detected/used in the script environment.
ExperimentManager_Constructed	this state is used to determine whenever the object has been constructed, this state also cannot be detected/used in the script environment.
ExperimentManager_Loaded	after the Experiment file (*.exml) is successfully loaded (and validated) the ExperimentManager state changes to this state.
ExperimentManager_PreParsed	when the Experiment could be successfully pre-parsed (after loading) then the ExperimentManager state changes to this state.
ExperimentManager_Configured	after the function runExperiment() is called the ExperimentManager (validates if it has not been done before) and configures the experiment, it then changes to this state if the configuration was done.
ExperimentManager_Initialized	after the Experiment configuration the ExperimentManager tries to initialized and changes the state to this state if this step was successful.
ExperimentManager_IsStarting	after the Experiment initialization the ExperimentManager is ready to actually start the Experiment but first it changes the state to this state.
ExperimentManager_Started	after the Experiment is successfully started the ExperimentManager changes to this state.
ExperimentManager_IsStopping	before the ExperimentManager tries to stop the Experiment it first changes to this state.
ExperimentManager_Stopped	after the ExperimentManager could finalize and stop the Experiment it changes to this state.

Constructor & Destructor Documentation

ExperimentManager::ExperimentManager	(	QObject *	parent = `NULL`,
		QScriptEngine *	engine = `NULL`
	)

The ExperimentManager constructor.

You do not need to specify the parent object. The BrainStim script engine automatically retrieves the parent role

ExperimentManager::~ExperimentManager ( )

The ExperimentManager destructor.

You do not need call the destructor. The BrainStim script engine automatically performs the garbage collection after you set the object to NULL and the script ends

Member Function Documentation

void ExperimentManager::abortExperiment ( )

slot

Aborts the current Experiment that is running.

Tries to abort the current Experiment that is running, see ExperimentManager.runExperiment().

int ExperimentManager::createExperimentTimer ( )

slot

Use this function to create a Experiment Timer object.

This function creates a Experiment Timer object and returns the Timer identifier of the newly constructed Experiment Timer object.

Returns: a integer value determining whether this function executed successfully, if it failed it returns -1.

double ExperimentManager::elapsedExperimentTimerTime ( int nIndex )

slot

Use this function to retrieve the current elapsed Experiment Timer time.

This function tries to retrieve the current elapsed Experiment Timer time

Parameters

nIndex a integer value that holds the Timer identifier.

Returns: a double value boolean value holding the elapsed time or -1 in case the function executed unsuccessfully.

void ExperimentManager::ExperimentStateHasChanged	(	int	nExperimentMainState,
		QString	timeTextStamp
	)

signal

The ExperimentStateHasChanged Signal.

You can use this Signal to keep track of the internal Experiment state changes. Parameter nExperimentMainState is type of the enum ExperimentState.

QScreen * ExperimentManager::getActiveStimuliOutputScreen ( )

slot

Returns a QScreen object representing the active Stimuli Output Screen.

This function returns a pointer to an QScreen object representing the active configured Stimuli Output Screen.

Returns: a pointer to an QScreen object.

QString ExperimentManager::getAvailableScreensInformation ( )

staticslot

Returns various Screen information from all available screens.

This function returns various Screen information from all available screens.

Returns: a string containing the various Screen information from all the available screens.

QString ExperimentManager::getCurrentDateTimeStamp ( const QString & sFormat = MainAppInfo::stdDateTimeFormat() )

slot

Use this function to retrieve the current date/time.

This function returns the current date/time string that can be custom formatted.

Parameters

sFormat a string value containing the custom Date/Time format, if left empty the value "yyyyMMddHHmmsszzz" is used.

Returns: a string value containing the current date/time string.

QString ExperimentManager::getCurrentExperimentState ( )

slot

Use this function to retrieve the current Experiment State.

Returns: a string containing the current Experiment State.

bool ExperimentManager::getDebugMode ( )

slot

Get the debug mode for the experiment.

Returns the configured debug mode for the current experiment.

Returns: a boolean value determining whether the experiments debug mode is enabled.

QString ExperimentManager::getExperimentFileName ( )

slot

Returns the path to the current set experiment file.

This function returns the path to the current set experiment file, see also ExperimentManager.setExperimentFileName()

Returns: a string containing the path to the current set experiment file.

QString ExperimentManager::getExperimentName ( )

slot

Returns the current experiment name.

This function returns the configured experiment name for the current experiment.

Returns: a string containing the configured experiment name.

bool ExperimentManager::getExperimentObjectBlockParameter	(	const int	nObjectID,
		const QString	sName,
		ParsedParameterDefinition &	strcParDef
	)

slot

Returns a boolean value that determines if a specified named object parameter from the current experiment block could be retrieved and set.

Parameters

nObjectID	a integer value that holds the object ID.
sName	a string value that contains the parameter name.
strcParDef	a ParsedParameterDefinition structure that hold the requested named object parameter after a successful function call.

Returns: a boolean value determining whether this function executed successfully.

cExperimentStructure * ExperimentManager::getExperimentStructure ( const bool bCreateIfUndefined = false )

slot

Returns the current in-memory Experiment Structure.

This function returns a pointer to the current in-memory Experiment Structure.

Parameters

bCreateIfUndefined a boolean value (default = false) that can be used to force a new cExperimentStructure structure to be created when the current cExperimentStructure structure is undefined.

Returns: a pointer to a cExperimentStructure structure, if the function fails it returns NULL.

bool ExperimentManager::insertExperimentObjectBlockParameter	(	const int	nObjectID,
		const QString	sName,
		const QString	sValue,
		bool	bIsInitializing = `true`,
		bool	bIsCustom = `false`
	)

slot

Inserts a specified object parameter for the current experiment block.

Inserts a specified object parameter with an object ID, a parameter name and a parameter value in the current experiment block definitions.

Parameters

nObjectID	a integer value that holds the object ID.
sName	a string value that contains the parameter name.
sValue	a string value that contains the parameter value.
bIsInitializing	a boolean value, if true then then the new parameter is marked as Initializing, see strcParsedParameterDefinition.bIsInitialized This property marks the parameter as unused which can be helpful for further setting the default value.
bIsCustom	a boolean value that determines whether the parameter should be treated as a custom parameter (default = false).

Returns: a boolean value determining whether the function executed successfully.

bool ExperimentManager::loadExperiment	(	QString	strSource = `""`,
		const bool	bIsFile = `true`,
		const bool	bSkipXMLValidation = `false`
	)

slot

Loads the Experiment from a file path into the memory.

The Experiment file (*.EXML) is loaded into memory.

Parameters

strSource	a string containing the file path to the experiment file (*.EXML), if this value is "" then the last configured experiment file path is automatically loaded in memory, see ExperimentManager.setExperimentFileName(). A second configurable option (see
bIsFile)	is that this variabele can also hold the script content to load.
bIsFile	a boolean determining whether the
strSource	parameter should be threated as a string containing a path to a experiment file. If false then the parameter is threated threated as a string containing the script content itself.
bSkipXMLValidation	a boolean determining whether the content should be fully validated first (default = false), this can causes the loading process to take more time when enabled.

Returns: a boolean value determining whether the function executed successfully.

bool ExperimentManager::logExperimentObjectData	(	const int &	nObjectIndex,
		const int &	nTimerIndex,
		const QString &	strFunction = `""`,
		const QString &	strTag = `""`,
		const QString &	strMessage = `""`,
		const QString &	strValue = `""`
	)

slot

Use this function to append a experiment data log to the default BrainStim log file.

This function appends a experiment data log entry to the default BrainStim log file by forwarding this information to the internal Experiment Data Logger.

Parameters

nObjectIndex	a integer value that holds the object ID to which the line to log correlates.
nTimerIndex	a integer value that holds the Timer ID to which the line to log correlates.
strFunction	a string value that defines the Function string of text of the experiment data log.
strTag	a string value that defines the Tag string of text of the experiment data log.
strMessage	a string value that defines the Message string of text of the experiment data log.
strValue	a string value that defines the Value string of text of the experiment data log.

Returns: a boolean value determining whether this function executed successfully.

bool ExperimentManager::parseCurrentExperimentStructure ( )

slot

Forces a Parse of the current Internal Experiment Structure.

This function Forces the parsing of the current Internal Experiment Structure.

Returns: a boolean value determining whether this function executed successfully.

double ExperimentManager::restartExperimentTimer ( int nIndex )

slot

Use this function to retrieve the current elapsed Experiment Timer time and restart a Experiment Timer object.

This function tries to retrieve the current elapsed Experiment Timer time and restart a Experiment Timer object.

Parameters

nIndex a integer value that holds the Timer identifier.

Returns: a double value boolean value holding the elapsed time or -1 in case the function executed unsuccessfully.

bool ExperimentManager::runExperiment ( const bool bSkipXMLValidation = false )

slot

Runs the current Experiment available in memory.

The current available experiment in memory is started if/after it has been successfully loaded and validated.

Parameters

bSkipXMLValidation a boolean determining whether the content should be fully validated (default = false), this process takes more time when enabled.

Returns: a boolean value determining whether the function executed successfully.

bool ExperimentManager::saveExperiment ( QString strFile = "" )

slot

Saves the current experiment file from memory to a file.

The current experiment file in memory is saved to a file.

Parameters

strFile a string containing the path to the to be saved experiment file (*.EXML). If this parameter is empty ("") then the experiment is automatically saved to the last configured experiment file path, see ExperimentManager.setExperimentFileName().

Returns: a boolean value determining whether the function executed successfully.

void ExperimentManager::sendToMainAppLogOutput ( const QString & strText2Write )

slot

Sends a text string to the BrainStim Log output pane.

This function sends a text string to the BrainStim Log output pane.

Parameters

strText2Write a string containing the text to send.

bool ExperimentManager::setActiveStimuliOutputScreen ( int nScreenNumber )

slot

Sets a Screen referred by it's Screen Number as the current active Stimuli Output Screen.

This function sets a Screen referred by it's Screen Number as the current active Stimuli Output Screen.

Parameters

nScreenNumber a integer value representing the Screen Number that should be set as the current active Stimuli Output Screen.

Returns: a boolean value determining whether this function executed successfully.

void ExperimentManager::setDebugMode ( bool mode )

slot

Sets the debug mode for the experiment.

This function sets the debug mode for the experiment.

Parameters

mode	a boolean value holding the debug mode for the current experiment.

bool ExperimentManager::setExperimentFileName ( const QString sExpFileName )

slot

Sets the path for the experiment file.

This function sets the internal path to the experiment file.

Parameters

sExpFileName a string holding the path to the experiment file (*.EXML), see also ExperimentManager.getExperimentFileName().

Returns: a boolean value determining whether the function executed successfully.

void ExperimentManager::setExperimentName ( QString sName )

slot

Sets the experiment name for the current experiment.

This function sets the experiment name for the current experiment.

Parameters

sName a string containing the new experiment name.

void ExperimentManager::setExperimentOutputFilePostString ( const QString & sPostString )

slot

Sets the configurable part of the automatic generated experiment Output filename.

This function sets the configurable part of the automatic generated experiment Output filename. This string is then integrated in the output filename (format = YearMonthDayHourMinuteSecond_<sPostString>.txt ).

Parameters

sPostString a string containing the configurable post file name string.

bool ExperimentManager::showTreeviewExperimentDialog	(	ExperimentTreeModel *	expTreeModel = `NULL`,
		const QString &	sExpTreeModelCanonFilePath = `""`
	)

slot

Shows the Experiment in a Tree-view Experiment Editor dialog.

This function shows the Experiment in a Tree-view Experiment Editor dialog, if the provided ExperimentTreeModel is NULL than the current in-memory Experiment is parsed by the editor.

Parameters

expTreeModel	a ExperimentTreeModel to be edited by the Tree-view Experiment Editor dialog, make it NULL to automatically use the current in-memory Experiment.
sExpTreeModelCanonFilePath	a string holding a canonical path referring to a file that should be used by default for saving changes to.

Returns: a boolean value determining whether this function executed successfully.

bool ExperimentManager::showVisualExperimentDialog	(	ExperimentTreeModel *	expTreeModel = `NULL`,
		const QString &	sExpTreeModelCanonFilePath = `""`
	)

slot

Shows the Experiment in a Visual Experiment Editor dialog.

This function shows the Experiment in a Visual Experiment Editor dialog, if the provided ExperimentTreeModel is NULL than the current in-memory Experiment is parsed by the editor.

Parameters

expTreeModel	a ExperimentTreeModel to be edited by the Visual Experiment Editor dialog, make it NULL to automatically use the current in-memory Experiment.
sExpTreeModelCanonFilePath	a string holding a canonical path referring to a file that should be used by default for saving changes to.

Returns: a boolean value determining whether this function executed successfully.

bool ExperimentManager::startExperimentTimer ( int nIndex )

slot

Use this function to start a Experiment Timer object.

This function tries to starts a experiment timer object specified with a Timer identifier.

Parameters

nIndex a integer value that holds the Timer identifier.

Returns: a boolean value determining whether this function executed successfully.

void ExperimentManager::stopExperiment ( )

slot

Stops the current Experiment that is running.

Tries to stop the current Experiment that is running, see ExperimentManager.runExperiment().

bool ExperimentManager::validateExperiment ( const bool bSkipXMLValidation = false )

slot

Validates the current experiment available in memory.

The current experiment available in memory is validated.

Parameters

bSkipXMLValidation a boolean determining whether the content should be fully validated (default = false), this process takes more time when enabled.

Returns: a boolean value determining whether the current experiment could be validated successfully.

void ExperimentManager::WriteToLogOutput ( const QString & strText2Write )

signal

The WriteToLogOutput Signal.

You can use this signal to let the ExperimentManager write something to the BrainStim log window.

Public Types

Public Slots

Signals

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation