QgsGuiUtils namespace

The QgsGuiUtils namespace contains constants and helper functions used throughout the QGIS GUI.

Reference
- Functions
- Variables

Functions

auto createFileFilter_(QString const& longName, QString const& glob) -> QString: Convenience function for readily creating file filters.
auto createFileFilter_(QString const& format) -> QString: Create file filters suitable for use with QFileDialog.
auto createWidgetKey(QWidget* widget, const QString& keyName = QString()) -> QString: Creates a key for the given widget that can be used to store related data in settings.
auto getFont(bool& ok, const QFont& initial, const QString& title = QString()) -> QFont: Show font selection dialog.
auto getSaveAsImageName(QWidget* parent, const QString& message, const QString& defaultFilename = QString()) -> QPair<QString, QString> GUI_EXPORT: A helper function to get an image name from the user.
auto openFilesRememberingFilter(QString const& filterName, QString const& filters, QStringList& selectedFiles, QString& enc, QString& title, bool cancelAll = false) -> bool GUI_EXPORT: Open files, preferring to have the default file selector be the last one used, if any; also, prefer to start in the last directory associated with filterName.
auto restoreGeometry(QWidget* widget, const QString& keyName = QString()) -> bool: Restore the wigget geometry from settings.
void saveGeometry(QWidget* widget, const QString& keyName = QString()): Save the wigget geometry into settings.
auto scaleIconSize(int standardSize) -> int: Scales an icon size to compensate for display pixel density, making the icon size hi-dpi friendly, whilst still resulting in pixel-perfect sizes for low-dpi displays.

Variables

double CANVAS_MAGNIFICATION_MAX constexpr: Maximum magnification level allowed in map canvases.
double CANVAS_MAGNIFICATION_MIN constexpr: Minimum magnification level allowed in map canvases.
static const Qt::WindowFlags ModalDialogFlags: /var ModalDialogFlags /brief Flags used to create a modal dialog (adapted from QMessageBox).

Function documentation

QString QgsGuiUtils::createFileFilter_(QString const& longName, QString const& glob)

Convenience function for readily creating file filters.

Given a long name for a file filter and a regular expression, return a file filter string suitable for use in a QFileDialog::OpenFiles() call. The regular express, glob, will have both all lower and upper case versions added.

QString QgsGuiUtils::createFileFilter_(QString const& format)

Create file filters suitable for use with QFileDialog.

Parameters
format	extension e.g. "png"
Returns	QString e.g. "PNG format (.png, .PNG)"

QString QgsGuiUtils::createWidgetKey(QWidget* widget, const QString& keyName = QString())

Creates a key for the given widget that can be used to store related data in settings.

Parameters
widget	The widget to make the key from.
keyName	Override for objectName() if needed. If not set will use objectName()
Returns	A key name that can be used for the widget in settings.

Will use objectName() or class name if objectName() is not set. Can be overridden using keyName.

QFont QgsGuiUtils::getFont(bool& ok, const QFont& initial, const QString& title = QString())

Show font selection dialog.

Parameters
ok	true on ok, false on cancel
initial	initial font
title	optional dialog title
Returns	QFont the selected fon

It is strongly recommended that you do not use this method, and instead use the standard QgsFontButton widget to allow users consistent font selection behavior.

QPair<QString, QString> GUI_EXPORT QgsGuiUtils::getSaveAsImageName(QWidget* parent, const QString& message, const QString& defaultFilename = QString())

A helper function to get an image name from the user.

Parameters
parent	widget that should act as the parent for the file dialog
message	the message to display to the user
defaultFilename	default file name (empty by default)
Returns	QPair<QString, QString> where first is the file name and second is the file type

It will nicely provide filters with all available writable image formats.

bool GUI_EXPORT QgsGuiUtils::openFilesRememberingFilter(QString const& filterName, QString const& filters, QStringList& selectedFiles, QString& enc, QString& title, bool cancelAll = false)

Open files, preferring to have the default file selector be the last one used, if any; also, prefer to start in the last directory associated with filterName.

Parameters
filterName	the name of the filter; used for persistent store key
filters	the file filters used for QFileDialog
selectedFiles	string list of selected files; will be empty if none selected
enc	encoding?
title	the title for the dialog
cancelAll	add button to cancel further requests

Stores persistent settings under /UI/. The sub-keys will be filterName and filterName + "Dir".

Opens dialog on last directory associated with the filter name, or the current working directory if this is the first time invoked with the current filter name.

This method returns true if cancel all was clicked, otherwise false

bool QgsGuiUtils::restoreGeometry(QWidget* widget, const QString& keyName = QString())

Restore the wigget geometry from settings.

Parameters
widget	The widget to restore.
keyName	Override for objectName() if needed.
Returns	True if the geometry was restored.

Will use the objetName() of the widget and if empty, or keyName is set, will use keyName to save state into settings.

void QgsGuiUtils::saveGeometry(QWidget* widget, const QString& keyName = QString())

Save the wigget geometry into settings.

Parameters
widget	The widget to save.
keyName	Override for objectName() if needed.

Will use the objectName() of the widget and if empty, or keyName is set, will use keyName to save state into settings.

int QgsGuiUtils::scaleIconSize(int standardSize)

Scales an icon size to compensate for display pixel density, making the icon size hi-dpi friendly, whilst still resulting in pixel-perfect sizes for low-dpi displays.

standardSize should be set to a standard icon size, e.g. 16, 24, 48, etc.

Variable documentation

double QgsGuiUtils::CANVAS_MAGNIFICATION_MAX constexpr

Maximum magnification level allowed in map canvases.

double QgsGuiUtils::CANVAS_MAGNIFICATION_MIN constexpr

Minimum magnification level allowed in map canvases.

static const Qt::WindowFlags QgsGuiUtils::ModalDialogFlags

/var ModalDialogFlags /brief Flags used to create a modal dialog (adapted from QMessageBox).

Using these flags for all modal dialogs throughout QGIS ensures that for platforms such as the Mac where modal and modeless dialogs have different looks, QGIS modal dialogs will look the same as Qt modal dialogs and all modal dialogs will look distinct from modeless dialogs. Although not the standard Mac modal look, it does lack the minimize control which makes sense only for modeless dislogs.

The Qt3 method of creating a true Mac modal dialog is deprecated in Qt4 and should not be used due to conflicts with QMessageBox style dialogs.

Qt::WindowMaximizeButtonHint is included but will be ignored if the dialog is a fixed size and does not have a size grip.