Overview

The goal of this article is to introduce Qtilities to someone who has never used it before. Basic principles will be covered and a basic example is presented which demonstrates many features and concepts. This article is not intended to give an overview of the different modules, for that see Modules Overview.

Table of contents:

First Steps

Overviews

Constructing your QApplication object

A Qtilities application is just a normal Qt application with one small difference. The recommended way to construct your QApplication object is to use Qtilities::CoreGui::QtilitiesApplication which initializes some internal Qtilities features, and extends QApplication. Thus it would look something like this:

QtilitiesApplication a(argc, argv);
// If you use a different class that inherits from QApplication and it is not possible to use QtilitiesApplication as shown above, it should be initialized directly after QApplication construction, as follows:
QApplication a(argc, argv);
QtilitiesApplication::initialize();

This is the only difference between a Qtilities application and a normal Qt application. If you don't use any GUI related classes, you can keep using QCoreApplication without the need to do anything different.

Macros made available to you

When using Qtilities you have access to a set of macros. The table below provides an overview of the most important ones:

Object Manager

Context Manager

Action Manager

Logging

The OBJECT_MANAGER macro provides object management functionality in your application. The most important feature is the global object pool in which objects can be registered either by the main application, or by plugins. For more information about the object manager see the the Object Management article.

The CONTEXT_MANAGER macro allows management of contexts in an application. For more information about the context manager see the The Context Manager section of the Action Management article.

The ACTION_MANAGER macro allows management of actions, shortcuts and menu related items in an application. For more information about the action manager see the The Action Manager section of the Action Management article.

A set of logging macros are available, for more information see Logging.

Includes and namespaces

In your .pro file you need to define the Qtilities module you would like to use in your application. This will include all the needed header files and link your application to the correct libraries. The exact details to use for the different modules are provided in the Modules Overview article. Note that all dependent Qtilities modules will be added automatically for you and details about the used dependencies are printed as output during compilation.

// In your .pro file:
QTILITIES += coregui
QTILITIES_BASE  = your_path/qtilities/trunk
include($$QTILITIES_BASE/src/Qtilities.pri)

For the above example we set the QTILITIES variable to coregui indicating that we are using the CoreGui module, and the following will be printed during compilation:

Project MESSAGE: Using Qtilities CoreGui module...
Project MESSAGE: CoreGui Dependency: Using Qtilities Logging module...
Project MESSAGE: CoreGui Dependency: Using Qtilities Core module...

In the source files where you want to use Qtilities you need to include the name of the module and then specify the namespaces we want to use. All the required namespaces of all the dependent modules will be made available through automatically. For example:

// In your source files:
#include <QtilitiesCoreGui>
using namespace QtilitiesCoreGui;

A basic example application

Next we will look at a basic example which you can build and play around with. The example will not do a lot but it introduces many features and concepts. To run this example, launch the TheBasicsExample application in the QtilitiesExample project.

#include <QtGui>
#include <QtilitiesCoreGui>
using namespace QtilitiesCoreGui;
int main(int argc, char *argv[])
{
    QtilitiesApplication a(argc, argv);
    QtilitiesApplication::setOrganizationName("Jaco Naudé");
    QtilitiesApplication::setOrganizationDomain("Qtilities");
    QtilitiesApplication::setApplicationName("Simple Example");
    QtilitiesApplication::setApplicationVersion("1.0");
    // Create a main window for our application:
    QMainWindow* main_window = new QMainWindow;
    QtilitiesApplication::setMainWindow(main_window);
    // Create a settings window for our application:
    ConfigurationWidget* config_widget = new ConfigurationWidget;
    QtilitiesApplication::setConfigWidget(config_widget);
    // Initialize the application session path in QtilitiesCoreApplication.
    QtilitiesApplication::applicationSessionPath();
    // Initialize the logger:
    LOG_INITIALIZE();
    // Add a menu bar to our main window with a File menu:
    bool existed;
    ActionContainer* menu_bar = ACTION_MANAGER->createMenuBar(qti_action_MENUBAR_STANDARD,existed);
    main_window->setMenuBar(menu_bar->menuBar());
    ActionContainer* file_menu = ACTION_MANAGER->createMenu(qti_action_FILE,existed);
    menu_bar->addMenu(file_menu);
    // Our menu items will need to be associated with a context.
    // A good idea is to use the standard context which is always active:
    QList<int> std_context;
    std_context.push_front(CONTEXT_MANAGER->contextID(qti_def_CONTEXT_STANDARD));
    // Create File->Settings and File->Exit menu items:
    Command* command = ACTION_MANAGER->registerActionPlaceHolder(qti_action_FILE_SETTINGS,QObject::tr("Settings"),QKeySequence(),std_context);
    QObject::connect(command->action(),SIGNAL(triggered()),config_widget,SLOT(show()));
    file_menu->addAction(command);
    file_menu->addSeperator();
    command = ACTION_MANAGER->registerActionPlaceHolder(qti_action_FILE_EXIT,QObject::tr("Exit"),QKeySequence(QKeySequence::Close),std_context);
    QObject::connect(command->action(),SIGNAL(triggered()),QCoreApplication::instance(),SLOT(quit()));
    file_menu->addAction(command);
    // Lets add a couple of pages to our setting page which handles shortcuts and logging in our application:
    OBJECT_MANAGER->registerObject(ACTION_MANAGER->commandEditor());
    OBJECT_MANAGER->registerObject(LoggerGui::createLoggerConfigWidget());
    // Initializing the configuration widget will search the global object pool for objects implementing IConfigPage, and automatically add them:
    config_widget->initialize();
    // Now build an example tree which will tell all views to provide some actions for the tree items:
    TreeNode* node = new TreeNode("Root Node");
    node->displayHints()->setActionHints(ObserverHints::ActionAllHints);
    node->displayHints()->setDisplayFlagsHint(ObserverHints::AllDisplayFlagHint);
    TreeNode* nodeA = node->addNode("Node A");
    nodeA->displayHints()->setActionHints(ObserverHints::ActionAllHints);
    nodeA->displayHints()->setDisplayFlagsHint(ObserverHints::AllDisplayFlagHint);
    nodeA->addItem("Item 1");
    nodeA->addItem("Item 2");
    TreeItem* sharedItem = nodeA->addItem("Shared Item");
    TreeNode* nodeB = node->addNode("Node B");
    nodeB->displayHints()->setActionHints(ObserverHints::ActionPushUp | ObserverHints::ActionSwitchView);
    nodeB->displayHints()->setDisplayFlagsHint(ObserverHints::ItemView | ObserverHints::ActionToolBar);
    nodeB->attachSubject(sharedItem);
    nodeB->addItem("Item 3");
    nodeB->addItem("Item 4");
    // Notice we added different display hints on Node B, it will behave different.
    // We show the tree using an ObserverWidget:
    ObserverWidget* tree_widget = new ObserverWidget(node);
    tree_widget->show();
    // Finally, set the ObserverWidget as the main window's central widget and show it:
    main_window->setCentralWidget(tree_widget);
    main_window->show();
    return a.exec();
}

This example introduced some of the core concepts in Qtilities and most of the other features uses these concepts in one way or another. For example, the Qtilities::CoreGui::ObserverWidget object in the above example automatically adds its actions to the action manager and registers their its own contexts in the context manager for these actions.

Now that the basics are covered check out the Examples and Plugins and take a look at some of the articles which provides in depth overviews of feature areas found in Qtilities at the top of this page.

If you run into something that does not make sense, post a question on the mailing list.