A general class to modifiy the appereance of elements of a settings dialog. More...

#include <qsettingslayout.h>

Public Types
enum	LayoutType { DialogLayout, CategoryLayout, SectionLayout, GroupLayout, EntryLayout }
	Defines the different elements a layout can be created for. More...

Public Member Functions
	QSettingsLayout (QSettingsDialog *settingsDialog, bool fromCurrentContainer=false)
	Creates a new layout for the given dialogs root element or current container. More...

	QSettingsLayout (QSettingsDialog *settingsDialog, const QString &containerPath, int entryId=-1)
	Creates a new layout for the given container in the dialog or an entry within that container. More...

	QSettingsLayout (QSettingsContainer *container)
	Creates a new layout from the given container.

QString	id () const
	Returns the container id of the current container. More...

LayoutType	layoutType () const
	Returns the element type this layout represents. More...

bool	isNull () const
	Returns whether this layout is a null-layout (does not represent anything) More...

QSettingsDialog *	dialog () const
	Returns the dialog this layout belongs to. More...

QString	containerPath () const
	Returns the full container path of the element. More...

QSettingsLayout	parentContainer () const
	Returns the parent container element, if available. More...

int	displayId () const
	Gets the elements display id. More...

void	setDisplayId (int displayId)
	Sets the elements display id. More...

QString	name () const
	Gets the elements name. More...

void	setName (const QString &name)
	Sets the elements name. More...

QIcon	icon () const
	Gets the elements icon. More...

void	setIcon (const QIcon &icon)
	Sets the elements icon. More...

QString	tooltip () const
	Gets the elements tooltip. More...

void	setTooltip (const QString &tooltip)
	Sets the elements tooltip. More...

bool	isOptional () const
	Gets whether the element is optional or not. More...

void	setOptional (bool optional)
	Sets whether the element is optional or not. More...

QSettingsLayout	defaultElement (bool allowCreateNew=false) const
	Returns the elements default child element. More...

bool	removeDefaultElement ()
	Removes the default element, if it exists. More...

int	elementCount () const
	Returns the number of children this element has. More...

QSettingsLayout	elementAt (int index) const
	Gets the child element at the given position. More...

int	indexOfElement (const QSettingsLayout &element) const
	Gets the child index of the given element within this element. More...

int	indexOfElement (const QString &elementName) const
	Gets the child index of the given element by name within this element. More...

QSettingsLayout	createElement (int index, const QString &id, const QString &name=QString(), const QIcon &icon=QIcon(), const QString &tooltip=QString())
	Creates a new child element at the given index. More...

QSettingsLayout	createGroupElement (int index, const QString &id, int displayId=0, const QString &name=QString(), bool optional=false, const QString &tooltip=QString())
	Creates a new optional child element at the given index. More...

void	removeElement (int index)
	Removes the child element at the given index. More...

void	moveElement (int indexFrom, int indexTo)
	Moves the child from one index to a new one. More...

void	transferElement (int indexFrom, QSettingsLayout targetLayout, int indexTo)
	Transfers a child from this layout to the given target. More...

Friends
class	SettingsEntryLayout

class	SettingsGroupLayout

class	SettingsSectionLayout

class	SettingsCategoryLayout

class	SettingsRootLayout

Detailed Description

A general class to modifiy the appereance of elements of a settings dialog.

Layouts can be created for any element within the dialog (see QSettingsLayout::LayoutType). The layout itself is a generalized class that provides a bunch of functions to modify those elements, focused on their appereance and the organization of their child elements.

Warning: Even though the layout is generalized, not all elements in the dialog support the same properties and methods. For example, QSettingsLayout::setOptional is defined for group and entry elements, but not for the rest. If you are trying to access a property that is not defined for current type, a LayoutPropertyNotDefinedException will be thrown. Check the documentation of each method to see which layout types support it

The layouts themselves are value-classes that can be copied without hesitation, because they are mere wrappers around the internal data structures. This makes the use of them easy and simple. Even if you have multiple copies of one layout, if one is changed, all will see this change, because all of them are internally using the same data

Warning: Even though it's a value type class, the layout is bound to it's dialog. If the dialog gets delete while the layout is accessing it, the layout will still work for some options, but others will create crashes. Make shure to not destroy the dialog while a layout is used. They are ment as short-time-wrappers.

Note: All changes made with the layouts will not affect running dialogs.

Member Enumeration Documentation

enum QSettingsLayout::LayoutType

