A QtilitiesCategory object represents a category in Qtilities. More...

#include <QtilitiesCategory.h>

Inheritance diagram for Qtilities::Core::QtilitiesCategory:

Public Member Functions
int	accessMode () const
	Gets the access mode of this category.
void	addLevel (const QString &name)
	Adds a level to the category by providing the information needed to construct a CategoryLevel.
void	addLevel (CategoryLevel category_level)
	Adds a level to the category by providing a ready to use CategoryLevel structure.
QString	categoryBottom () const
	Returns the bottom level category in this category object.
int	categoryDepth () const
	Returns the depth of this category.
QList< CategoryLevel >	categoryLevels () const
	Returns the category levels where the first item in the list is always the top level category and the last item is the bottom level.
QString	categoryTop () const
	Returns the top level category in this category object.
void	clear ()
	Clears the category.
IExportable::ExportResultFlags	exportBinary (QDataStream &stream) const
	Allows exporting to a QDataStream.
IExportable::ExportResultFlags	exportXml (QDomDocument doc, QDomElement object_node) const
IExportable::ExportResultFlags	importBinary (QDataStream &stream, QList< QPointer< QObject > > &import_list)
	Allows importing and reconstruction of the object state from information provided in a QDataStream.
IExportable::ExportResultFlags	importXml (QDomDocument doc, QDomElement object_node, QList< QPointer< QObject > > &import_list)
	Allows importing and reconstruction of data from information provided in a XML document. A reference to the QDomElement which contains the object's information is provided, along with a reference to the QDomDocument.
bool	isEmpty () const
	Indicates if this category is empty. Thus no levels have been added to it.
bool	isValid () const
	Indicates if this category is valid.
QObject *	objectBase ()
const QObject *	objectBase () const
bool	operator!= (const QtilitiesCategory &ref) const
	Operator overload to compare two QtilitiesCategory objects are not equal.
bool	operator< (const QtilitiesCategory &e1) const
	Overload < operator so that we can use QtilitiesCategory in a QMap.
QtilitiesCategory &	operator<< (const QString &category_level_name)
	Overload << operator so that we can build up a category structure in the same way as QStringList.
bool	operator<= (const QtilitiesCategory &e1) const
	Overload <= operator.
bool	operator== (const QtilitiesCategory &ref) const
	Operator overload to compare two QtilitiesCategory objects with each other.
bool	operator> (const QtilitiesCategory &e1) const
	Overload > operator.
bool	operator>= (const QtilitiesCategory &e1) const
	Overload >= operator.
	QtilitiesCategory (const QString &category_level_name=QString())
	Constructs a QtilitiesCategory object.
	QtilitiesCategory (const QString &category_levels, const QString &seperator)
	Constructs a QtilitiesCategory object.
	QtilitiesCategory (const QStringList &category_name_list)
	Creates a QtilitiesCategory object from a QStringList.
void	setAccessMode (int access_mode)
	Sets the access mode of this category.
void	setExportVersion (Qtilities::ExportVersion version)
	Returns the export version currently used by all Qtilities classes.
ExportModeFlags	supportedFormats () const
	Provides information about the export format(s) supported by your implementation of IExportable.
QString	toString (const QString &join_string="::") const
	Returns the category as a QString.
QStringList	toStringList (int level=-1) const
	Returns the category as a QStringList.
Public Member Functions inherited from Qtilities::Core::Interfaces::IExportable
quint32	applicationExportVersion () const
	Returns the application export version currently used by all your application's classes.
virtual void	clearExportTask ()
	Clears the export task.
IExportable *	duplicate (QString error_msg=0, int properties_to_copy=0, ExportResultFlags result_flags=0) const
	Function which will create a duplicate (copy) of this object.
virtual ITask *	exportTask () const
	Gets the task which must be used to log import/export information to.
Qtilities::ExportVersion	exportVersion () const
	Returns the export version currently used by all Qtilities classes.
virtual InstanceFactoryInfo	instanceFactoryInfo () const
	The instance factory information which must be used when the exported object is reconstructed during an import.
bool	isExportable () const
	Gets if this object must be part of it's parents' exports.
virtual void	setApplicationExportVersion (quint32 version)
	Sets the application export version currently used by all your application's classes.
virtual void	setExportTask (ITask *task)
	Sets the task which must be used to log import/export information to.
virtual void	setIsExportable (bool new_is_exportable)
	Sets if this object must be part of it's parents' exports.
Public Member Functions inherited from Qtilities::Core::Interfaces::IObjectBase
QString	objectOriginID () const
	Allows interfaces to provide some sort of source identification.
