The main class that represents the dialog itself. More...

#include <qsettingsdialog.h>

Inheritance diagram for QSettingsDialog:

Public Slots
void	openSettings (QWidget *parentWindow=nullptr)
	Creates a new display dialog and shows it without blocking. More...

int	execSettings (QWidget *parentWindow=nullptr)
	Creates a new display dialog and shows it blocking. More...

Signals
void	saved (bool closed)
	Will be emitted everytime the user saves his settings. More...

void	resetted ()
	Will be emitted if the user resets the settings. More...

void	canceled ()
	Will be emitted if the user canceld the settings dialog.

Public Member Functions
	QSettingsDialog (QObject *parent=nullptr)
	Creates a new settings dialog with a parent.

	QSettingsDialog (QSettingsDisplayEngine engine, QObject parent=nullptr)
	Creates a new settings dialog with a parent and a custom display engine.

	~QSettingsDialog ()
	Destructor.

QSettingsDisplayEngine *	displayEngine () const
	Returns the current display engine of dialog.

void	setDisplayEngine (QSettingsDisplayEngine *engine)
	Sets the display engine to a new one. More...

QString	containerPath () const
	Returns the complete current container path. More...

QString	sectionContainerPath () const
	Returns the current container path up to the section, excluding groups.

QString	categoryId () const
	Returns the current category id.

QString	sectionId () const
	Returns the current section id.

QString	groupId () const
	Returns the current group id. More...

void	setCategory (const QString &id, const QString &name=QString(), const QIcon &icon=QIcon(), const QString &tooltip=QString())
	Sets the current category and optionally modifies it's appeareance. More...

void	setSection (const QString &id, const QString &name=QString(), const QIcon &icon=QIcon(), const QString &tooltip=QString())
	Sets the current section and optionally modifies it's appeareance. More...

void	setGroup (const QString &id, int displayId=-1, const QString &name=QString(), int optional=-1, const QString &tooltip=QString())
	Sets the current group and optionally modifies it's appeareance. More...

void	unsetGroup ()
	Sets the current group to nothing. More...

void	setContainer (const QString &containerPath)
	Sets the whole container path (category, section and (optionally) group) More...

bool	removeContainer (const QString &containerPath)
	Removes the container with the given path. More...

QSettingsContainer *	currentContainer (QObject *parent=nullptr)
	Creates a new settings container for the current path configuration.

QSettingsContainer *	currentContainerAsync (QObject *parent=nullptr)
	Creates a new async settings container for the current path configuration.

QSettingsContainer *	currentSectionContainer (QObject *parent=nullptr)
	Creates a new settings container for the current section.

QSettingsContainer *	currentSectionContainerAsync (QObject *parent=nullptr)
	Creates a new async settings container for the current section.

int	appendEntry (QSettingsEntry *entry)
	Appends the given entry to the current container. More...

int	appendEntry (const QString &containerPath, QSettingsEntry *entry)
	Appends the given entry to to the container specified. More...

int	prependEntry (QSettingsEntry *entry)
	Prepends the given entry to the current container. More...

int	prependEntry (const QString &containerPath, QSettingsEntry *entry)
	Prepends the given entry to to the container specified. More...

QSharedPointer< QSettingsEntry >	getEntry (int id) const
	Searches for an entry with the given id. More...

QString	getEntryPath (int id) const
	Searches for the path of the container of the entry with the given id. More...

bool	removeEntry (int id)
	Searches for an entry with the given id and removes it. More...

Public Member Functions inherited from QObject
	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

virtual const QMetaObject *	metaObject () const

QString	objectName () const

void	setObjectName (const QString &name)

bool	isWidgetType () const

bool	isWindowType () const

bool	signalsBlocked () const

bool	blockSignals (bool block)

QThread *	thread () const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const

const QObjectList &	children () const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const

bool	disconnect (const char signal, const QObject receiver, const char *method) const

bool	disconnect (const QObject receiver, const char method) const

void	dumpObjectTree ()

void	dumpObjectInfo ()

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const

QList< QByteArray >	dynamicPropertyNames () const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const

bool	inherits (const char *className) const

void	deleteLater ()