Defines the different elements a layout can be created for.

Enumerator
DialogLayout	The layout represents the dialog itself.
CategoryLayout	The layout represents a category.
SectionLayout	The layout represents a section.
GroupLayout	The layout represents a group.
EntryLayout	The layout represents an entry.

Constructor & Destructor Documentation

QSettingsLayout::QSettingsLayout	(	QSettingsDialog *	settingsDialog,
		bool	fromCurrentContainer = `false`
	)

explicit

Creates a new layout for the given dialogs root element or current container.

Parameters

settingsDialog	The dialog to create the layout for
fromCurrentContainer	`true`, to use the current container, `false` to create a root layout

If fromCurrentContainer is false (the default), a LayoutType::DialogLayout will be created from the dialog itself. If it is true, the dialogs current container path (QSettingsDialog::containerPath) will be used.

QSettingsLayout::QSettingsLayout	(	QSettingsDialog *	settingsDialog,
		const QString &	containerPath,
		int	entryId = `-1`
	)

explicit

Creates a new layout for the given container in the dialog or an entry within that container.

Parameters

settingsDialog	The dialog to create the layout for
containerPath	The path to create the layout for
entryId	The id of the entry within the container, or -1, if the path container should be used

If entryId is < 0, a container for the given path will be created. An empty path will create a LayoutType::DialogLayout. If the path has 1 element, it will be QSettingsLayout::CategoryLayout, a QSettingsLayout::SectionLayout for 2 and a QSettingsLayout::GroupLayout for 3. If you have a section or group path, and id is 0 or greater, the entry with the given id inside the specified path will be used.

Note: If the path or does not exists or no entry with the given id is insed of the path container, the newly created layout will be a null layout. Use QSettingsLayout::isNull to check this.

Member Function Documentation

QSettingsLayout::containerPath ( ) const

Returns the full container path of the element.

Returns: The container path

For categories, this is just the id. For sections and groups, this will be a 2 or three element path.

Note: If the layout is a QSettingsLayout::EntryLayout, the elements container path (section or group) combined with the hashed id will be returned. Example: The element with id 42 inside the default category and a section called "Baum". The returned path would be: ./Baum/#42. Please note that this is not a valid container path, just a representation of container and id.

Supported Layout Types
Supported for all layout types

QSettingsLayout::createElement	(	int	index,
		const QString &	id,
		const QString &	name = `QString()`,
		const QIcon &	icon = `QIcon()`,
		const QString &	tooltip = `QString()`
	)

Creates a new child element at the given index.

Parameters

index	The index to insert the item at
id	The id the new element should have
name	The display name the element should have
icon	The display icon for the element
tooltip	The tooltip for the new element

Returns: A layout reference to the newly created element

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

If an element with that id does already exist, it will be deleted and overwritten. To avoid this, check for children beforehand. If name is left as a null string, the id will be used as name. If index is not a valid index, the function will assert.

For group elements, use QSettingsLayout::createGroupElement.

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::createGroupElement	(	int	index,
		const QString &	id,
		int	displayId = `0`,
		const QString &	name = `QString()`,
		bool	optional = `false`,
		const QString &	tooltip = `QString()`
	)

Creates a new optional child element at the given index.

Parameters

index	The index to insert the item at
id	The id the new element should have
displayId	The displayId the new element should have
name	The display name the element should have
optional	Specifies whether the element should be optional or not
tooltip	The tooltip for the new element

Returns: A layout reference to the newly created element

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

If an element with that id does already exist, it will be deleted and overwritten. To avoid this, check for children beforehand. If name is left as a null string, the id will be used as name. If index is not a valid index, the function will assert.

For other elements, use QSettingsLayout::createElement.

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::defaultElement ( bool allowCreateNew = false ) const

Returns the elements default child element.

Parameters

allowCreateNew Specifies whether it's allowed to create the default element if it does not exist

Returns: The default element within this element

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

If the default element does not yet exist, allowCreateNew can be used to create it. If it is not created, a null layout will be returned (See QSettingsLayout::isNull)

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::dialog ( ) const

Returns the dialog this layout belongs to.

Returns: The dialog this layout manages

If the dialog was destroyed while this layout is still alive, this function will return nullptr. It is save to destroy a layout even after the dialog was deleted.

Supported Layout Types
Supported for all layout types

QSettingsLayout::displayId ( ) const

Gets the elements display id.

Returns: The current display id of the element

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::elementAt ( int index ) const

Gets the child element at the given position.