void	setObjectOriginID (const QString &object_origin_id)
	Allows setting of the object source ID of this interface implementation.

Additional Inherited Members
Public Types inherited from Qtilities::Core::Interfaces::IExportable
enum	ExportMode { None = 0, Binary = 1, XML = 2 }
	Possible export modes that an implementation of IExportable can support. More...
enum	Result { Complete = 0, Incomplete = 1, Failed = 2, FailedContinue = 4, VersionTooNew = 8, VersionTooOld = 16, VersionSupported = 32, SuccessResult = Complete \| Incomplete \| VersionSupported, FailedResult = Failed \| FailedContinue \| VersionTooNew \| VersionTooOld }
	The possible results of an export/import operation. More...
Static Public Member Functions inherited from Qtilities::Core::Interfaces::IExportable
template<typename T >
static T *	duplicateInstance (IExportable obj, QString error_msg=0, int properties_to_copy=0, ExportResultFlags *result_flags=0)
	Provides an easy to use template based implementation of IExportable::duplicate().
static QString	exportModeToString (ExportMode export_mode)
	Function which returns a string associated with a specific ExportMode.
static ExportMode	stringToExportMode (const QString &export_mode_string)
	Function which returns the ExportMode associated with a string.
static Result	validateQtilitiesExportVersion (Qtilities::ExportVersion export_version, ITask *task=0)
	Checks the exportVersion() against the supported Qtilities export versions for the current Qtilities version.
static Result	validateQtilitiesImportVersion (Qtilities::ExportVersion import_version, ITask *task=0)
	Checks the exportVersion() against the supported Qtilities import versions for the current Qtilities version.

Detailed Description

A QtilitiesCategory object represents a category in Qtilities.

The QtilitiesCategory class can be used to define a category for an object. The category can be any number of levels deep where each level is a CategoryLevel instance.

We can construct a category object as follows:

// A category with a single level:
QtilitiesCategory single_category("My Category");
// If we want to use a category with multiple levels:
// One way to do it:
QtilitiesCategory category;
category << "Top Level Category" << "Middle Level Category" << "Lowest Level Category";
// Another way to do it:
QtilitiesCategory category("Top Level Category::Middle Level Category::Lowest Level Category","::");
// Yet another way to do it:
QStringList category_list;
category_list << "Top Level Category" << "Middle Level Category" << "Lowest Level Category";
QtilitiesCategory category(category_list);

We can check if a category is valid using isValid() where a valid category is a category with at least one level. The category depth is available through categoryDepth() and the top and bottom level category names are available through categoryTop() and categoryBottom() respectively. The category can be converted to a string using toString() or to a string list using toStringList().

It is possible to set the access mode of a category using setAccessMode() and the access mode can be accessed using accessMode(). A QtilitiesCategory object supports streaming to a QDataStream or saving its data to a XML QDomElement node. This is made possible by the implementation of Qtilities::Core::Interfaces::IExportable.

Usage Scenario

Lets look at one example usage of QtilitiesCategory: The Observer class supports the grouping of objects into categories by inspecting objects attached to it for the qti_prop_CATEGORY_MAP property. We can add an object in a specific category to an Observer context in a couple of ways:

// Using Observer directly:
Observer* observer = new Observer("My Node");
observer->useDisplayHints();
observer->displayHints()->setHierarchicalDisplayHint(ObserverHints::CategorizedDisplay);
QObject* object = new QObject();
object->setObjectName("Categorized Item");
MultiContextProperty category_property(qti_prop_CATEGORY_MAP);
category_property.setValue(qVariantFromValue(QtilitiesCategory("Item Category")),observer->observerID());
ObjectManager::setMultiContextProperty(object,category_property);
observer->attachSubject(object);
// Using TreeNode (which inherits from Observer):
TreeNode* node = new TreeNode("My Node");
node->enableCategorizedDisplay();
node->addItem("Categorized Item",QtilitiesCategory("Item Category"));

Usage in Qtilities

In Qtilities categories are used in a few places and by using the QtilitiesCategory class everywhere we make sure that categories are handled the same way everywhere. Some usages in Qtilities:

The Qtilities::CoreGui::Interfaces::IActionProvider interface allows grouping of actions into categories.
Observer classes allows grouping of subjects into categories.
Factory classes allows grouping of registered interfaces into categories.
Qtilities::CoreGui::Interfaces::IConfigPage implementations allows grouping of the pages into categories in the Qtilities::CoreGui::ConfigurationWidget.

This class was added in Qtilities v0.2.

Constructor & Destructor Documentation

