Qt Utilities: QtUtilities Namespace Reference

Qt Utilities 6.21.3 Common Qt related C++ classes and routines used by my applications such as dialogs, widgets and models

Loading...
Searching...
No Matches
Namespaces | Classes | Typedefs | Enumerations | Functions
QtUtilities Namespace Reference

! More...

## Namespaces
namespace | QtUtilitiesResources
| Functions for using the resources provided by this library.
namespace | TranslationFiles
| Convenience functions to load translations for Qt and the application.
namespace | ApplicationInstances
| Convenience functions to check whether a QCoreApplication/QGuiApplication/QApplication singleton has been instantiated yet.
namespace | Ui

## Classes
class | TryLocker
| Like QMutexLocker, but it just tries to lock the mutex. More...
class | AdoptLocker
| Like QMutexLocker, but assumes that the mutex has already been locked. More...
class | QtSettings
class | UpdateNotifier
| The UpdateNotifier class allows checking for new updates. More...
class | Updater
| The Updater class allows downloading and applying an update. More...
class | UpdateHandler
| The UpdateHandler class manages the non-graphical aspects of checking for new updates and performing them. More...
class | RestartHandler
| The RestartHandler class allows quitting and respawning the application if a restart is requested. More...
class | ChecklistItem
class | ChecklistModel
class | DBusNotification
| The DBusNotification class emits D-Bus notifications. More...
struct | QtSettingsData
struct | UpdateNotifierPrivate
struct | UpdaterPrivate
struct | UpdateHandlerPrivate
struct | SwappedImage
| The SwappedImage struct represents RGB-interved version of the image specified on construction. More...
struct | NotificationImage
| The NotificationImage struct is a raw data image format. More...
class | AboutDialog
| The AboutDialog class provides a simple about dialog. More...
class | EnterPasswordDialog
| The EnterPasswordDialog class provides a simple dialog to ask the user for a password. More...
class | OptionCategory
| The OptionCategory class wraps associated option pages. More...
class | OptionCategoryFilterModel
| The OptionCategoryFilterModel class is used by SettingsDialog to filter option categories. More...
class | OptionCategoryModel
| The OptionCategoryModel class is used by SettingsDialog to store and display option categories. More...
class | OptionPageWidget
class | OptionPage
| The OptionPage class is the base class for SettingsDialog pages. More...
class | UiFileBasedOptionPage
class | SettingsDialog
| The SettingsDialog class provides a framework for creating settings dialogs with different categories and subcategories. More...
class | ButtonOverlay
| The ButtonOverlay class is used to display buttons on top of other widgets. More...
class | ClearComboBox
| A QComboBox with an embedded button for clearing its contents. More...
class | ClearLineEdit
| A QLineEdit with an embedded button for clearing its contents. More...
class | ClearPlainTextEdit
| A QPlainTextEdit with an embedded button for clearing its contents. More...
class | ClearSpinBox
| A QSpinBox with an embedded button for clearing its contents and the ability to hide the minimum value. More...
class | IconButton
| A simple QAbstractButton implementation displaying a QPixmap. More...
class | PathSelection
| A QLineEdit with a QPushButton next to it which allows to select file/directory via QFileDialog. More...
class | PaletteEditor
| The PaletteEditor class provides a dialog to customize a QPalette. More...
class | PaletteModel
| The PaletteModel class is used by PaletteEditor. More...
class | BrushEditor
| The BrushEditor class is used by PaletteEditor. More...
class | RoleEditor
| The RoleEditor class is used by PaletteEditor. More...
class | ColorDelegate
| The ColorDelegate class is used by PaletteEditor. More...
class | ColorButton
| The ColorButton class is used by PaletteEditor. More...
class | RecentMenuManager
| The RecentMenuManager class manages the entries for a "recently opened files" menu. More...

## Typedefs
using | Utf16CharType
using | StringView
using | VersionSuffixIndex = qsizetype

