Querying standard paths

Querying Standard Paths

Many ManiVault-based applications need to know “where to put things”: plugins, downloads, user projects, log files, and so on.
To keep this consistent across the application (and across platforms), ManiVault provides the utility class mv::util::StandardPaths.

This tutorial explains what standard paths exist and how to query them from C++.

---

Standard paths overview

StandardPaths exposes a small set of logical locations via the StandardLocation enum:

• Plugins
  Directory where the application looks for loadable plugins.

  • Typically a Plugins directory located next to the application binary (or near the app bundle on macOS).

• Downloads
  Directory for files downloaded or exported by the application.

  • On Windows/Linux, this lives under the app’s application data folder (e.g. AppDataLocation/Downloads).
  • On macOS, it is placed next to the app (a Downloads folder beside the bundle).
  • The directory is created automatically if it does not exist.

• Customization
  The application’s customization folder (e.g. where app.json lives). More on app customization here.

  • By default, this is a Customization folder next to the application directory.
  • On macOS, the folder is resolved relative to the app bundle.
  • The directory is created automatically when first requested.

• Projects
  Default location for user projects.

  • Implemented as a subfolder in the user’s Documents directory, using the application’s organization name and base name:
    Documents/<OrganizationName>/<BaseName>/Projects
  • The directory is created automatically.
  • If no documents location is available, the user’s home directory is used as a fallback.

• Logs
  Default location for application log files.

  • Similar to Projects, but using a Logs subfolder:
    Documents/<OrganizationName>/<BaseName>/Logs
  • Again, the directory is created if missing, and falls back to the home directory if needed.

The Projects and Logs directories both derive their base path from QStandardPaths::writableLocation(QStandardPaths::DocumentsLocation) and use the application’s organization/base name via the Application class.

---

Basic usage from C++

Including the header

To use StandardPaths, include its header and use the mv::util namespace:

#include "StandardPaths.h"

using mv::util::StandardPaths;

(Adjust the include path to match your project layout.)

Using the generic get() function

The central entry point is:

QString path = StandardPaths::get(StandardPaths::Customization);

This returns the absolute path for the requested StandardLocation. Internally, get() forwards to the appropriate convenience function (getPluginsDirectory(), getDownloadsDirectory(), etc.).

Example: query the main locations at startup and store them for later:

QString pluginsDir   = StandardPaths::get(StandardPaths::Plugins);
QString downloadsDir = StandardPaths::get(StandardPaths::Downloads);
QString customDir    = StandardPaths::get(StandardPaths::Customization);
QString projectsDir  = StandardPaths::get(StandardPaths::Projects);
QString logsDir      = StandardPaths::get(StandardPaths::Logs);

You can then pass these paths to file dialogs, loggers, project managers, and so on.

Using the convenience getters

If you know exactly which directory you want, you can call the dedicated functions:

QString pluginsDir   = StandardPaths::getPluginsDirectory();
QString downloadsDir = StandardPaths::getDownloadsDirectory();
QString customDir    = StandardPaths::getCustomizationDirectory();
QString projectsDir  = StandardPaths::getProjectsDirectory();
QString logsDir      = StandardPaths::getLogsDirectory();

These are thin wrappers around the logic described above and behave identically to get(...) with the corresponding enum value.

---

Directory creation behaviour

StandardPaths not only returns paths, but it also ensures that certain directories exist:

• Downloads, Customization, Projects, Logs
  These locations call QDir::mkpath(...) under the hood before returning the path, so the directory is created on first use if needed.

• Plugins
  The plugins directory is not created by StandardPaths; it is assumed to be part of your application installation or deployment layout.

This means you can safely write to Downloads, Projects, or Logs immediately after querying them; no extra checks or mkpath calls are needed in your own code.

---

Platform specifics (macOS vs. others)

Internally, StandardPaths detects macOS using QOperatingSystemVersion::currentType() and adjusts the paths accordingly.

• On macOS, paths like Plugins, Downloads, and Customization are computed relative to QCoreApplication::applicationDirPath(), taking into account that the executable lives inside an app bundle (.app).
• On other platforms, the application directory and Qt’s QStandardPaths locations (AppDataLocation, DocumentsLocation) are used directly.

From the caller’s perspective, all of this is transparent: you always just ask StandardPaths for a logical location and get back a usable absolute path.

---

That’s all you need to use StandardPaths: pick the logical location you need, call either get(...) or a convenience function, and let the utility handle OS-specific details and directory creation for you.