- Extending Qt Creator Manual
- Utils Namespace
- Extending Qt Creator Manual 21.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 | Aggregation
namespace | FileUtils
namespace | Internal
namespace | MathUtils
namespace | SettingsDatabase

## Classes

class | CheckableMessageBox
class | CommandLine
class | CompletingTextEdit
class | DetailsWidget
class | DocumentTabBar
class | DropSupport
class | ElidingLabel
class | Environment
class | FakeToolTip
class | FancyMainWindow
class | FileInProjectFinder
class | FileSystemWatcher
class | FileWizardPage
class | Guard
class | GuardedObject
class | HeaderViewStretcher
class | ListView
class | ListWidget
class | MacroExpander
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 | StatusLabel
class | TextFieldCheckBox
class | TextFieldComboBox
class | TextFileFormat
class | TreeModel
class | TreeView
class | TypedAspect
class | VariableChooser
class | Wizard
class | WizardPage

## Types

enum | FindFlag { FindBackward, FindCaseSensitively, FindWholeWords, FindRegularExpression, FindPreserveCase, DontFindBinaryFiles }
flags | FindFlags
enum class | PathChooserKind { ExistingDirectory, Directory, File, SaveFile, ExistingCommand, …, Any }
enum class | ProgressIndicatorSize { Small, Medium, Large }
enum | ResultSpecialErrorCode { ResultAssert, ResultUnimplemented }

## Functions

void | addToolTipsToMenu(QMenu *menu)
QAction * | execMenuAtWidget(QMenu *menu, QWidget *widget)
Utils::MacroExpander * | globalMacroExpander()
Utils::QtcSettings & | installSettings()
class QString | joinStrings(const QStringList &strings, SEPARATOR separator)
class QString | qtcEnvironmentVariable(const class QString &key)
class QString | qtcEnvironmentVariable(const class QString &key, const class QString &defaultValue)
int | qtcEnvironmentVariableIntValue(const class QString &key, bool *ok = nullptr)
bool | qtcEnvironmentVariableIsEmpty(const class QString &key)
bool | qtcEnvironmentVariableIsSet(const class QString &key)
QObject * | shutdownGuard()
void | triggerShutdownGuard()
class QString | trim(const class QString &string, QChar ch)
class QString | trimBack(const class QString &string, QChar ch)
class QString | trimFront(const class QString &string, QChar ch)
Utils::QtcSettings & | userSettings()
QTextStream & | operator<<(QTextStream &s, const Utils::FilePath &fn)

## Detailed Description

## Namespaces

### namespace Utils::Aggregation

Components that are bundled into an aggregate can be cast to each other and have a coupled life cycle. See the documentation of Aggregation::Aggregate for details and examples.

### namespace Utils::FileUtils

### namespace Utils::Internal

Stores the internal value of this BaseAspect into the Store map.

### 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 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 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 DropSupport

The DropSupport class makes it easy for a QWidget to accept drops without subclassing QWidget and overriding methods. 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 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 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 Guard

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

### class GuardedObject

The GuardedObject class owns a heap-allocated object and deletes it when the shutdown guard is destroyed. More...

### class HeaderViewStretcher

The HeaderViewStretcher class fixes QHeaderView to resize all columns to contents, except one stretching column. 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 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 StatusLabel

The StatusLabel class displays messages for a while with a timeout. 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 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 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::PathChooserKind

The Kind enum describes the kind of path a PathChooser considers valid.

Constant | Value | Description
--- | --- | ---
`Utils::PathChooserKind::ExistingDirectory` | `0` | An existing directory
`Utils::PathChooserKind::Directory` | `1` | A directory that does not need to exist
`Utils::PathChooserKind::File` | `2` | An existing file
`Utils::PathChooserKind::SaveFile` | `3` | A file that does not need to exist
`Utils::PathChooserKind::ExistingCommand` | `4` | An executable file that must exist at the time of selection
`Utils::PathChooserKind::Command` | `5` | An executable file that may or may not exist at the time of selection (e.g. result of a build)
`Utils::PathChooserKind::Any` | `6` | No restriction on the selected path

See also setExpectedKind() and expectedKind().

### 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.

## 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::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> class 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).

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

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

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

### class QString Utils::qtcEnvironmentVariable(const class QString &key, const class 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 class 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 class 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 class QString &key)

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

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

### 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.

To tie a single object's lifetime to the guard, prefer the GuardedObject wrapper over connecting to this object's `destroyed()` signal by hand.

See also Utils::GuardedObject and 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.

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

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

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

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

### class QString Utils::trimFront(const class 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.

### QTextStream &Utils::operator<<(QTextStream &s, const Utils::FilePath &fn)

Sorts the paths in-place using the default less-than comparison.