## Enumerations
enum class | DocumentStatus { NoDocument , Saved , Unsaved }
| The DocumentStatus enum specifies the status of the document in a window. More...
enum class | UpdateCheckFlags : quint64 { None = 0 , IncludePreReleases = (1 << 0) , IncludeDrafts = (1 << 1) , Default = None }
enum class | NotificationIcon { NoIcon , Information , Warning , Critical }
enum class | NotificationCloseReason { Undefined , Expired , Dismissed , Manually , ActionInvoked }
enum | { BrushRole = 33 }

## Functions
QT_UTILITIES_EXPORT QString | generateWindowTitle (DocumentStatus documentStatus, const QString &documentPath)
| Generates the window title string for the specified documentStatus and documentPath.
QT_UTILITIES_EXPORT bool | openLocalFileOrDir (const QString &path)
| Shows the specified file or directory using the default file browser.
QT_UTILITIES_EXPORT bool | isPaletteDark (const QPalette &palette)
| Returns whether palette is dark.
QT_UTILITIES_EXPORT std::optional< bool > | isDarkModeEnabled ()
| Returns whether dark mode is enabled.
QT_UTILITIES_EXPORT QMetaObject::Connection | onDarkModeChanged (std::function< void(bool)> &&darkModeChangedCallback, QObject *context, bool invokeImmediately)
| Invokes the specified callback when the color scheme changed.
QByteArray | toNativeFileName (const QString &fileName)
QString | fromNativeFileName (const char *nativeFileName, int size=-1)
QString | fromNativeFileName (const std::string &nativeFileName)
QString | qstringFromStdStringView (std::string_view stringView)
StringView | makeStringView (const QString &str)
| Makes either a QStringView or a QStringRef depending on the Qt version.
template<typename PosType1, typename PosType2 = PosType1, CppUtilities::Traits::EnableIf< std::is_integral< PosType1 >, std::is_signed< PosType1 >, std::is_integral< PosType2 >, std::is_signed< PosType2 > > * = nullptr>
StringView | midRef (const QString &str, PosType1 pos, PosType2 n=-1)
| Makes either a QStringView or a QStringRef depending on the Qt version, applying "mid()" parameters.
template<class... SplitArgs>
auto | splitRef (const QString &str, SplitArgs &&...args)
| Splits str into QStringViews, QStringRefs or QStrings depending on the Qt version.
QT_UTILITIES_EXPORT void | setupCommonQtApplicationAttributes ()
| Sets Qt application attributes which are commonly used within my Qt applications.
QT_UTILITIES_EXPORT std::unique_ptr< QSettings > | getSettings (const QString &organization, const QString &application)
| Returns the settings object for the specified organization and application.
QT_UTILITIES_EXPORT QString | errorMessageForSettings (const QSettings &settings)
| Returns an error message for the specified settings or an empty string if there's no error.
QT_UTILITIES_EXPORT void | loadSettingsWithLogging (QSettings &settings)
| Loads settings and logs a corresponding message if the env variable QT_DEBUG_SETTINGS is set.
QT_UTILITIES_EXPORT void | saveSettingsWithLogging (QSettings &settings)
| Saves settings and logs a corresponding message if the env variable QT_DEBUG_SETTINGS is set.
QT_UTILITIES_EXPORT void | deletePipelineCacheIfNeeded ()
| Disables the Qt Quick pipeline cache on platforms where this is needed to workaround issues with the cache.
QDBusArgument & | operator<< (QDBusArgument &argument, const NotificationImage &img)
const QDBusArgument & | operator>> (const QDBusArgument &argument, NotificationImage &img)

## Detailed Description

!

The QtUtilities namespace contains all utilities provided by the qtutilities library.

## Typedef Documentation

## ◆ StringView

using QtUtilities::StringView

Initial value:
QStringView

Definition at line 32 of file compat.h.

## ◆ Utf16CharType

using QtUtilities::Utf16CharType

Initial value:
char16_t

Definition at line 24 of file compat.h.

## ◆ VersionSuffixIndex

using QtUtilities::VersionSuffixIndex = qsizetype

Definition at line 108 of file updater.cpp.

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

Enumerator
BrushRole |

Definition at line 21 of file paletteeditor.cpp.

## ◆ DocumentStatus

enum class QtUtilities::DocumentStatus
| strong

