C++ API Reference

This reference is generated from the Doxygen comments in the C++ headers and source files during the Read the Docs build.

Core Model

class ConfiguredProject

Owns the persisted project model and configuration item tree.

ConfiguredProject stores project metadata, the root ConfiguredItem hierarchy, JSON persistence, duplicate parameter checks, dirty-state clearing, and exporter-friendly parameter collection.

Public Functions

ConfiguredProject()

Creates an empty project with a root system item.

ConfiguredItem *root()

Returns the mutable root item of the configuration hierarchy.

const ConfiguredItem *root() const

Returns the read-only root item of the configuration hierarchy.

void createSampleProject()

Replaces the current tree with a representative sample robotics project.

bool saveToFile(const QString &filePath, QString *error = nullptr)

Save the project as a .configured JSON document.

Parameters:

• filePath – Destination file path.

• error – Optional error output populated on failure.

Returns:

true when the file was written successfully.

bool loadFromFile(const QString &filePath, QString *error = nullptr)

Load project metadata and items from a .configured JSON document.

Parameters:

• filePath – Source file path.

• error – Optional error output populated on failure.

Returns:

true when the file was read and parsed successfully.

bool hasDuplicateParameterKeys(QString *duplicateKey = nullptr) const

Check whether two or more parameters share the same key.

Parameters:

duplicateKey – Optional output containing the first duplicate key found.

Returns:

true if at least one duplicate parameter key exists.

std::vector<ExportParameter> collectParameters() const

Flatten the item tree into exportable parameters.

Returns:

Parameters with hierarchy path, type, key, value, and unit.

void clearDirtyFlags()

Clear dirty visual state flags across the full item tree.

struct ProjectMetadata

Editable project-level metadata shown in the new/open project dialogs.

ProjectMetadata is a transfer object used by UI dialogs and services before values are applied to a ConfiguredProject. Keeping it separate from the project model makes validation and metadata updates explicit.

Public Members

QString name

Human-readable project name. Also used to derive default project filenames.

QString description

Optional project description shown in metadata dialogs and exported files.

QString author

Optional author name for project ownership/audit metadata.

QString company

Optional company or organization name.

QString version

User-facing project version string.

QString robotPlatform

Robot, vehicle, or platform this configuration targets.

bool gitManaged = false

True when the project should be initialized and managed as a Git repository.

QString lastModified

Last modified timestamp stored in the project file.

QString gitCommitHash

Commit hash associated with the saved project state, when available.

struct ProjectCreationResult

Result returned after creating a project on disk.

Public Members

bool success = false

True when the project folder, project file, and optional Git setup succeeded.

QString errorMessage

User-facing failure details when success is false.

QString projectFilePath

Full path to the created .configured project file.

std::unique_ptr<ConfiguredProject> project

Newly created project instance ready to show in the editor.

class ProjectService

Coordinates project file operations and optional Git repository setup. ProjectService is the application-level boundary around creating, loading, saving, and updating ConfiguredProject instances. It delegates Git-specific work to GitService when a project is marked as Git-managed.

Public Functions

explicit ProjectService(GitService *gitService)

Create a service.

Parameters:

gitService – Optional Git service used for repository initialization.

ProjectCreationResult createProject(const ProjectMetadata &metadata, const QString &baseFolder) const

Create a new project folder and .configured file.

Parameters:

• metadata – Metadata to apply to the new project.

• baseFolder – Parent folder where the project folder will be created.

Returns:

Creation result containing either the project or an error message.

bool updateProjectMetadata(ConfiguredProject &project, const ProjectMetadata &metadata, const QString &projectFilePath, QString &error) const

Apply metadata changes and save the project file.

Parameters:

• project – Project to update.

• metadata – New metadata values.

• projectFilePath – Existing project file path.

• error – User-facing error populated on failure.

Returns:

true when metadata was applied and saved.

bool ensureGitInitialized(const QString &repoDir, QString &error) const

Ensure a directory is initialized as a Git repository.

Parameters:

• repoDir – Working directory to initialize.

• error – User-facing error populated on failure.

Returns:

true when the directory is already a repository or was initialized.

bool saveProject(ConfiguredProject &project, const QString &projectFilePath, QString &error) const

Save an existing project to disk.

Parameters:

• project – Project model to persist.

• projectFilePath – Destination .configured file path.

• error – User-facing error populated on failure.

Returns:

true when the project file was written.

std::unique_ptr<ConfiguredProject> loadProject(const QString &projectFilePath, QString &error) const

Load a project from disk.

Parameters:

• projectFilePath – Source .configured file path.

• error – User-facing error populated on failure.

Returns:

Loaded project, or nullptr on failure.

ProjectSaveAsResult saveProjectAs(ConfiguredProject &project, const QString &baseDirectory) const

Save a standalone copy of a project inside its own project folder.

Parameters:

• project – Project model to copy.

• baseDirectory – Parent folder where the project folder will be created.

Returns:

Save As result containing either the copied file path or an error message.

Git Workflows

class GitWorkflowController : public QObject

Handles user-facing Git workflows for the active project.

The controller keeps Git dialogs and application actions out of MainWindow. It owns no project data; instead it receives a ProjectContext that points at the currently loaded project and emits signals when the UI should refresh.

Public Functions

explicit GitWorkflowController(GitService *gitService, ProjectService *projectService, QWidget *dialogParent = nullptr, QObject *parent = nullptr)

Create a Git workflow controller.

Parameters:

• gitService – Service used to execute Git commands.

• projectService – Service used to save/reload projects around Git actions.

• dialogParent – Parent widget for modal dialogs.

• parent – QObject parent.

void setDialogParent(QWidget *dialogParent)

Update the parent widget used for dialogs created by this controller.

void setProjectContext(const ProjectContext &context)

Replace the active project context used by future Git actions.

void showGitStatus()

Show a read-only Git status dialog for the active repository.

void promptAndCommit()

Prompt for a commit message and commit project/repository changes.

void promptAndPull()

Run pull preflight checks, then pull remote changes if the user proceeds.

void promptAndPush()

Push the current branch, prompting for upstream setup when needed.

void promptAndConnectRemote()

Prompt for a remote URL and connect or clone a repository.

void promptAndSwitchBranch()

Prompt for a target branch and switch the active repository.

void runNewProjectGitOnboarding()

Launch the first-run Git setup wizard for newly created projects.

Signals

void reloadProjectRequested(const QString &projectFilePath)

Emitted when Git changed files and the project should be reloaded from disk.

void gitStateChanged()

Emitted after an action that may change branch, dirty state, or upstream state.

void informationRequested(const QString &title, const QString &message)

Request that the host UI show an informational message.

void warningRequested(const QString &title, const QString &message)

Request that the host UI show a warning message.

struct ProjectContext

Runtime project state required to run Git actions.

Public Members

ConfiguredProject *project = nullptr

Active project model, or nullptr when no project is open.

QString projectFilePath

Path to the active .configured file.

bool *hasUnsavedChanges = nullptr

Pointer to MainWindow’s unsaved-change flag so save/pull decisions stay current.

class StatusBarController : public QObject

Keeps the editor status bar synchronized with project and Git state.

Public Functions

explicit StatusBarController(GitService *gitService, QObject *parent = nullptr)

Create a status bar controller.

Parameters:

• gitService – Service used to query repository state.

• parent – QObject parent.

void setContext(const Context &context)

Replace the state used by the next refresh.

void setWidgets(const Widgets &widgets)

Register the status bar widgets to update.

void refresh()

Refresh all status bar fields from project and repository state.

void clear()

Clear status text and hide repository-only controls.

struct Context

Current editor/project state used to decide what should be shown.

Public Members

ConfiguredProject *project = nullptr

Active project, or nullptr when no project is loaded.

QString projectFilePath

Path to the active .configured file.

bool hasUnsavedChanges = false

True when the editor has unsaved changes.

bool editorVisible = false

True when the editor screen is currently visible.

struct Widgets

Widgets owned by MainWindow and updated by this controller.

Public Members

QStatusBar *statusBar = nullptr

Status bar that contains the labels and refresh control.

QLabel *remoteUrlLabel = nullptr

Label showing the configured remote URL.

QLabel *branchLabel = nullptr

Label showing the current Git branch.

QLabel *dirtyLabel = nullptr

Label showing whether the project has unsaved editor changes.

QLabel *commitLabel = nullptr

Label showing whether commits are ahead of the upstream branch.

QWidget *refreshButton = nullptr

Refresh control shown when editor status is available.

class CloneWorker : public QObject

Runs git clone asynchronously and streams process output.

CloneWorker is designed to live on a worker thread. Call start() from that thread and listen for finished() to move back to the UI workflow.

Public Functions

explicit CloneWorker(const QString &remoteUrl, const QString &parentFolder)

Create a clone worker.

Parameters:

• remoteUrl – Repository URL to clone.

• parentFolder – Destination parent folder.

Public Slots

void start()

Start the clone process.

void cancel()

Request cancellation of the running clone process.

Signals

void outputReceived(const QString output)

Emitted whenever git writes output to stdout or stderr.

void finished(bool success, const QString &clonedPath, const QString &output)

Emitted once the clone process exits.

Parameters:

• success – true when git clone completed successfully.

• clonedPath – Best-effort path to the cloned repository.

• output – Full captured process output.

class GitPullWorker : public QObject

Runs git pull asynchronously and streams process output.

Public Functions

explicit GitPullWorker(const QString &workingDir)

Create a pull worker for a repository.

Parameters:

workingDir – Repository working directory.

Public Slots

void start()

