Project Management

Overview Projects forms a vital part of most software packages. It allows the user to save the current state of an application to a file and later restore the state of the application from the saved state. Qtilities provides a library dedicated to project management which can easily be added to any Qt application. Table of contents: The structure of a Qtilities project First steps: Setting up the project manager Initializing and finalizing the project manager Registering project items in the project manager Project file type and versioning Projects in action: Using projects in your application Working with projects (creating, saving and loading) Project management options Adding other classes as project items

First Steps Getting Started The Basics Examples and Plugins Overviews Action Management Building Trees Debugging Applications Extension System Factories Logging Modules Object Management Observers Observer Widgets Project Management Tasking Widget Set

The structure of a Qtilities project

A project is a class which implements the Qtilities::ProjectManagement::Interfaces::IProject interface. Each project can consist of any number of project items. Project items are classes which implement the Qtilities::ProjectManagement::Interfaces::IProjectItem interface. The Qtilities::ProjectManagement::ProjectManager singleton is responsible to manage open projects. At present only one project can be open (active) at any time.

The diagram below shows this structure graphically.

Project Structure

First steps: Setting up the project manager

Initializing and finalizing the project manager

The project manager provides macros to initialize it on application startup and to finalize the manager when the application exists. During initialization the project manager will restore its settings from the previous session and load the last project if needed, or create a new project if needed. The finalization does the opposite: it saves the current settings and checks if the open project (if any) must be saved before exit. Lets look at the correct way to initialize and finalize the project manager:

#include <QtilitiesProjectManagement>
using namespace Qtilities::CoreGui;
using namespace Qtilities::ProjectManagement;

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

  // Add project items in the application to the project manager.

  // Initialize the project manager:
  PROJECT_MANAGER_INITIALIZE();

  // Register project management config page. If the configuration widget is used in the application this is needed, if not you can skip this line.
  OBJECT_MANAGER->registerObject(PROJECT_MANAGER->configWidget());

  int result = a.exec();
  PROJECT_MANAGER_FINALIZE();
  return results;
}

Registering project items in the project manager

Project items must be added to the project manager before initialization. When the project manager creates a new project it will attach all known project items to the project. The recommended way to do this is to register all your project items in the global object pool (see Object Management for more information on this topic) and then get all the project items once the application is stable (all plugins were initialized etc.). When using the Qtilities::Plugins::ProjectManagement plugin in the QtilitiesPlugins project this will be done automatically when the plugin initializes its dependencies. Alternatively when not using the plugin, PROJECT_MANAGER->refreshPartList() can be used to inspect the object pool.

Project file type and versioning

The project manager is able to save projects in either binary or XML formats where the suffices used for these different types can be set as follows:

PROJECT_MANAGER->setDefaultProjectType(IExportable::XML);
PROJECT_MANAGER->setAllowedProjectTypes(IExportable::XML);
// Lets say we want our project files to be save with the following extension: my_file.my_project_suffix
PROJECT_MANAGER->setProjectTypeSuffix(IExportable::XML,"my_project_suffix");

// Once the project type parameters were set, we can initialize the project manager.
PROJECT_MANAGER_INITIALIZE();

Qtilities make it easy to control different versions of project files since projects implement Qtilities::Core::Interfaces::IExportable which supports different versions of output formats. See the IExportable class documentation for a complete example of how the versioning implementation works.

Projects in action: Using projects in your application

Working with projects (creating, saving and loading)

The project manager can manage one open project at a time, accessible through Qtilities::ProjectManagement::ProjectManager::currentProject(). If no project is open, a new project can be created using Qtilities::ProjectManagement::ProjectManager::newProject(). This function can also be used to create a new project, thus closing and prompting to save the current project (if necessary) and creating a new project. If the current project must be closed without creating a new project call the Qtilities::ProjectManagement::ProjectManager::closeProject() function.

To open projects is straight forward. Below is an example of how the user can be prompted to open a project file:

QString filter = PROJECT_MANAGER->allowedProjectTypesFilter();
QString project_path;
if (PROJECT_MANAGER->useCustomProjectsPath())
    project_path = PROJECT_MANAGER->customProjectsPath();
else
    project_path = QCoreApplication::applicationDirPath() + tr("/Projects");
QString file_name = QFileDialog::getOpenFileName(0, tr("Open Existing Project"), project_path, filter);
if (file_name.isEmpty())
    return;

if (!PROJECT_MANAGER->isAllowedFileName(file_name))
    file_name.append("." + PROJECT_MANAGER->projectTypeSuffix(PROJECT_MANAGER->defaultProjectType()));

PROJECT_MANAGER->openProject(file_name);

The project manager contains functions to open saved projects and it keeps track of recent project paths and names. It also implements the Qtilities::Core::Interfaces::IModificationNotifier interface which can be used directly to control the modification state of the open project in the project manager.

Project management options

The project manager provides various options on how projects must be managed. See the Qtilities::ProjectManagement::ProjectManager class documentation for the access functions of these options. The screen shot below (taken from the ObjectManagementExample) shows the available settings in the project management configuration dialog:

Project Management Configuration Widget

Adding other classes as project items

The Qtilities::ProjectManagement::ObserverProjectItemWrapper class provides a wrapper which can be used to add an observer (tree) as a project item in your application. Below is an example which shows how to use this wrapper.

Observer* observerA = new Observer("Observer A","Example observer");
ObserverProjectItemWrapper* project_item = new ObserverProjectItemWrapper(this);
project_item->setObserverContext(observerA);
OBJECT_MANAGER->registerObject(project_item);

Qtilities::ProjectManagement::CodeEditorProjectItemWrapper as be used in a similar way to make any Qtilities::CoreGui::CodeEditorWidget part of a project.

The example project management plugin

In the QtilitiesExamples project there is a project management plugin which can be built against your application (this is necessary for the plugin to know which version of the application must be used during plugin compatibility checking). For more information see the Plugins Overview section of the Examples and Plugins page.