The DocumentStatus enum specifies the status of the document in a window.

Enumerator
NoDocument | There is no document opened. The document path is ignored in this case.
Saved | There is a document opened. All modifications have been saved yet.
Unsaved | There is a document opened and there are unsaved modifications.

Definition at line 21 of file dialogutils.h.

## ◆ NotificationCloseReason

enum class QtUtilities::NotificationCloseReason
| strong

Enumerator
Undefined |
Expired |
Dismissed |
Manually |
ActionInvoked |

Definition at line 20 of file dbusnotification.h.

## ◆ NotificationIcon

enum class QtUtilities::NotificationIcon
| strong

Enumerator
NoIcon |
Information |
Warning |
Critical |

Definition at line 18 of file dbusnotification.h.

## ◆ UpdateCheckFlags

enum class QtUtilities::UpdateCheckFlags : quint64
| strong

Enumerator
None |
IncludePreReleases |
IncludeDrafts |
Default |

Definition at line 45 of file updater.h.

## Function Documentation

## ◆ deletePipelineCacheIfNeeded()

void QtUtilities::deletePipelineCacheIfNeeded | ( |  | ) |

Disables the Qt Quick pipeline cache on platforms where this is needed to workaround issues with the cache.

Remarks
  This function is called "delete…" because it previously deleted the cache. However, it is actually possible to just disable it so that is preferable.

Definition at line 515 of file resources.cpp.

## ◆ errorMessageForSettings()

QString QtUtilities::errorMessageForSettings | ( | const QSettings & | settings | ) |

Returns an error message for the specified settings or an empty string if there's no error.

Definition at line 491 of file resources.cpp.

## ◆ fromNativeFileName() [1/2]

QString QtUtilities::fromNativeFileName | ( | const char * | nativeFileName,
|  | int | size = -1 )
| inline

Definition at line 22 of file conversion.h.

## ◆ fromNativeFileName() [2/2]

QString QtUtilities::fromNativeFileName | ( | const std::string & | nativeFileName | ) |
| inline

Definition at line 31 of file conversion.h.

## ◆ generateWindowTitle()

QString QtUtilities::generateWindowTitle | ( | DocumentStatus | documentStatus,
|  | const QString & | documentPath )

Generates the window title string for the specified documentStatus and documentPath.

Definition at line 31 of file dialogutils.cpp.

## ◆ getSettings()

std::unique_ptr< QSettings > QtUtilities::getSettings | ( | const QString & | organization,
|  | const QString & | application )

Returns the settings object for the specified organization and application.

Remarks
  - This function always uses INI as that's what I'd like to use in all of my applications consistently, regardless of the platform.
  - The parameter application might be empty. In fact, most of my applications use just getSettings(QStringLiteral(PROJECT_NAME)).
  - This function first checks whether a file called $organization/$application.ini exists in the current working directory or next to the executable (or just $organization.ini if application is empty) and uses that if it exists. That allows having a portable installation.
  - Some of my apps where using values from QCoreApplication for organization and application in the beginning. This function moves those old config files to their new location if needed. This extra handling will likely removed at some point. Note that I moved away from using values from QCoreApplication to avoid having spaces and additional config suffixes in the file name.

Definition at line 430 of file resources.cpp.

## ◆ isDarkModeEnabled()

std::optional< bool > QtUtilities::isDarkModeEnabled | ( |  | ) |

Returns whether dark mode is enabled.

Remarks
  Whether dark mode is enabled can only be determined on Qt 6.5 or newer and only on certain platforms. If it cannot be determined, std::nullopt is returned.

Definition at line 80 of file desktoputils.cpp.

## ◆ isPaletteDark()

bool QtUtilities::isPaletteDark | ( | const QPalette & | palette = QPalette() | ) |

Returns whether palette is dark.

Definition at line 70 of file desktoputils.cpp.

## ◆ loadSettingsWithLogging()

void QtUtilities::loadSettingsWithLogging | ( | QSettings & | settings | ) |

Loads settings and logs a corresponding message if the env variable QT_DEBUG_SETTINGS is set.

Definition at line 457 of file resources.cpp.