Parameters

index The index of the desired child element

Returns: A layout reference to the element at the given index

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

If index is not a valid index, the function will assert.

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::elementCount ( ) const

Returns the number of children this element has.

Returns: The number of child elements within this element

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::icon ( ) const

Gets the elements icon.

Returns: The current icon of the element

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::id ( ) const

Returns the container id of the current container.

Returns: The id of the element this layout manages

Will return the container id of the element this layout represents. For LayoutType::DialogLayout this will always be an emtpy string, and for LayoutType::EntryLayout, the entry id (an integer) prepended by # will be returned. E.g. #42 for an entry with the id 42

Supported Layout Types
Supported for all layout types

QSettingsLayout::indexOfElement ( const QSettingsLayout & element ) const

Gets the child index of the given element within this element.

Parameters

element The element to be found within this layout

Returns: The index of the child within this layout, or -1 if it was not found

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::indexOfElement ( const QString & elementName ) const

Gets the child index of the given element by name within this element.

Parameters

elementName The name of the element to be found within this layout

Returns: The index of the child within this layout, or -1 if it was not found

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::isNull ( ) const

Returns whether this layout is a null-layout (does not represent anything)

Returns: true, if this element is a null element, false if not

Null layouts can happen if you try to create a layout for a container path that does not exist

Supported Layout Types
Supported for all layout types

QSettingsLayout::isOptional ( ) const

Gets whether the element is optional or not.

Returns: true, if the element is optional, false if not

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::layoutType ( ) const

Returns the element type this layout represents.

Returns: The LayoutType this layout is

Supported Layout Types
Supported for all layout types

QSettingsLayout::moveElement	(	int	indexFrom,
		int	indexTo
	)

Moves the child from one index to a new one.

Parameters

indexFrom	The index of the child element to be moved
indexTo	The index to move the element to

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

If one of the indexes is not a valid index, the function will assert.

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::name ( ) const

Gets the elements name.

Returns: The current name of the element

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::parentContainer ( ) const

Returns the parent container element, if available.

Returns: The parent layout, or a "null" layout, if the layout is without a parent

The parent container will only be available, if this layout was originally created from a parent layout. In other words, a layout created from a constructor it will always return a null layout. If you created it from a parent, for example by using QSettingsLayout::elementAt, it will return the element it was created from.

Attention: always check if the parent is valid by using QSettingsLayout::isNull!

Supported Layout Types
Supported for all layout types

QSettingsLayout::removeDefaultElement ( )

Removes the default element, if it exists.

Returns: true, if the default group was removed, false if none exists

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

If the default element does exist, it will be removed. If does not currently exist, nothing happens

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::removeElement ( int index )

Removes the child element at the given index.

Parameters

index The index of the child element to be removed

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

If index is not a valid index, the function will assert.

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::setDisplayId ( int displayId )

Sets the elements display id.

Parameters

displayId The id to be set as new display id

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::setIcon ( const QIcon & icon )

Sets the elements icon.

Parameters

icon	The icon to be set as new icon

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::setName ( const QString & name )

Sets the elements name.

Parameters

name	The name to be set as new name

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::setOptional ( bool optional )

Sets whether the element is optional or not.

Parameters

optional The value that optional should be set to

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::setTooltip ( const QString & tooltip )

Sets the elements tooltip.

Parameters

tooltip The tooltip to be set as new tooltip

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::tooltip ( ) const

Gets the elements tooltip.

Returns: The current tooltip of the element

Exceptions

LayoutPropertyNotDefinedException Will be thrown if called on a layout with an unsupported type

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

QSettingsLayout::transferElement	(	int	indexFrom,
		QSettingsLayout	targetLayout,
		int	indexTo
	)

Transfers a child from this layout to the given target.

Parameters

indexFrom	The index of the child element to be moved
targetLayout	The layout to move the element to
indexTo	The index to move the element to

Exceptions

LayoutPropertyNotDefinedException	Will be thrown if called on a layout with an unsupported type
InvalidTargetLayoutException	Will the thrown if the target layout is of a different layout type

If one of the indexes is not a valid index, the function will assert. To move entries from layouts to groups and the other way around, please use QSettingsContainer classes.

Note: This function will not include the default element.

Supported Layout Types
QSettingsLayout::DialogLayout
QSettingsLayout::CategoryLayout
QSettingsLayout::SectionLayout
QSettingsLayout::GroupLayout
QSettingsLayout::EntryLayout

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

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

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation