- Extending Qt Creator Manual
- Utils Namespace
- Extending Qt Creator Manual 20.0.0-beta1

# Utils Namespace

The Utils namespace contains a collection of utility classes and functions for use by all plugins. More...

Header: | `#include <Utils>`

## Namespaces

namespace | FileUtils
namespace | MathUtils
namespace | SettingsDatabase

## Classes

class | Action
class | AnsiEscapeCodeHandler
class | AspectContainer
class | BaseAspect
class | BoolAspect
class | CheckableMessageBox
class | ClassNameValidatingLineEdit
class | ColorAspect
class | CommandLine
class | CompletingTextEdit
class | DetailsWidget
class | DocumentTabBar
class | DoubleAspect
class | ElidingLabel
class | Environment
class | FakeToolTip
class | FancyLineEdit
class | FancyMainWindow
class | FileInProjectFinder
class | FileNameValidatingLineEdit
class | FilePath
class | FilePathAspect
class | FilePathListAspect
class | FilePathWatcher
class | FileSystemWatcher
class | FileWizardPage
class | FontAspect
class | FutureSynchronizer
class | Guard
class | HeaderViewStretcher
class | Id
class | IntegerAspect
class | ListView
class | ListWidget
class | MacroExpander
class | MultiSelectionAspect
class | NavigationTreeView
class | NetworkAccessManager
class | OptionPushButton
class | PathChooser
class | PathListEditor
class | PersistentSettingsReader
class | PersistentSettingsWriter
class | PlainTextDocumentLayout
class | PlainTextEdit
class | Port
class | Process
class | ProcessArgs
class | ProcessHandle
class | ProgressIndicator
class | ProgressIndicatorPainter
class | ProjectIntroPage
class | QrcCache
class | QrcParser
class | QtcSettings
class | Result
class | ResultError
class | SelectionAspect
class | StatusLabel
class | StringAspect
class | StringListAspect
class | TextDisplay
class | TextFieldCheckBox
class | TextFieldComboBox
class | TextFileFormat
class | ToggleAspect
class | TreeModel
class | TreeView
class | TriStateAspect
class | TypedAspect
class | VariableChooser
class | Wizard
class | WizardPage

## Types

enum | FindFlag { FindBackward, FindCaseSensitively, FindWholeWords, FindRegularExpression, FindPreserveCase, DontFindBinaryFiles }
flags | FindFlags
enum class | ProgressIndicatorSize { Small, Medium, Large }
enum | ResultSpecialErrorCode { ResultAssert, ResultUnimplemented }

## Variables

const Utils::Result<> | ResultOk

## Functions

void | addToolTipsToMenu(QMenu *menu)
QAction * | execMenuAtWidget(QMenu *menu, QWidget *widget)
Utils::FutureSynchronizer * | futureSynchronizer()
Utils::MacroExpander * | globalMacroExpander()
Utils::QtcSettings & | installSettings()
QString | joinStrings(const QStringList &strings, SEPARATOR separator)
Utils::Result<> | makeResult(bool ok, const QString &errorMessage)
QString | qtcEnvironmentVariable(const QString &key)
QString | qtcEnvironmentVariable(const QString &key, const QString &defaultValue)
int | qtcEnvironmentVariableIntValue(const QString &key, bool *ok = nullptr)
bool | qtcEnvironmentVariableIsEmpty(const QString &key)
bool | qtcEnvironmentVariableIsSet(const QString &key)
bool | setUpCrashReporting()
QObject * | shutdownGuard()
void | triggerShutdownGuard()
QString | trim(const QString &string, QChar ch)
QString | trimBack(const QString &string, QChar ch)
QString | trimFront(const QString &string, QChar ch)
Utils::QtcSettings & | userSettings()

## Detailed Description

## Namespaces

### namespace Utils::FileUtils

### namespace Utils::MathUtils

### namespace Utils::SettingsDatabase

The settings database is SQLite based, and lazily retrieves data when it is asked for. It also does incremental updates of the database rather than rewriting the whole file each time one of the settings change.

The SettingsDatabase API mimics that of QSettings.

See also settings().

## Classes

### class Action

The Action class is intended for actions that act on a 'current', string-type parameter (typically a file name), for example 'Save file %1'. More...

### class AnsiEscapeCodeHandler

The AnsiEscapeCodeHandler class parses text and extracts ANSI escape codes from it. More...

### class AspectContainer

The AspectContainer class wraps one or more aspects while providing the interface of a single aspect. More...

### class BaseAspect

The `BaseAspect` class provides a common base for classes implementing aspects. More...

### class BoolAspect

A boolean aspect is a boolean property of some object, together with a description of its behavior for common operations like visualizing or persisting. More...

### class CheckableMessageBox

The CheckableMessageBox class implements a message box suitable for questions with a Do not ask again or Do not show again checkbox. More...

### class ClassNameValidatingLineEdit

The ClassNameValidatingLineEdit class implements a line edit that validates a C++ class name and emits a signal to derive suggested file names from it. More...

### class ColorAspect

A color aspect is a color property of some object, together with a description of its behavior for common operations like visualizing or persisting. More...

### class CommandLine

The CommandLine class represents a command line of a QProcess or similar utility. More...

### class CompletingTextEdit

The CompletingTextEdit class is a QTextEdit with auto-completion support. More...

### class DetailsWidget

The DetailsWidget class implements a button to expand a Details area. More...

### class DocumentTabBar

The DocumentTabBar class adds handling of the middle mouse button for closing tabs to QTabBar. More...

### class DoubleAspect

An double aspect is a numerical property of some object, together with a description of its behavior for common operations like visualizing or persisting. More...

### class ElidingLabel

The ElidingLabel class is a label suitable for displaying elided text. More...

### class Environment

The Environment class sets Qt Creator's system environment. More...

### class FakeToolTip

The FakeToolTip class is a widget that pretends to be a tooltip. More...

### class FancyLineEdit

The FancyLineEdit class is an enhanced line edit with several opt-in features. More...

### class FancyMainWindow

The FancyMainWindow class is a MainWindow with dock widgets and additional "lock" functionality (locking the dock widgets in place) and "reset layout" functionality. More...

### class FileInProjectFinder

The FileInProjectFinder class is a helper class to find the original file in the project directory for a given file URL. More...

### class FileNameValidatingLineEdit

The FileNameValidatingLineEdit class is a control that lets the user choose a (base) file name, based on a QLineEdit. More...

### class FilePath

The FilePath class is an abstraction for handles to objects in a (possibly remote) file system, similar to a URL or, in the local case, a path to a file or directory. More...

### class FilePathAspect

A file path aspect is shallow wrapper around a Utils::StringAspect that represents a file in the file system. More...

### class FilePathListAspect

A filepath list aspect represents a property of some object that is a list of filepathList. More...

### class FilePathWatcher

The FilePathWatcher class watches a file at a path for editing, renaming, or deletion. More...

### class FileSystemWatcher

The FileSystemWatcher class is a file watcher that internally uses a centralized QFileSystemWatcher and enforces limits on Mac OS. More...

### class FileWizardPage

The FileWizardPage class is a standard wizard page for a single file letting the user choose name and path. More...

### class FontAspect

A font aspect is a font property of some object, together with a description of its behavior for common operations like visualizing or persisting. More...

### class FutureSynchronizer

The FutureSynchronizer is an enhanced version of QFutureSynchronizer. More...

### class Guard

The Guard class implements a recursive guard with locking mechanism. More...

### class HeaderViewStretcher

The HeaderViewStretcher class fixes QHeaderView to resize all columns to contents, except one stretching column. More...

### class Id

The Id class encapsulates an identifier that is unique within a specific running Qt Creator process. More...

### class IntegerAspect

An integer aspect is a integral property of some object, together with a description of its behavior for common operations like visualizing or persisting. More...

### class ListView

The ListView adds setActivationMode to QListView to allow for single click/double click behavior on platforms where the default is different. Use with care. More...

### class ListWidget

The ListWidget adds setActivationMode to QListWidget to allow for single click/double click behavior on platforms where the default is different. Use with care. More...

### class MacroExpander

The MacroExpander class manages Qt Creator wide variables, that a user can enter into many string settings. The variables are replaced by an actual value when the string is used, similar to how environment variables are expanded by a shell. More...

### class MultiSelectionAspect

A multi-selection aspect represents one or more choices out of several. More...

### class NavigationTreeView

The NavigationTreeView class implements a general TreeView for any sidebar widget. More...

### class NetworkAccessManager

The NetworkAccessManager class provides a network access manager for use with Qt Creator. More...

### class OptionPushButton

The OptionPushButton class implements a QPushButton for which the menu is only opened if the user presses the menu indicator. More...

### class PathChooser

The PathChooser class is a control that lets the user choose a path. The control consist of a QLineEdit and a "Browse" button, and is optionally able to perform variable substitution. More...

### class PathListEditor

The PathListEditor class is a control that lets the user edit a list of (directory) paths using the platform separator (';',':'). More...

### class PersistentSettingsReader

The PersistentSettingsReader class reads a QVariantMap of arbitrary, nested data structures from an XML file. More...

### class PersistentSettingsWriter

The PersistentSettingsWriter class serializes a Store of arbitrary, nested data structures to an XML file. More...

### class PlainTextDocumentLayout

The PlainTextDocumentLayout class implements a plain text layout for QTextDocument. More...

### class PlainTextEdit

The PlainTextEdit class provides a widget that is used to edit and display plain text. More...

### class Port

The Port class implements a wrapper around a 16 bit port number to be used in conjunction with IP addresses. More...

### class Process

The Process class provides functionality for with processes. More...

### class ProcessArgs

Handles shell-quoted process arguments. More...

### class ProcessHandle

The ProcessHandle class is a helper class to describe a process. More...

### class ProgressIndicator

The ProgressIndicator class shows an circular, endlessly animated progress indicator. More...

### class ProgressIndicatorPainter

The ProgressIndicatorPainter class is the painting backend for the ProgressIndicator class. More...

### class ProjectIntroPage

The ProjectIntroPage class is the standard wizard page for a project, letting the user choose its name and path. More...

### class QrcCache

The QrcCache class caches the contents of parsed QRC files. More...

### class QrcParser

The QrcParser class parses one or more QRC files and keeps their content cached. More...

### class QtcSettings

The QtcSettings class is an extension of the QSettings class the uses Utils::Key instead of QString for keys. More...

### class Result

Result<T> is used for returning either a success value or an error string from a function. More...

### class ResultError

The ResultError class is used for returning an error including an error message for the user from a function. More...

### class SelectionAspect

A selection aspect represents a specific choice out of several. More...

### class StatusLabel

The StatusLabel class displays messages for a while with a timeout. More...

### class StringAspect

A string aspect is a string-like property of some object, together with a description of its behavior for common operations like visualizing or persisting. More...

### class StringListAspect

A string list aspect represents a property of some object that is a list of strings. More...

### class TextDisplay

A text display is a phony aspect with the sole purpose of providing some text display using an Utils::InfoLabel in places where otherwise more expensive Utils::StringAspect items would be used. More...

### class TextFieldCheckBox

The TextFieldCheckBox class is a aheckbox that plays with `QWizard::registerField`. More...

### class TextFieldComboBox

The TextFieldComboBox class is a non-editable combo box for text editing purposes that plays with `QWizard::registerField` (providing a settable 'text' property). More...

### class TextFileFormat

The TextFileFormat class describes the format of a text file and provides autodetection. More...

### class ToggleAspect

A toggle aspect is a boolean property of some object, together with a description of its behavior for common operations like visualizing or persisting. It also contains independent tooltips, icons and text for the action() according to the on / off state of the aspect. More...

### class TreeModel

The TreeModel class is a convienience base class for models to use in a QTreeView. More...

### class TreeView

The TreeView adds setActivationMode to QTreeView to allow for single click/double click behavior on platforms where the default is different. Use with care. More...

### class TriStateAspect

A tristate aspect is a property of some object that can have three values: enabled, disabled, and unspecified. More...

### class TypedAspect

The `TypedAspect` class is a helper class for implementing a simple aspect. More...

### class VariableChooser

The VariableChooser class is used to add a tool window for selecting Qt Creator variables to line edits, text edits or plain text edits. More...

### class Wizard

The Wizard class implements a wizard with a progress bar on the left. More...

### class WizardPage

QWizardPage with a couple of improvements. More...

## Type Documentation

### enum Utils::FindFlag
flags Utils::FindFlags

This enum holds the find flags.

Constant | Value | Description
--- | --- | ---
`Utils::FindBackward` | `0x01` | Searches backwards.
`Utils::FindCaseSensitively` | `0x02` | Considers case when searching.
`Utils::FindWholeWords` | `0x04` | Finds only whole words.
`Utils::FindRegularExpression` | `0x08` | Uses a regular epression as a search term.
`Utils::FindPreserveCase` | `0x10` | Preserves the case when replacing search terms.
`Utils::DontFindBinaryFiles` | `0x20` | Does not include binary files in search results.

The FindFlags type is a typedef for QFlags<FindFlag>. It stores an OR combination of FindFlag values.

### enum class Utils::ProgressIndicatorSize

Size of a progress indicator.