Start the pull process.

void cancel()

Request cancellation of the running pull process.

Signals

void outputReceived(const QString output)

Emitted whenever git writes output to stdout or stderr.

void finished(bool success, const QString &output)

Emitted once the pull process exits.

Parameters:

• success – true when git pull completed successfully.

• output – Full captured process output.

class GitPushWorker : public QObject

Runs git push asynchronously and streams process output.

Public Functions

explicit GitPushWorker(const QString &workingDir, bool setUpstream, const QString &branchName)

Create a push worker for a repository.

Parameters:

• workingDir – Repository working directory.

• setUpstream – true to push with upstream tracking for branchName.

• branchName – Current branch name used when setting upstream.

Public Slots

void start()

Start the push process.

void cancel()

Request cancellation of the running push process.

Signals

void outputReceived(const QString output)

Emitted whenever git writes output to stdout or stderr.

void finished(bool success, const QString &output)

Emitted once the push process exits.

Parameters:

• success – true when git push completed successfully.

• output – Full captured process output.

Exporters

struct ExportParameter

Flattened parameter record used by project exporters.

Public Members

QString path

Hierarchical path to the parameter within the project tree.

QString type

Configured item/value type associated with the parameter.

QString value

Stored parameter value as text.

QString unit

Optional engineering unit.

QString key

Unique parameter key used by downstream systems.

class JsonProjectExporter

Writes project parameters to a JSON export document.

Public Functions

bool exportParameters(const ConfiguredProject &project, const QString &filePath, QString *errorMessage = nullptr) const

Export collected project parameters to JSON.

Parameters:

• project – Source project.

• filePath – Destination JSON file path.

• errorMessage – Optional error output populated on failure.

Returns:

true when the export file was written.

class XmlProjectExporter

Writes project parameters to an XML export document.

Public Functions

bool exportParameters(const ConfiguredProject &project, const QString &filePath, QString *errorMessage = nullptr) const

Export collected project parameters to XML.

Parameters:

• project – Source project.

• filePath – Destination XML file path.

• errorMessage – Optional error output populated on failure.

Returns:

true when the export file was written.

Validation

class ProjectValidator

Runs whole-project validation across metadata and item hierarchy.

Public Functions

ValidationResult validate(const ConfiguredProject &project) const

Validate a project and all configuration items.

Parameters:

project – Project to validate.

Returns:

Validation messages collected from project and item validators.

UI Dialogs

class NewProjectGitWizard : public QWizard

Wizard for configuring Git immediately after creating a project.

The wizard captures identity, initial commit, remote, and push preferences. GitWorkflowController reads the final State and performs the requested work.

Public Functions

explicit NewProjectGitWizard(const QString &workingDir, GitService *service, QWidget *parent = nullptr)

Create the onboarding wizard.

Parameters:

• workingDir – Project repository directory.

• service – Git service used to prefill existing identity/branch state.

• parent – Parent widget.

State state() const

Return the final wizard state after the dialog is accepted.

struct State

Collected onboarding choices.

Public Members

QString workingDir

Repository/project working directory.

QString branchName

Current branch name shown in the wizard.

QString userName

Git user.name value to apply locally or globally.

QString userEmail

Git user.email value to apply locally or globally.

bool useGlobalIdentity = false

True when identity should be written to the user’s global Git config.

bool createInitialCommit = true

True when the wizard should create the first commit.

QString commitMessage = "Initial configured project"

Commit message used for the initial commit.

bool connectRemote = false

True when a remote should be configured.

QString remoteName = "origin"

Remote name, usually origin.

QString remoteUrl

Remote repository URL.

bool pushAfterSetup = false

True when the current branch should be pushed after setup.

class PullPreflightDialog : public QDialog

Dialog shown before pulling when local work may need attention.

Public Types

enum class Decision

User decision selected from the preflight dialog.

Values:

enumerator SaveProject

enumerator CommitChanges

enumerator Cancel

Public Functions

explicit PullPreflightDialog(const State &state, QWidget *parent = nullptr)

Create the dialog for the current pull preflight state.

Decision decision() const

Return the decision selected by the user.

struct State

Repository and editor state shown in the preflight dialog.

Public Members

bool hasUnsavedEditorChanges = false

True when the editor has changes that are not saved to the project file.

bool hasUncommittedGitChanges = false

True when the Git working tree has uncommitted changes.

bool hasUnpushedCommits = false

True when local commits have not been pushed upstream.

QString branchName

Current local branch name.

QString upstreamName

Upstream branch name, if one is configured.

class RemoteConnectDialog : public QDialog

Dialog that collects clone/connect details for a remote repository.

Public Functions

explicit RemoteConnectDialog(QWidget *parent = nullptr)

Create a remote connection dialog.

QString remoteUrl() const

Repository URL entered by the user.

QString parentFolder() const

Parent folder selected as the clone destination.