WidgetManager Class Reference

Singleton for managing widgets attached to workspace data. More...

#include <Workspace/Widgets/widgetmanager.h>

Inherits QObject.

Signals
void	displayOpened (QWidget *widget, const QString &uiFileName, CSIRO::DataExecution::Operation *relativeTo)
void	filterByInput (const CSIRO::DataExecution::InputScalar &input)
void	filterByOutput (const CSIRO::DataExecution::Output &output)
void	widgetWindowAdded (CSIRO::Widgets::WidgetWindow *w)
void	widgetWindowRemoved (CSIRO::Widgets::WidgetWindow *w)

Public Member Functions
bool	addFactory (const WidgetFactory &factory)
void	addWidgetWindow (WidgetWindow &w)
void	clearWidgetWindows ()
bool	connectWidget (QWidget &widget, DataExecution::IOBase &iobase, WidgetState state=WidgetState::Unmodified) const
QWidget *	createUnconnectedWidget (const DataExecution::DataFactory &dataFactory, QWidget *parent=nullptr) const
QWidget *	createWidget (const NamePath &namePath, QWidget *parent=nullptr, bool readOnly=false) const
QWidget *	createWidget (const QString &pathToUiFile, QStringList &errors, DataExecution::Operation *operation=nullptr, QWidget *parent=nullptr) const
void	filterOperationByInput (const DataExecution::InputScalar &input)
void	filterOperationByOutput (const DataExecution::Output &output)
QString	getCustomUiFileName (const DataExecution::IOBase &iobase) const
QString	getCustomUiFileName (const DataExecution::Operation &op) const
WidgetWindow *	getHighlightedWidget () const
QString	getHighlightedWidgetTitle () const
unsigned	getNumWidgetWindows () const
QString	getPreferredWidgetName (WidgetWindow &w)
std::vector< const WidgetFactory * >	getWidgetFactories (const DataExecution::DataFactory &dataFactory) const
WidgetCreators	getWidgetFactories (const NamePath &namePath) const
const WidgetFactory *	getWidgetFactory (const DataExecution::DataFactory &dataFactory) const
WidgetWindow *	getWidgetWindow (unsigned index)
void	insertPreferredWidget (WidgetWindow &w, const QString &widgetName)
QWidget *	openDisplay (const QString &uiFileName, DataExecution::Operation &relativeTo)
void	removeWidgetWindow (WidgetWindow &w)
void	setHighlightedWidget (WidgetWindow *w)
void	setHighlightedWidgetTitle (const QString &title)

Static Public Member Functions
static WidgetManager &	getInstance ()

Detailed Description

The WidgetManager provides a way to create new widgets and associate them with operation inputs and outputs. Plugins which provide their own custom widget implementations can make the workspace aware of those widgets by adding a WidgetFactory using addFactory(). Clients can create a widget for a given input/output using createWidget(). These are the two most commonly used functions of the widget manager.

Member Function Documentation

addFactory()

bool addFactory

(

const WidgetFactory &

factory

)

addWidgetWindow()

void addWidgetWindow

(

WidgetWindow &

w

)

clearWidgetWindows()

void clearWidgetWindows

(

)

Immediately deletes all currently open widget windows.

connectWidget()

bool connectWidget	(	QWidget &	widget,
		DataExecution::IOBase &	iobase,
		WidgetState	state = WidgetState::Unmodified
	)		const

createUnconnectedWidget()

QWidget * createUnconnectedWidget	(	const DataExecution::DataFactory &	dataFactory,
		QWidget *	parent = nullptr
	)		const

Parameters

dataFactory	The factory of the data object associated with this widget.
parent	The parent of the newly created widget.

Returns

A new widget that is associated with the data factory dataFactory. This widget is not connected to any IOBase and requires no namepath. There will be no widget connector, the user will call updateWidget() and updateData() manually.

createWidget() [1/2]

QWidget * createWidget	(	const NamePath &	namePath,
		QWidget *	parent = nullptr,
		bool	readOnly = false
	)		const

Parameters