Static Public Member Functions
static QString	createContainerPath (QString category=QString(), QString section=QString(), QString group=QString())
	Creates a container path string from category, section and group. More...

Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Friends
class	QSettingsDialogPrivate

Additional Inherited Members
Protected Member Functions inherited from QObject
QObject *	sender () const

int	senderSignalIndex () const

int	receivers (const char *signal) const

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Properties inherited from QObject
	objectName

Detailed Description

The main class that represents the dialog itself.

The settings dialog is the core class of the QSettingsDialog library. It manages the virtual representation of the settings entries.

Dialog structure

A settings dialog provides the following structure:

QSettingsDialog
 |
 |--Category
 |   |
 |   |--Section
 |   |   |
 |   |   |--QSettingsEntry
 |   |   |
 |   |   |--Group
 |   |   |   |
 |   |   |   |--QSettingsEntry
 |   |   |   ⋮
 |   |   ⋮
 |   ⋮
 ⋮

The dialog itself contains categories. Each category is made up of sections. Each section can contain entries and groups. Groups can contain QSettingsEntries. While the dialog itself an the entries are classes, the 3 others are internally used and can be indirectly created and modified through the QSettingsDialog.

The dialog proivdes general and simple members to access and modify all of the listed elements, but only in a limited way, that should suffice for most applications. However, if you need more control of the organization of these elements and their appereance, the QSettingsLayout will be useful. For more option on the entries and some encapsulation, the QSettingsContainer will be at your aid.

Settings Path

The dialog uses a path based mechanism to identify containers and entries. Each container (categories, sections and groups) has a string id that can be any combination of latin letters (both cases), numbers, the underscore and hyphen. Path elements are seperated by a slash. Default containers (categories and sections only) can be set using a dot. In some functions, an empty string means to use the current container. Function that accept empty ids are marked as such. Using simply two dots as a full path is a shortcut for "default category, default section, no group". A completly emty path means the same as two slashes

The following shows a few example paths.

- category/section/group       -> category, section, group
- category/another_section     -> category, another_section, [no group]
- category/./grp3              -> category, [default section], grp3
- .//more-group                -> [default category], [current section], more-group
- //                           -> [current category], [current section], [current group]
- ..                           -> [default category], [default section], [no group]
- /.                           -> [current category], [default section], [no group]
-                              -> [current category], [current section], [current group]

Member Function Documentation

QSettingsDialog::appendEntry ( QSettingsEntry * entry )

Appends the given entry to the current container.

Parameters

entry The entry to be appended

Returns: The new id of the entry. Can be used to get the entry

Appends to the entry to the current container. This can either be a group or a section, depeding on whether it is set or not.

Note: The dialog will take ownership of the entry

QSettingsDialog::appendEntry	(	const QString &	containerPath,
		QSettingsEntry *	entry
	)

Appends the given entry to to the container specified.

Parameters

containerPath	The container to insert the entry into
entry	The entry to be appended

Returns: The new id of the entry. Can be used to get the entry

Exceptions

InvalidContainerPathException Will be thrown if the path is not a valid container path

Appends to the entry to the given container. This can either be a group or a section. You can use empty ids to use current elements. If containers within the path do not exist, they will be created with the id as name. This function will not change the current container.

Note: The dialog will take ownership of the entry

QSettingsDialog::containerPath ( ) const

Returns the complete current container path.

Returns: a valid settings path

Depending on whehter the group is currently set, this path can contain either only category and section, or all three: category/section/group or category/section

QSettingsDialog::createContainerPath	(	QString	category = `QString()`,
		QString	section = `QString()`,
		QString	group = `QString()`
	)

static

Creates a container path string from category, section and group.

Parameters

category	The category id for the path
section	The section id for the path
group	The group id for the path, or a null string to exclude the group

Returns: The resulting path, if all ids are valid

Exceptions

InvalidContainerPathException Will be thrown if one of the ids is not a valid container id

The path will be generated as is, i.e. empty strings will stay empty. If group is a null string, the path will be a section path (2 elements). If not, the path will contain all 3 elements.

Attention: For the group id, null and empty strings make a difference. If the group is only empty, not null, a group path will be created. To create a null string, simply use QString(). For an empty string that is not null, use QString("") instead.

QSettingsDialog::execSettings ( QWidget * parentWindow = nullptr )

