Qtilities::CoreGui::ModeManager Class Reference

The ModeManager allows management of application modes. More...

#include <ModeManager.h>

List of all members.

Public Slots
void	setActiveMode (int mode_id, bool refresh_list=false)
	Slot through which a new mode can be set by specifying the mode ID.
void	setActiveMode (const QString &mode_name, bool refresh_list=false)
	Slot through which a new mode can be set by specifying the mode name.
void	setActiveMode (IMode *mode_iface, bool refresh_list=false)
	Slot through which a new mode can be set by specifying the mode interface.
bool	switchToPreviousMode ()
	Switches back to the mode that was previously active before the current mode was activated.

Signals
void	activeModeChanged (int new_mode_id, int old_mode_id)
	Signal which is emitted when the active mode of the application changed.
void	changeCentralWidget (QWidget *new_central_widget)
	This signal is emitted with the new active mode widget as the new_central_widget parameter as soon as the active mode changes.
void	modeListItemSizesChanged ()
	This signal is emitted when the number sizes of items in the mode list changes.

Public Member Functions
int	activeModeID () const
	Returns the active mode ID.
IMode *	activeModeIFace () const
	Returns the active mode interface.
QString	activeModeName () const
	Returns the active mode name.
void	addMode (IMode *mode, bool initialize_mode=true, bool refresh_list=true)
	Adds a mode to the mode widget.
void	addModes (QList< IMode * > modes, bool initialize_modes=true, bool refresh_list=true)
	Adds a list of modes to the main window.
void	addModes (QList< QObject * > modes, bool initialize_modes=true, bool refresh_list=true)
	Adds a list of modes to the main window. This call will attempt to cast each object in the list to IMode* and add the Successful interfaces to the main window.
bool	containsModeId (int mode_id) const
	Checks if a mode is registered in the mode manager.
QList< int >	disabledModeIDs () const
	Gets the mode ids which are disabled.
QList< IMode * >	disabledModeIFaces () const
	Gets the mode interfaces which are disabled.
QStringList	disabledModeNames () const
	Gets the mode names which are disabled.
void	initialize ()
	Initializes the mode widget by displaying all current modes.
int	managerID () const
	Returns an unique ID for this mode manager.
QSize	maximumItemSize () const
	Gets the maximum items size of mode items in the list widget.
QSize	minimumItemSize () const
	Gets the minimum items size of mode items in the list widget.
QListWidget *	modeListWidget ()
	Gets access to the QListWidget which is used to represent the modes.
	ModeManager (int manager_id, Qt::Orientation orientation, QObject *parent=0)
	Default constructor.
QList< IMode * >	modes () const
	A list of the modes in this mode widget.
QString	modeShortcut (int mode_id) const
	Function which returns a string representation of the shortcut assigned to a specific mode.
QList< int >	preferredModeOrderIDs () const
	Gets the preferred mode order's mode IDs where the first items in the list will appear first.
QList< IMode * >	preferredModeOrderIFaces () const
	Gets the preferred mode order's mode interfaces where the first items in the list will appear first.
QStringList	preferredModeOrderNames () const
	Gets the preferred mode order's mode names where the first items in the list will appear first.
QStack< int >	previousModeIDs () const
	Returns a QStack storing the ids of previously active modes.
void	refreshModeList ()
	Refreshes the list of modes in this mode manager by doing a search through the global object pool.
bool	registerModeShortcuts () const
	Gets if the mode manager registers application wide shortcuts for the modes shown.
void	setDisabledModes (const QStringList &disabled_modes)
	Sets the modes which should be disabled using the mode names.
void	setDisabledModes (QList< int > disabled_modes)
	Sets the modes which should be disabled using the unique mode IDs.
void	setDisabledModes (QList< IMode * > disabled_modes)
	Sets the modes which should be disabled using the IMode interfaces.
void	setManagerID (int manager_id)
	Sets the unique ID of this mode manager.
void	setMaximumItemSize (QSize size)
	Sets the maximum items size of mode items in the list widget.
void	setMinimumItemSize (QSize size)
	Sets the minimum items size of mode items in the list widget.
void	setPreferredModeOrder (const QStringList &preferred_order, bool refresh_list=true)
	Sets the preferred order of modes in the mode widget using the names of the modes.
void	setPreferredModeOrder (QList< int > preferred_order, bool refresh_list=true)
	Sets the preferred order of modes in the mode widget using the unique IDs of the modes.
void	setPreferredModeOrder (QList< IMode * > preferred_order, bool refresh_list=true)
	Sets the preferred order of modes in the mode widget using the IMode interfaces of the modes.
void	setRegisterModeShortcuts (bool register_shortcuts)
	Sets if the mode manager registers application wide shortcuts for the modes shown.