namePath	The input or output for which a widget is to be created. If the input/output is an object group, then the namePath may refer to a particular child within that group.
parent	The parent of the newly created widget. Note that up to at least version 4.6.1, Qt has a bug relating to QGLWidget. If a QGLWidget is not created with a parent, it will run into problems with GL contexts on some platforms. Therefore, you are encouraged to provide a non-null parent to createWidget().
readOnly	Toggles read only mode for the widget as specified by the widget connector.

Widget creation is a fairly involved process. The type of widget created and the way it is configured can be customized for each input or output of any given operation. In addition, whenever the user creates a particular type of widget on an input or output, that choice is recorded and will be used as the preferred widget type until the user explicitly asks for a different type of widget on that input/output.

There are two ways widgets can be created. The first is to provide a custom display using an interface file. Customization is achieved by putting an appropriately named .ui file at a specific location where the workspace will find it. In the absence of such a customized .ui file, the workspace falls back to the second way of creating widgets, namely by looking at which widget factories support the data type associated with namePath. If no preferred widget is set, the first factory found will be the one selected. In most cases, a custom .ui file is not needed and the fallback widget factory mechanism is sufficient.

The location for .ui files is dependent on the name of the operation and the input/output it is meant for. The .ui file must have exactly the same name as the input/output with .ui appended. The file must be in a directory of the form:

    OperationName/input/My input name.ui
    OperationName/output/My output name.ui

where OperationName must match the string returned from the operation's factory's OperationFactory::getType() function. Be sure to put your .ui file in the appropriate input or output subdirectory.

The OperationName directory should be in one of the locations the workspace will search when creating widgets. The workspace defines some standard locations based on the directory containing the binary used to start up the application. Assuming the binary lives in the directory SomePath/bin, the standard search path will be SomePath/widgets. Plugins can add their own additional search paths in a number of forms. They can be an absolute path (only advisable for local usage where a plugin will never be packaged or moved), a relative path (not generally advisable) or using the widgets: search path as a prefix. See WorkspacePlugin::getCustomWidgetPaths() for an example.

If namePath refers to a child within an object group for the input/output, then the .ui file functionality described above is skipped, since this only makes sense when creating a widget for an input/output as a whole. If the namePath refers to a child within an object group, this implies that only part of the input/output needs to be represented by the widget to be created.

Returns

A new widget which has already been connected to iobase, or a null pointer if no widget could be created and connected. Note that failure to connect a widget will result in that widget being discarded. The returned widget (or a child within it) will always have been successfully connected to the input/output associated with namePath.

createWidget() [2/2]

QWidget * createWidget	(	const QString &	pathToUiFile,
		QStringList &	errors,
		DataExecution::Operation *	operation = nullptr,
		QWidget *	parent = nullptr
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

pathToUiFile	The path to a .ui user interface file. This can be a path on the local file system or more commonly a resource path such as appdata:/myapp/foobar.ui.
errors	Upon exit, this will contain any errors that were generated as part of the process. This can be non-empty even if the return value is not null.
operation	If this is not a null pointer, it is assumed to be an operation that the user interface should be connected to. If the operation happens to be a Workspace, then the user interface can connect to anything within that workspace (or indeed above it).
parent	The parent of the newly created widget. Note that up to at least version 4.6.1, Qt has a bug relating to QGLWidget. If a QGLWidget is not created with a parent, it will run into problems with GL contexts on some platforms. Therefore, you are encouraged to provide a non-null parent to createWidget().

The widget manager will attempt to establish all connections defined within the user interface file. Any errors found in this part of the process will be reported in errors, but the user interface will still be returned. This allows a user interface to tolerate missing data, albeit with some parts of the interface having no effect.

Returns

A QWidget containing the user interface defined by pathToUiFile or a null pointer if a user interface could not be constructed.

displayOpened

void displayOpened ( QWidget *  widget, const QString &  uiFileName, CSIRO::DataExecution::Operation *  relativeTo  )

signal

filterByInput

void filterByInput ( const CSIRO::DataExecution::InputScalar &  input )

signal

filterByOutput

void filterByOutput ( const CSIRO::DataExecution::Output &  output )

signal

filterOperationByInput()

void filterOperationByInput

(

const DataExecution::InputScalar &

input

)

To link between InputScalarActionsImpl and OperationCatalogue which is owned by GuiMainWindow

Parameters

input

Data type of InputScalar for operation filtering

filterOperationByOutput()

void filterOperationByOutput

(

const DataExecution::Output &

output

)

To link between OutputActionsImpl and OperationCatalogue which is owned by GuiMainWindow

Parameters

output

data type of Output for operation filtering

getCustomUiFileName() [1/2]

QString getCustomUiFileName

(

const DataExecution::IOBase &

iobase

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getCustomUiFileName() [2/2]

QString getCustomUiFileName

(

const DataExecution::Operation &

op

)

const

Parameters

op	The operation for which a potential .ui file is being sought.

A custom .ui file for an operation must have the same name as the operation type with .ui appended. It must live in a directory that has the same name as the operation type and that directory must be on the custom widgets search path. See WorkspacePlugin::getCustomWidgetPaths() for more details about widget search paths.

Returns

The file name of a custom .ui file for the specified op, or an empty string if no such custom .ui file could be found. Note that operations frequently don't have a custom .ui file.

getHighlightedWidget()

WidgetWindow * getHighlightedWidget

(

)

const

getHighlightedWidgetTitle()

QString getHighlightedWidgetTitle

(

)

const

getInstance()

WidgetManager & getInstance ( )

static

Returns

The widget manager singleton instance.

getNumWidgetWindows()

unsigned getNumWidgetWindows

(

)

const

Returns

The number of WidgetWindow instances that currently exist. This value is kept up to date by the WidgetWindow constructor and destructor.

getPreferredWidgetName()

QString getPreferredWidgetName

(

WidgetWindow &

w

)

Parameters

w	WidgetWindow to retrieve the type of Widget it is.

getWidgetFactories() [1/2]

std::vector< const WidgetFactory * > getWidgetFactories

(

const DataExecution::DataFactory &

dataFactory

)

const

Returns

A list of all widget factories that are compatible with the supplied dataFactory

getWidgetFactories() [2/2]

WidgetCreators getWidgetFactories

(

const NamePath &

namePath

)

const

getWidgetFactory()

const WidgetFactory * getWidgetFactory

(

const DataExecution::DataFactory &

dataFactory

)

const

Parameters

dataFactory

A data factory for which an appropriate widget factory is being sought.

This function is inferior to createWidget() because it does not allow any customization of the widget creation. In fact, the best it can offer is to find a factory which is compatible with the data type corresponding to dataFactory, whereas createWidget() not only returns the most suitable widget, it also allows the widget to be customized further because it can be described by an arbitrary .ui file and hence set various properties differently for different inputs/outputs of particular operation types.

Returns

A suitable widget factory for data objects created by dataFactory. Note that the widget factory might not be the most suitable, but it will at least be compatible. The logic is essentially to return the first widget factory which is compatible.

getWidgetWindow()

WidgetWindow * getWidgetWindow

(

unsigned

index

)

Parameters

index

The index of the WidgetWindow to retrieve.

The index of a WidgetWindow refers to an internal array maintained by the widget manager. The index for a given WidgetWindow can change if a WidgetWindow with a lower index is removed. Therefore, you should never store this index. It is primarily used as a means to iterate over the list of WidgetWindow instances currently in existence for an application.

Returns

The WidgetWindow stored at the specified index.

insertPreferredWidget()

void insertPreferredWidget	(	WidgetWindow &	w,
		const QString &	widgetName
	)

Parameters

w	WidgetWindow to be stored in hash as key.
widgetName	The QString to be stored inside the hash to record the widget type each WidgetWindow contains.

openDisplay()

QWidget * openDisplay	(	const QString &	uiFileName,
		DataExecution::Operation &	relativeTo
	)

Parameters

uiFileName	The name of a .ui file containing the user interface description to load.
relativeTo	The operation that the display should be made relative to.

removeWidgetWindow()

void removeWidgetWindow

(

WidgetWindow &

w

)

setHighlightedWidget()

void setHighlightedWidget

(

WidgetWindow *

w

)

setHighlightedWidgetTitle()

void setHighlightedWidgetTitle

(

const QString &

title

)

widgetWindowAdded

void widgetWindowAdded ( CSIRO::Widgets::WidgetWindow *  w )

signal

widgetWindowRemoved

void widgetWindowRemoved ( CSIRO::Widgets::WidgetWindow *  w )

signal