slot

Creates a new display dialog and shows it blocking.

Parameters

parentWindow The parent window the dialog should be created for. nullptr to create a root window.

Returns: The exec result of the dialog (See QDialog::DialogCode)

Note: Only one settings dialog can be shown at a time. Calling this function while the dialog is running will generate a warning and return -1.

QSettingsDialog::getEntry ( int id ) const

Searches for an entry with the given id.

Parameters

id	The id of the entry searched for

Returns: The entry as shared pointer, if existing.

If the settings dialog has an entry somewhere with that id, it will be returned. If not, a null pointer.

Note: This function performs a recursive search through all containers until the id was found. The more containers and elements the dialog has, the longer this will take.

QSettingsDialog::getEntryPath ( int id ) const

Searches for the path of the container of the entry with the given id.

Parameters

id	The id of the entry searched for

Returns: The path of the container that holds this entry, or a null string

If the settings dialog has an entry somewhere with that id, the path to the container it is placed in will be returned. If not, a null string.

Note: This function performs a recursive search through all containers until the id was found. The more containers and elements the dialog has, the longer this will take.

QSettingsDialog::groupId ( ) const

Returns the current group id.

Returns: the id of the current group, or a null string if no group is currently set

QSettingsDialog::openSettings ( QWidget * parentWindow = nullptr )

slot

Creates a new display dialog and shows it without blocking.

Parameters

parentWindow The parent window the dialog should be created for. nullptr to create a root window.

Note: Only one settings dialog can be shown at a time. Calling this function while the dialog is running will generate a warning and do nothing.

QSettingsDialog::prependEntry ( QSettingsEntry * entry )

Prepends the given entry to the current container.

Parameters

entry The entry to be prepended

Returns: The new id of the entry. Can be used to get the entry

Prepends to the entry to the current container. This can either be a group or a section, depeding on whether it is set or not.

Note: The dialog will take ownership of the entry

QSettingsDialog::prependEntry	(	const QString &	containerPath,
		QSettingsEntry *	entry
	)

Prepends the given entry to to the container specified.

Parameters

containerPath	The container to insert the entry into
entry	The entry to be prepended

Returns: The new id of the entry. Can be used to get the entry

Exceptions

InvalidContainerPathException Will be thrown if the path is not a valid container path

Prepends to the entry to the given container. This can either be a group or a section. You can use empty ids to use current elements. If containers within the path do not exist, they will be created with the id as name. This function will not change the current container.

Note: The dialog will take ownership of the entry

QSettingsDialog::removeContainer ( const QString & containerPath )

Removes the container with the given path.

Parameters

containerPath The container path that should be removed

Returns: true, if a container with that path was removed, false if it does not exist

Exceptions

InvalidContainerPathException Will be thrown if the path is not a valid container path

Use this function to remove any container based on a path. You can pass in a single id, a path of two or a path of three elements. If you have only an id, the category with that id will be removed. Using a two element path will remove the section within the given category. The same happens for paths with 3 elements with groups. You can use empty ids for all elements.

Attention: If you remove a currently active container, this will delete the container and all it's contents, but not unset the container as current. You can manually change the current container in that case. If you don't do it, the container will be recreated as soon as it is accessed. (For example by adding a child element to it)

QSettingsDialog::removeEntry ( int id )

Searches for an entry with the given id and removes it.

Parameters

id	The id of the entry to be removed

Returns: true, if an entry with that id was found and removed, false if not

If the settings dialog has an entry somewhere with that id, it will be deleted and true returned. If not, false.

Note: This function performs a recursive search through all containers until the id was found. The more containers and elements the dialog has, the longer this will take.

QSettingsDialog::resetted ( )

signal

Will be emitted if the user resets the settings.

Resettings a dialog will automatically close it. If using a Qt::QueuedConnection, it is possible to show a new dialog directly from the slot.

Canceling a dialog will automatically close it. If using a Qt::QueuedConnection, it is possible to show a new dialog directly from the slot.

QSettingsDialog::saved ( bool closed )

signal

Will be emitted everytime the user saves his settings.

Parameters

closed Indicates, whether the dialog was closed with that saving action.