Constant | Value | Description
--- | --- | ---
`Utils::ProgressIndicatorSize::Small` | `0` | Small icon size. Useful for tool bars, status bars, rows in tree views, and so on.
`Utils::ProgressIndicatorSize::Medium` | `1` | Larger progress indicator useful for covering whole medium sized widgets.
`Utils::ProgressIndicatorSize::Large` | `2` | Very large progress indicator that can be used to cover large parts of a UI.

See also Utils::ProgressIndicator and Utils::ProgressIndicatorPainter.

### enum Utils::ResultSpecialErrorCode

The ResultSpecialErrorCode enum is used with the Utils::ResultError class to provide a set of standardized error messages.

Constant | Value | Description
--- | --- | ---
`Utils::ResultAssert` | `0` | An internal error that indicates that preconditions are violated.
`Utils::ResultUnimplemented` | `1` | A backend unexpectedly did not provide an implementation of this functionality.

See also Utils::ResultError.

## Variable Documentation

### const Utils::Result<> Utils::ResultOk

Use the global object ResultOk to return success of type `Result<>`.

See also Utils::Result.

## Function Documentation

### void Utils::addToolTipsToMenu(QMenu *menu)

Adds tool tips to the menu that show the action's tool tip when hovering over an entry.

### QAction *Utils::execMenuAtWidget(QMenu *menu, QWidget *widget)

Opens menu at the specified widget position. This function computes the position where to show the menu, and opens it with QMenu::exec().

### Utils::FutureSynchronizer *Utils::futureSynchronizer()

Returns a global FutureSynchronizer. The application should cancel and wait for the tasks in this synchronizer before actually unloading any libraries. This is for example done by the plugin manager in Qt Creator. May only be accessed by the main thread.

### Utils::MacroExpander *Utils::globalMacroExpander()

Returns the expander for globally registered variables.

### Utils::QtcSettings &Utils::installSettings()

Returns the global (user-independent) settings used for information about default disabled plugins.

### template <typename SEPARATOR> QString Utils::joinStrings(const QStringList &strings, SEPARATOR separator)

Joins all the not empty string list's strings into a single string with each element separated by the given separator (which can be an empty string).

### Utils::Result<> Utils::makeResult(bool ok, const QString &errorMessage)

Returns a result object that reports success if ok is true, or error with an errorMessage for the user if ok is false.

See also Utils::Result.

### QString Utils::qtcEnvironmentVariable(const QString &key)

Returns the value of key in Qt Creator's modified system environment.

See also Utils::Environment::systemEnvironment and qEnvironmentVariable.

### QString Utils::qtcEnvironmentVariable(const QString &key, const QString &defaultValue)

Returns the value of key in Qt Creator's modified system environment if it is set, or otherwise defaultValue.

See also Utils::Environment::systemEnvironment and qEnvironmentVariable.

### int Utils::qtcEnvironmentVariableIntValue(const QString &key, bool *ok = nullptr)

Returns the value of key in Qt Creator's modified system environment, converted to an int. If ok is not null, sets `*ok` to true or false depending on the success of the conversion

See also Utils::Environment::systemEnvironment and qEnvironmentVariableIntValue.

### bool Utils::qtcEnvironmentVariableIsEmpty(const QString &key)

Returns if the environment variable key is not set or empty in Qt Creator's modified system environment.

See also Utils::Environment::systemEnvironment and qEnvironmentVariableIsEmpty.

### bool Utils::qtcEnvironmentVariableIsSet(const QString &key)

Returns if the environment variable key is set Qt Creator's modified system environment.

See also Utils::Environment::systemEnvironment and qEnvironmentVariableIsSet.

### bool Utils::setUpCrashReporting()

Returns whether it succeeded. Normally `false` indicates that a restart is required before the change can take effect.

### QObject *Utils::shutdownGuard()

Returns an object that can be used as the parent for objects that should be destroyed just at the end of the applications lifetime. The object is destroyed after all plugins' aboutToShutdown methods have finished, just before the plugins are deleted.

Only use this from the application's main thread.

See also ExtensionSystem::IPlugin::aboutToShutdown().

### void Utils::triggerShutdownGuard()

Destroys the shutdown guard object and consequently all objects guarded by it.

In a normal run of the application this function is called automatically at the appropriate time.

### QString Utils::trim(const QString &string, QChar ch)

Returns a copy of string that has ch characters removed from the start and the end.

### QString Utils::trimBack(const QString &string, QChar ch)

Returns a copy of string that has ch characters removed from the end.

### QString Utils::trimFront(const QString &string, QChar ch)

Returns a copy of string that has ch characters removed from the start.

### Utils::QtcSettings &Utils::userSettings()

Returns the user specific settings used for information about enabled and disabled plugins.