Qtilities::CoreGui::ConfigurationWidget Class Reference

Configuration widget which displays config pages from widgets implementing the Qtilities::CoreGui::Interfaces::IConfigPage interface. More...

#include <ConfigurationWidget.h>

List of all members.

Public Slots
IConfigPage *	activePageIFace () const
	Function to get the reference to the IConfig interface of the active page.
QString	activePageName () const
	Function to get the active page name and category.
void	handleActiveGroupedPageChanged (IConfigPage *new_active_grouped_page)
	Handles changes to active grouped pages.
void	handleActiveItemChanges (QList< QObject * > active_pages)
	Handles item changes in the page tree.
void	setActivePage (const QString &active_page_name)
	Function to set the active page.

Signals
void	appliedPage (IConfigPage *conig_page)
	Signal emitted whenever a config page is applied.

Public Member Functions
bool	applyAllPages () const
	Gets the way the configuration widget handles the Apply button.
bool	categorizedTabDisplay () const
	Gets if the configuration widget groups pages with the same categories under tabs in pages named using the name of the category.
IConfigPage *	getPage (const QString &page_name) const
	Checks if a configuration page with the given name exists and if so returns a pointer to the interface.
bool	hasPage (const QString &page_name) const
	Checks if a configuration page with the given name exists.
void	initialize (QList< IConfigPage * > config_pages, QList< IGroupedConfigPageInfoProvider * > grouped_page_info_providers)
	Initializes the config widget with the given set of config pages.
void	initialize (QList< QObject * > object_list=QList< QObject * >())
	Initializes the widget with a list of QObjects. All objects in the list which implements the IConfigPage interface will be added.
void	setApplyAllPages (bool apply_all_pages)
	Sets the way the configuration widget handles the Apply button.
void	setCategorizedTabDisplay (bool enabled=true)
	Sets if the configuration widget groups pages with the same categories under tabs in pages named using the name of the category.

---

Detailed Description

Configuration widget which displays config pages from widgets implementing the Qtilities::CoreGui::Interfaces::IConfigPage interface.

The configuration widget is a simple widget which can be used to display user settings in your applications. There are many such widgets available to Qt developers, and it is not very difficult to create a simple widget yourself. However, to do it properly takes time and doing it properly normally introduces bugs. Thus, the Qtilities configuration widget provides a ready to use, tested, extendable and configurable configuration widget solution.

ConfigurationWidget shows configuration pages that implements Qtilities::CoreGui::Interfaces::IConfigPage. To show pages in the configuration widget, register them in the global object pool and call initialize() on the configuration widget. The widget will find all configuration pages in the object pool. Parts of Qtilities provides ready to use configuration pages to use in your application. For example:

// The shortcuts editor for commands in your application:
OBJECT_MANAGER->registerObject(ACTION_MANAGER->commandEditor());

// Logging configuration page:
OBJECT_MANAGER->registerObject(LoggerGui::createLoggerConfigWidget());

// Extension system configuration page:
OBJECT_MANAGER->registerObject(EXTENSION_SYSTEM->configWidget());

// The project manager configuration page:
OBJECT_MANAGER->registerObject(PROJECT_MANAGER->configWidget());

To create your widget, add something like the following to your main.cpp code:

int main(int argc, char *argv[])
{
    QtilitiesApplication a(argc, argv);

    // Create a settings window for our application:
    ConfigurationWidget* config_widget = new ConfigurationWidget;
    QtilitiesApplication::setConfigWidget(config_widget);

    // ... Lots of application code ...
    // Initialize the widget as soon as all your pages are registered in the global object pool:
    config_widget->initialize();

It is now possible to access the configuration widget from anywhere in your application and perform actions on it:

if (QtilitiesApplication::configWidget()) {
    ConfigurationWidget* config_widget = qobject_cast<ConfigurationWidget*> (QtilitiesApplication::configWidget());
    if (config_widget) {
        // First call initialize on the config_widget to make sure it has all the pages available in the global object pool:
        config_widget->initialize();
        if (config_widget->hasPage(tr("My Page"))) {
            // We can get the interface to this page like this:
            IConfigWidget* config_widget_iface = config_widget->getPage("My Page");

            // Or we can show this page:
            config_widget->setActivePage(tr("Code Editors"));
            config_widget->show();
        }
    }
}

Below is an example of the configuartion widget taken from the Object Management Example in the QtilitiesExamples project:

Project Configuration Widget

It is possible to either show the configuration pages as a list as shown above, or it can be shown as a categorized tree by using the correct Qtilities::DisplayMode in the constructor. This allows your pages to provide a Qtilities::Core::QtilitiesCategory to use in the categorized tree through the IConfigPage interface.

See also:

Qtilities::CoreGui::Interfaces::IConfigPage

Configuration settings storage in Qtilities

Throughout Qtilities classes store settings using QSettings using the QSettings::IniFormat.

The construction of the QSettings object is done as follows everywhere that settings are saved. This example saves settings of a specific ObserverWidget:

QSettings settings(QtilitiesCoreApplication::qtilitiesSettingsPath(),QSettings::IniFormat);
settings.beginGroup("Qtilities");
settings.beginGroup("GUI");
settings.beginGroup(d->global_meta_type);
// .... Stores some ObserverWidget stuff ...
settings.endGroup();
settings.endGroup();
settings.endGroup();

An important difference is that the Logger modulde does not depend on the Core module, thus it does not have access to QtilitiesCoreApplication. However the logger stores the session path it uses as well (see Qtilities::Logging::Logger::setLoggerSessionConfigPath()) and it will save its settings under that path in a file called qtilities.ini which by default points to the same files as the rest of Qtilities. If you however changes the session path used by your application through QtilitiesCoreApplication::setApplicationSessionPath(), the Logger will automatically be updated to use the same settings path, thus your settings will all be saved in the same ini file accross all Qtilities modules. The same counts for disabling settings using QtilitiesCoreApplication::setQtilitiesSettingsEnabled().

For more information see the Qtilities::Core::QtilitiesCoreApplication::qtilitiesSettingsPath() documentation.

---

Member Function Documentation

bool Qtilities::CoreGui::ConfigurationWidget::categorizedTabDisplay

(

)

const

Gets if the configuration widget groups pages with the same categories under tabs in pages named using the name of the category.

See also:

setCategorizedTabDisplay()

This function was introduced in Qtilities v1.1.

void Qtilities::CoreGui::ConfigurationWidget::initialize

(

QList< QObject * >

object_list = QList<QObject*>()

)

Initializes the widget with a list of QObjects. All objects in the list which implements the IConfigPage interface will be added.

You can initialize the ConfigurationWidget multiple times and when called more than once it will just rescan the global object pool.

Parameters:

object_list

Explicitly specified the list of config pages and grouped config page info providers that must be shown in this widget.

Note:

If the list is empty, the function will search the global object pool and automatically add all found config pages and grouped config page info providers. Debug messages with information about the found items will be logged.

void Qtilities::CoreGui::ConfigurationWidget::setApplyAllPages

(

bool

apply_all_pages

)

Sets the way the configuration widget handles the Apply button.

Parameters:

apply_all_pages

When true, the apply button will call apply on all the configuration pages. When false, only the active page will be applied.

Default is true;

void Qtilities::CoreGui::ConfigurationWidget::setCategorizedTabDisplay

(

bool

enabled = true

)

Sets if the configuration widget groups pages with the same categories under tabs in pages named using the name of the category.

False by default.

Note:

You must call this function before initialize().

See also:

categorizedTabDisplay();

This function was introduced in Qtilities v1.1.