Since most dialogs support both, apply and ok, this signal can be emitted multiple times with false. Once it was emitted with true, the dialog is considered closed and, if using a Qt::QueuedConnection, it is possible to show a new dialog directly from the slot.

QSettingsDialog::setCategory	(	const QString &	id,
		const QString &	name = `QString()`,
		const QIcon &	icon = `QIcon()`,
		const QString &	tooltip = `QString()`
	)

Sets the current category and optionally modifies it's appeareance.

Parameters

id	The id of the category to be set
name	The display name of the category
icon	The display icon of the category
tooltip	The tooltip for the category element

Exceptions

InvalidContainerPathException Will be thrown if id is not a valid container id

This function will set the dialogs current category to id, if it is valid. If there is no category existing with that id a new one will be created with the id as default name. If you leave id empty, the current category will be used. Regardles of whether the category was created or not, if name is not null, this will be set as new name. Same goes for icon and tooltip.

QSettingsDialog::setContainer ( const QString & containerPath )

Sets the whole container path (category, section and (optionally) group)

Parameters

containerPath The container path this dialog should be set to

Exceptions

InvalidContainerPathException Will be thrown if the path is not a valid container path

Use this function to set containers based on a path. If any of the ids in the path does not yet exist, new containers will be created with the id as name. You can use all kinds of valid paths for this function, including empty elements to keep the current container for that path part. if you use 1 slash (just category and section), the group will be unset. use 2 slashes and an empty group id to keep the current group.

Warning: This function will NOT create the new containers. It will just set the id. The containers will be automatically created as soon as they are accessed. (For example by adding a child element to it). To explicitly create the containers, use the setter functions.

void QSettingsDialog::setDisplayEngine ( QSettingsDisplayEngine * engine )

Sets the display engine to a new one.

Note: The dialog will take ownership of the engine

QSettingsDialog::setGroup	(	const QString &	id,
		int	displayId = `-1`,
		const QString &	name = `QString()`,
		int	optional = `-1`,
		const QString &	tooltip = `QString()`
	)

Sets the current group and optionally modifies it's appeareance.

Parameters

id	The id of the group to be set
displayId	The display id of the section.
name	The display name of the group
optional	Sets the group to be optional or not
tooltip	The tooltip for the group element

Exceptions

InvalidContainerPathException Will be thrown if id is not a valid container id

This function will set the dialogs current group to id, if it is valid. If there is no group existing with that id a new one will be created with the id as default name and 0 as display id. If you leave id empty, the current section will be used. Regardles of whether the group was created or not, if name is not null, this will be set as new name. Same goes for the tooltip, and displayId and optional if they are not negative. optional will be converted to bool. If you want to set it, simply use true and false as values.

The displayId can be used to create a group with a custom appeareance. The default group (0) will always be defined. Check the QSettingsWidgetDialogEngine for more details about custom groups.

Groups are optional. If not group is set, new entries will be placed in the section. Use QSettingsDialog::unsetGroup to unset groups.

QSettingsDialog::setSection	(	const QString &	id,
		const QString &	name = `QString()`,
		const QIcon &	icon = `QIcon()`,
		const QString &	tooltip = `QString()`
	)

Sets the current section and optionally modifies it's appeareance.

Parameters

id	The id of the section to be set
name	The display name of the section
icon	The display icon of the section
tooltip	The tooltip for the section element

Exceptions

InvalidContainerPathException Will be thrown if id is not a valid container id

This function will set the dialogs current section to id, if it is valid. If there is no section existing with that id a new one will be created with the id as default name. If you leave id empty, the current section will be used. Regardles of whether the section was created or not, if name is not null, this will be set as new name. Same goes for icon and tooltip.

QSettingsDialog::unsetGroup ( )

Sets the current group to nothing.

After this call, entries will be placed in the current section again, instead of a group. Unsettings a group does not delete it, only change the current group to nothing. To set a group again, use QSettingsDialog::setGroup.

The documentation for this class was generated from the following files:

D:/felix/linked/Qworkplace/QSettingsDialog/QSettingsDialog/core/qsettingsdialog.h
D:/felix/linked/Qworkplace/QSettingsDialog/QSettingsDialog/core/qsettingsdialog.dox

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Dialog structure

Settings Path

Member Function Documentation