QAction *	switchToPreviousModeAction ()
	Convenience function which returns an action which can be placed in a menu to allow switching back to the previous mode.

---

Detailed Description

The ModeManager allows management of application modes.

A mode is any object implementing the Qtilities::CoreGui::Interfaces::IMode interface. Through this interface different application modes can be exposed and this class is responsible to manage all of these modes. The ModeManager class is intended to be used with Qtilities::CoreGui::QtilitiesMainWindow which responds to the changeCentralWidget() signal and displays the mode in the main window. The ModeManager class is a widget which will display a extended QListWidget with a list containing all the registered modes. The list widget can either display the modes in a left to right, or a top to bottom layout depending on the orientation parameter of the ModeManager constructor.

Modes can be easily added using the addMode() or addModes() functions. To get a list of all current modes use the modes() function.

At any given time a single mode must be active where the active mode will be selected in the mode list widget. To get the ID of the active mode use the activeMode() function. It is possible to change the active mode at any time through the setActiveMode() function.

It is possible to specify the order in which modes must appear to the user, or to change it at any time through the setPreferredModeOrder() functions. In some cases it might be needed to disable one or more modes and this can be achieved through the setDisabledModes() function.

By default the list widget is styled to look like a set of application modes, rather than a normal list view. The default stylesheet that is applied to the list is constructed as follows:

QString stylesheet = "";
// Give the view a colored background:
stylesheet += "QListView { background-color: #FFFFFF; border-style: none; }";
// The text underneath the unselected items:
stylesheet += "QListView::item::text { font-weight: bold; border-style: none; color: black }";
// The text underneath the selected item:
stylesheet += "QListView::item:selected:active { font-weight: bold; border-style: none; color: white }";
stylesheet += "QListView::item:selected:!active { font-weight: bold; border-style: none; color: white }";
// Hover effect:
stylesheet += "QListView::item:hover { background: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 white, stop: 0.4 #EEEEEE, stop:1 #CCCCCC); }";
// Selected item gradient:
stylesheet += "QListView::item:selected:active { background: #CCCCCC; }";
stylesheet += "QListView::item:selected:!active { background: #CCCCCC; }";
// The padding of items in the list:
if (d->orientation == Qt::Horizontal)
    stylesheet += "QListView::item { padding: 5px 1px 5px 1px;}";
else
    stylesheet += "QListView::item { padding: 5px 0px 5px 0px;}";
ModeListWidget()->setStyleSheet(stylesheet);

It is possible to change and customize the style of the list through the ModeListWidget() access function to the list widget.

---

Constructor & Destructor Documentation

Qtilities::CoreGui::ModeManager::ModeManager	(	int	manager_id,
		Qt::Orientation	orientation,
		QObject *	parent = 0
	)

Default constructor.

Parameters:

orientation

The orientation of the mode list widget. When Qt::Horizontal the list will be a top to bottom list and when Qt::Vertical the list will be a left to right list.

---

Member Function Documentation

void Qtilities::CoreGui::ModeManager::activeModeChanged ( int  new_mode_id, int  old_mode_id  )

signal

Signal which is emitted when the active mode of the application changed.

Parameters:

new_mode_id	The id of the new active mode. -1 if no mode is active.
old_mode_id	The id of the old mode that was active. -1 if no mode was active before the change.

This function was added in Qtilities v1.2.

void Qtilities::CoreGui::ModeManager::addMode	(	IMode *	mode,
		bool	initialize_mode = true,
		bool	refresh_list = true
	)

Adds a mode to the mode widget.

This function can be called at any time and will cause the mode list to be refreshed.

Parameters:

mode	The mode to be added.
initialize_mode	When true, the mode will be initialized and its context will be added to the context manager if it is not empty.
refresh_list	When true, the mode list widget will be refreshed.

Note:

The mode will only be added if it specifies this manager as one of its manager IDs.

void Qtilities::CoreGui::ModeManager::addModes	(	QList< IMode * >	modes,
		bool	initialize_modes = true,
		bool	refresh_list = true
	)

Adds a list of modes to the main window.

This function can be called at any time and will cause the mode list to be refreshed.

Parameters:

modes	A list of modes to be added.
initialize_mode	When true, each mode will be initialized and its context will be added to the context manager if it is not empty.
refresh_list	When true, the mode list widget will be refreshed.

Note:

Only modes which specify this manager as one of their manager IDs will be added.

void Qtilities::CoreGui::ModeManager::addModes	(	QList< QObject * >	modes,
		bool	initialize_modes = true,
		bool	refresh_list = true
	)

Adds a list of modes to the main window. This call will attempt to cast each object in the list to IMode* and add the Successful interfaces to the main window.

This function can be called at any time and will cause the mode list to be refreshed.

Parameters:

modes	A list of modes to be added.
initialize_mode	When true, each mode will be initialized and its context will be added to the context manager if it is not empty.
refresh_list	When true, the mode list widget will be refreshed.

Note:

Only modes which specify this manager as one of their manager IDs will be added.

QList< int > Qtilities::CoreGui::ModeManager::disabledModeIDs

(

)

const

Gets the mode ids which are disabled.

See also:

setDisabledModes()

QList< IMode * > Qtilities::CoreGui::ModeManager::disabledModeIFaces

(

)

const

Gets the mode interfaces which are disabled.

See also:

setDisabledModes()

QStringList Qtilities::CoreGui::ModeManager::disabledModeNames

(

)

const

Gets the mode names which are disabled.

See also:

setDisabledModes()

void Qtilities::CoreGui::ModeManager::initialize

(

)

Initializes the mode widget by displaying all current modes.

If there are no modes present in the mode manager, refreshModeList() will be called first. However if modes are present this step will be skipped.

Initialization will update the list widget displaying modes.

See also:

refreshModeList()

int Qtilities::CoreGui::ModeManager::managerID

(

)

const

Returns an unique ID for this mode manager.

The Qtilities::CoreGui::Interfaces::IMode interface allows you to specify the mode manager in which the mode must be shown. This allows you to have multiple modes in your application.

The mode ID for the manager can be set using setManagerID() or in the constructor. By default the manager ID will be -1 and no modes will be assigned to it.

Note:

Manager IDs available for user managers range from 100 - 999. The default manager created by Qtilities::CoreGui::QtilitiesMainWindow uses the mode defined by qti_def_DEFAULT_MODE_MANAGER.

See also:

setManagerID().

QSize CoreGui::ModeManager::maximumItemSize

(

)

const

Gets the maximum items size of mode items in the list widget.

Returns:

The maximum size. Dimensions < 0 will be ignored.

See also:

minimumItemSize(), setMinimumItemSize(), setMaximumItemSize()

This function was added in Qtilities v1.1.

QSize CoreGui::ModeManager::minimumItemSize

(

)

const

Gets the minimum items size of mode items in the list widget.

Parameters:

size	The minimum size. Dimensions < 0 will be ignored.

See also:

setMaximumItemSize(), setMinimumItemSize(), maximumItemSize();

This function was added in Qtilities v1.1.

QList< Qtilities::CoreGui::Interfaces::IMode * > Qtilities::CoreGui::ModeManager::modes

(

)

const

A list of the modes in this mode widget.

See also:

addMode(), addModes()

QList< int > Qtilities::CoreGui::ModeManager::preferredModeOrderIDs

(

)

const

Gets the preferred mode order's mode IDs where the first items in the list will appear first.

See also:

setPreferredModeOrder()

QList< Qtilities::CoreGui::Interfaces::IMode * > Qtilities::CoreGui::ModeManager::preferredModeOrderIFaces

(

)

const

Gets the preferred mode order's mode interfaces where the first items in the list will appear first.

See also:

setPreferredModeOrder()

QStringList Qtilities::CoreGui::ModeManager::preferredModeOrderNames

(

)

const

Gets the preferred mode order's mode names where the first items in the list will appear first.

See also:

setPreferredModeOrder()

QStack< int > CoreGui::ModeManager::previousModeIDs

(

)

const

Returns a QStack storing the ids of previously active modes.

This function was added in Qtilities v1.2.

void CoreGui::ModeManager::refreshModeList

(

)

Refreshes the list of modes in this mode manager by doing a search through the global object pool.

This function will search the global object pool and automatically add all found modes. A debug message with information about the found pages will be created. All found modes will automatically be initialized.

More modes can be added at a later stage using the addMode() and addModes() functions. A list of modes can be found using modes().

Note:

This function only refreshes all modes, it does not populate the mode list widget. To do that, call initialize().

bool CoreGui::ModeManager::registerModeShortcuts

(

)

const

Gets if the mode manager registers application wide shortcuts for the modes shown.

True by default.

See also:

setRegisterModeShortcuts()

void Qtilities::CoreGui::ModeManager::setActiveMode ( int  mode_id, bool  refresh_list = false  )

slot

Slot through which a new mode can be set by specifying the mode ID.

Parameters:

mode_id

The mode ID of the mode.

See also:

IMode::modeID().

Parameters:

refresh_list

When true, the mode list widget will be refreshed.

Note:

If mode_id appears in the list of disabled modes, this function does nothing.

void Qtilities::CoreGui::ModeManager::setActiveMode ( const QString &  mode_name, bool  refresh_list = false  )

slot

Slot through which a new mode can be set by specifying the mode name.

Parameters:

mode_name

The name of the mode.

See also:

IMode::text().

Parameters:

refresh_list

When true, the mode list widget will be refreshed.

Note:

If mode_id appears in the list of disabled modes, this function does nothing.

void Qtilities::CoreGui::ModeManager::setActiveMode ( IMode *  mode_iface, bool  refresh_list = false  )

slot

Slot through which a new mode can be set by specifying the mode interface.

Note:

If mode_id appears in the list of disabled modes, this function does nothing.

Parameters:

refresh_list

When true, the mode list widget will be refreshed.

void Qtilities::CoreGui::ModeManager::setDisabledModes

(

const QStringList &

disabled_modes

)

Sets the modes which should be disabled using the mode names.

To enable all modes, just pass an empty QStringList as the disabled_modes parameter.

See also:

disabledModeNames()

void Qtilities::CoreGui::ModeManager::setDisabledModes

(

QList< int >

disabled_modes

)

Sets the modes which should be disabled using the unique mode IDs.

To enable all modes, just pass an empty list as the disabled_modes parameter.

See also:

disabledModeNames()

void Qtilities::CoreGui::ModeManager::setDisabledModes

(

QList< IMode * >

disabled_modes

)

Sets the modes which should be disabled using the IMode interfaces.

To enable all modes, just pass an empty list as the disabled_modes parameter.

See also:

disabledModeNames()

void Qtilities::CoreGui::ModeManager::setManagerID

(

int

manager_id

)

Sets the unique ID of this mode manager.

See also:

managerID()

void CoreGui::ModeManager::setMaximumItemSize

(

QSize

size

)

Sets the maximum items size of mode items in the list widget.

Returns:

The maximum size. Dimensions < 0 will be ignored.

See also:

setMinimumItemSize(), maximumItemSize(), minimumItemSize()

This function was added in Qtilities v1.1.

void CoreGui::ModeManager::setMinimumItemSize

(

QSize

size

)

Sets the minimum items size of mode items in the list widget.

Parameters:

size	The minimum size. Dimensions < 0 will be ignored.

See also:

setMaximumItemSize(), maximumItemSize(), minimumItemSize()

This function was added in Qtilities v1.1.

void Qtilities::CoreGui::ModeManager::setPreferredModeOrder	(	const QStringList &	preferred_order,
		bool	refresh_list = true
	)

Sets the preferred order of modes in the mode widget using the names of the modes.

A QStringList with the names of the modes in the order in which they should appear. The first item in the list will appear first, the last item last. If a mode exists which does not appear in the order list, it will be placed after all modes which appear in the list. In the same way, if a mode name is specified in the preferred list which does not appear in the list of modes it will be placed after all modes which appear in the list.

Important: The modes listed in preferred_order must be registered in the mode manager for this function to work. If the modes are not there yet, you must use the QList<int> parameter alternative of this function.

Note:

This function will automatically refresh the view if modes are already present at the time the function is called.

void Qtilities::CoreGui::ModeManager::setPreferredModeOrder	(	QList< int >	preferred_order,
		bool	refresh_list = true
	)

Sets the preferred order of modes in the mode widget using the unique IDs of the modes.

An integer list with the ids of the modes in the order in which they should appear. The first item in the list will appear first, the last item last. If a mode exists which does not appear in the order list, it will be placed after all modes which appear in the list. In the same way, if a mode name is specified in the preferred list which does not appear in the list of modes it will be placed after all modes which appear in the list.

Note:

This function will automatically refresh the view if modes are already present at the time the function is called.

void Qtilities::CoreGui::ModeManager::setPreferredModeOrder	(	QList< IMode * >	preferred_order,
		bool	refresh_list = true
	)

Sets the preferred order of modes in the mode widget using the IMode interfaces of the modes.

A QStringList with the names of the modes in the order in which they should appear. The first item in the list will appear first, the last item last. If a mode exists which does not appear in the order list, it will be placed after all modes which appear in the list. In the same way, if a mode name is specified in the preferred list which does not appear in the list of modes it will be placed after all modes which appear in the list.

Important: The modes listed in preferred_order must be registered in the mode manager for this function to work. If the modes are not there yet, you must use the QList<int> parameter alternative of this function.

Note:

This function will automatically refresh the view if modes are already present at the time the function is called.

void CoreGui::ModeManager::setRegisterModeShortcuts

(

bool

register_shortcuts

)

Sets if the mode manager registers application wide shortcuts for the modes shown.

True by default.

Note:

This function must be called before initializing the design the first time.

See also:

registerModeShortcuts()

bool CoreGui::ModeManager::switchToPreviousMode ( )

slot

Switches back to the mode that was previously active before the current mode was activated.

This function was added in Qtilities v1.2.

QAction * CoreGui::ModeManager::switchToPreviousModeAction

(

)

Convenience function which returns an action which can be placed in a menu to allow switching back to the previous mode.

This action will be disabled when there is no valid previous mode.

This function was added in Qtilities v1.2.