## ◆ makeStringView()

StringView QtUtilities::makeStringView | ( | const QString & | str | ) |
| inline

Makes either a QStringView or a QStringRef depending on the Qt version.

Definition at line 43 of file compat.h.

## ◆ midRef()

template<typename PosType1, typename PosType2 = PosType1, CppUtilities::Traits::EnableIf< std::is_integral< PosType1 >, std::is_signed< PosType1 >, std::is_integral< PosType2 >, std::is_signed< PosType2 > > * = nullptr>

StringView QtUtilities::midRef | ( | const QString & | str,
|  | PosType1 | pos,
|  | PosType2 | n = -1 )
| inline

Makes either a QStringView or a QStringRef depending on the Qt version, applying "mid()" parameters.

Definition at line 58 of file compat.h.

## ◆ onDarkModeChanged()

QMetaObject::Connection QtUtilities::onDarkModeChanged | ( | std::function< void(bool)> && | darkModeChangedCallback,
|  | QObject * | context,
|  | bool | invokeImmediately )

Invokes the specified callback when the color scheme changed.

The first argument of the callback will be whether the color scheme is dark now (Qt::ColorScheme::Dark). The callback is invoked immediately by this function unless invokeImmediately is set to false.

Remarks
  Whether dark mode is enabled can only be determined on Qt 6.5 or newer and only on certain platforms. If it cannot be determined the darkModeChangedCallback is never invoked.

Definition at line 102 of file desktoputils.cpp.

## ◆ openLocalFileOrDir()

bool QtUtilities::openLocalFileOrDir | ( | const QString & | path | ) |

Shows the specified file or directory using the default file browser.

Remarks
  - The specified path must not be specified as URL. (The conversion to a URL suitable for QDesktopServices::openUrl() is the main purpose of this function).
  - The Qt documentation suggests to use QDesktopServices::openUrl(QUrl("file:///C:/Documents and Settings/All Users/Desktop", QUrl::TolerantMode)); under Windows. However, that does not work if the path contains a '#'. It is also better to use QUrl::DecodedMode to prevent QUrl from interpreting any of the paths characters in a special way.
  - Tries to open the path via the activity method openPath() under Android so that method can be implemented to override the behavior if needed. The method must take a string and return a boolean. If it does not exist the usual QDesktopServices::openUrl() is done.

Definition at line 37 of file desktoputils.cpp.

## ◆ operator<<()

QDBusArgument & QtUtilities::operator<< | ( | QDBusArgument & | argument,
|  | const NotificationImage & | img )

Definition at line 87 of file dbusnotification.cpp.

## ◆ operator>>()

const QDBusArgument & QtUtilities::operator>> | ( | const QDBusArgument & | argument,
|  | NotificationImage & | img )

Definition at line 95 of file dbusnotification.cpp.

## ◆ qstringFromStdStringView()

QString QtUtilities::qstringFromStdStringView | ( | std::string_view | stringView | ) |
| inline

Definition at line 40 of file conversion.h.

## ◆ saveSettingsWithLogging()

void QtUtilities::saveSettingsWithLogging | ( | QSettings & | settings | ) |

Saves settings and logs a corresponding message if the env variable QT_DEBUG_SETTINGS is set.

Definition at line 474 of file resources.cpp.

## ◆ setupCommonQtApplicationAttributes()

void QtUtilities::setupCommonQtApplicationAttributes | ( |  | ) |

Sets Qt application attributes which are commonly used within my Qt applications.

Remarks
  - So far this enables High-DPI support.
  - The exact attributes are unspecified and might change to whatever makes sense in the future.

Definition at line 389 of file resources.cpp.

## ◆ splitRef()

template<class... SplitArgs>

auto QtUtilities::splitRef | ( | const QString & | str,
|  | SplitArgs &&... | args )
| inline

Splits str into QStringViews, QStringRefs or QStrings depending on the Qt version.

Definition at line 70 of file compat.h.

## ◆ toNativeFileName()

QByteArray QtUtilities::toNativeFileName | ( | const QString & | fileName | ) |
| inline

Definition at line 13 of file conversion.h.