Qtilities::Core::QtilitiesCategory::QtilitiesCategory ( const QString & category_level_name = QString() )

Constructs a QtilitiesCategory object.

Parameters:

category_level_name	When this parameter contains a valid string, it will be used as the top level category level.
access_mode	The access mode of this category. By default we use Observer::InvalidAccess since the mode is not always going to be used.

Qtilities::Core::QtilitiesCategory::QtilitiesCategory	(	const QString &	category_levels,
		const QString &	seperator
	)

Constructs a QtilitiesCategory object.

Parameters:

category_levels	A QString containing a list of categories seperated by the `seperator` parameter.
seperator	The seperator string used to split the `category_levels` parameter.

Member Function Documentation

QString Qtilities::Core::QtilitiesCategory::categoryBottom ( ) const

inline

Returns the bottom level category in this category object.

This function is a convenience function. It returns the same as categoryLevels().back().d_name;

QString Qtilities::Core::QtilitiesCategory::categoryTop ( ) const

inline

Returns the top level category in this category object.

This function is a convenience function. It returns the same as categoryLevels().front().d_name;

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::QtilitiesCategory::exportBinary ( QDataStream & stream ) const

virtual

Allows exporting to a QDataStream.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Parameters:

stream A reference to the QDataStream to which the object's information must be appended is provided.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::QtilitiesCategory::exportXml	(	QDomDocument *	doc,
		QDomElement *	object_node
	)		const

virtual

This function adds a category node under object_node with all the information about this category.

Note:: The category icon is not exported along with your category.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::QtilitiesCategory::importBinary	(	QDataStream &	stream,
		QList< QPointer< QObject > > &	import_list
	)

virtual

Allows importing and reconstruction of the object state from information provided in a QDataStream.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Parameters:

stream	The QDataStream which contains the object's information.
import_list	All objects constructed during the import operation must be added to the import list. When the operation fails, all objects in this list will be deleted.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::QtilitiesCategory::importXml	(	QDomDocument *	doc,
		QDomElement *	object_node,
		QList< QPointer< QObject > > &	import_list
	)

virtual

Allows importing and reconstruction of data from information provided in a XML document. A reference to the QDomElement which contains the object's information is provided, along with a reference to the QDomDocument.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

bool Qtilities::Core::QtilitiesCategory::isValid ( ) const

inline

Indicates if this category is valid.

The validation check checks if the category has any levels, if not it is invalid.

QObject* Qtilities::Core::QtilitiesCategory::objectBase ( )

inlinevirtual

Note:: QtilitiesCategory is now a QObject, thus it returns 0.

Implements Qtilities::Core::Interfaces::IObjectBase.

const QObject* Qtilities::Core::QtilitiesCategory::objectBase ( ) const

inlinevirtual

Note:: QtilitiesCategory is now a QObject, thus it returns 0.

Implements Qtilities::Core::Interfaces::IObjectBase.

bool Qtilities::Core::QtilitiesCategory::operator!= ( const QtilitiesCategory & ref ) const

Operator overload to compare two QtilitiesCategory objects are not equal.

Note:: Only the category names are used in this comparison.

bool Qtilities::Core::QtilitiesCategory::operator== ( const QtilitiesCategory & ref ) const

Operator overload to compare two QtilitiesCategory objects with each other.

Note:: Only the category names are used in this comparison.

void Qtilities::Core::QtilitiesCategory::setExportVersion ( Qtilities::ExportVersion version )

virtual

Returns the export version currently used by all Qtilities classes.

By default the latest Qtilities version is selected.

See also:: exportVersion()

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportModeFlags Qtilities::Core::QtilitiesCategory::supportedFormats ( ) const

virtual

Provides information about the export format(s) supported by your implementation of IExportable.

Note:: It is important to note that you need to check the exportVersion() when you return the supported formats.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

QString Qtilities::Core::QtilitiesCategory::toString ( const QString & join_string = "::" ) const

Returns the category as a QString.

Parameters:

join_string The string that must be used to join the category level names.

Returns:: The joined category string. For example when join_string is :: we get TopLevelCategory::MiddleLevelCategory::LowerLevelCategory

QStringList Qtilities::Core::QtilitiesCategory::toStringList ( int level = -1 ) const

Returns the category as a QStringList.

Parameters:

level The depth of the requested string list. If the category has for example 3 levels, you can only get the first 2 levels by passing 2 as the level parameter. If level is bigger than the depth (number of levels) of the category, the depth of the category will be used.

Public Member Functions

Additional Inherited Members

Detailed Description

Usage Scenario

Usage in Qtilities

Constructor & Destructor Documentation

Member Function Documentation