QgsGuiUtils Namespace Reference

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

Functions
void	addDockWidget (QMainWindow *window, Qt::DockWidgetArea area, QDockWidget *dockwidget)
	Add a dock widget to a main window.
void	addTabifiedDockWidget (QMainWindow *window, Qt::DockWidgetArea area, QDockWidget *dockWidget, const QStringList &tabifyWith=QStringList(), bool raiseTab=false)
	Add a dock widget to the given area and tabify it (if other dock widgets exist in the same area).
QString	createFileFilter_ (QString const &format)
	Create file filters suitable for use with QFileDialog.
QString	createFileFilter_ (QString const &longName, QString const &glob)
	Convenience function for readily creating file filters.
QString	createWidgetKey (QWidget *widget, const QString &keyName=QString())
	Creates a key for the given widget that can be used to store related data in settings.
QString	displayValueWithMaximumDecimals (const Qgis::DataType dataType, const double value, bool displayTrailingZeroes=false)
	Returns a localized string representation of the value with the appropriate number of decimals supported by the dataType.
QFont	getFont (bool &ok, const QFont &initial, const QString &title=QString())
	Show font selection dialog.
QPair< QString, QString > GUI_EXPORT	getSaveAsImageName (QWidget *parent, const QString &message, const QString &defaultFilename=QString())
	A helper function to get an image name from the user.
QSize	iconSize (bool dockableToolbar=false)
	Returns the user-preferred size of a window's toolbar icons.
bool	isNonStandardGeoPackageGeometryType (Qgis::WkbType wkbType)
	Returns true if the given wkbType is a non-standard GeoPackage geometry type (PolyhedralSurface, TIN, or Triangle).
bool GUI_EXPORT	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.
QSize	panelIconSize (QSize size)
	Returns dockable panel toolbar icon width based on the provided window toolbar width.
bool	restoreGeometry (QWidget *widget, const QString &keyName=QString())
	Restore the wigget geometry from settings.
void	saveGeometry (QWidget *widget, const QString &keyName=QString())
	Save the wigget geometry into settings.
int	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.
int	significantDigits (const Qgis::DataType rasterDataType)
	Returns the maximum number of significant digits a for the given rasterDataType.
bool	warnAboutNonStandardGeoPackageGeometryType (Qgis::WkbType wkbType, QWidget *parent, const QString &dialogTitle, bool showDialog=true, bool *isNonStandard=nullptr)
	Checks if the given wkbType is a non-standard GeoPackage geometry type (PolyhedralSurface, TIN, or Triangle) and displays a warning message box asking the user if they want to continue.

Variables
constexpr double	CANVAS_MAGNIFICATION_MAX = 16.0
	Maximum magnification level allowed in map canvases.
constexpr double	CANVAS_MAGNIFICATION_MIN = 0.1
	Minimum magnification level allowed in map canvases.

Detailed Description

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

Note

not available in Python bindings

Function Documentation

addDockWidget()

GUI_EXPORT void QgsGuiUtils::addDockWidget	(	QMainWindow *	window,
		Qt::DockWidgetArea	area,
		QDockWidget *	dockwidget )

Add a dock widget to a main window.

After adding the dock widget to the UI (by delegating to the QMainWindow parent class, it will also add it to the View menu list of docks, if the window has one.

Since

QGIS 4.2

Definition at line 394 of file qgsguiutils.cpp.

addTabifiedDockWidget()

GUI_EXPORT void QgsGuiUtils::addTabifiedDockWidget	(	QMainWindow *	window,
		Qt::DockWidgetArea	area,
		QDockWidget *	dockWidget,
		const QStringList &	tabifyWith = QStringList(),
		bool	raiseTab = false )

Add a dock widget to the given area and tabify it (if other dock widgets exist in the same area).

The new tab will be below other tabs unless raiseTab is passed as true.

tabifyWith is a list of dock widget object names, ordered by priority, with which the new dock widget should be tabified. Only the first matching object name will be picked. If none of the given object names is found in that area (or if tabifyWith is not given at all), the new dock widget will be created anyways, but its location within that area will be unpredictable.

Since

QGIS 4.2

Definition at line 412 of file qgsguiutils.cpp.

createFileFilter_() [1/2]

QString GUI_EXPORT 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)"

Definition at line 212 of file qgsguiutils.cpp.

createFileFilter_() [2/2]

QString GUI_EXPORT 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.

Definition at line 207 of file qgsguiutils.cpp.

createWidgetKey()

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.

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

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.

Definition at line 249 of file qgsguiutils.cpp.

displayValueWithMaximumDecimals()

QString GUI_EXPORT QgsGuiUtils::displayValueWithMaximumDecimals	(	const Qgis::DataType	dataType,
		const double	value,
		bool	displayTrailingZeroes = false )

Returns a localized string representation of the value with the appropriate number of decimals supported by the dataType.

Trailing zeroes after decimal separator are not show unless displayTrailingZeroes is set. Note that for floating point types the number of decimals may exceed the actual internal precision because the precision is always calculated on the mantissa and the conversion to string interprets the precision as decimal places.

Since

QGIS 3.16

Definition at line 301 of file qgsguiutils.cpp.

getFont()

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

Show font selection dialog.

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.

Parameters

ok	true on ok, false on cancel
initial	initial font
title	optional dialog title

Returns

QFont the selected fon

Definition at line 219 of file qgsguiutils.cpp.

getSaveAsImageName()

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.

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

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

Definition at line 97 of file qgsguiutils.cpp.

iconSize()

QSize GUI_EXPORT QgsGuiUtils::iconSize

(

bool

dockableToolbar = false

)

Returns the user-preferred size of a window's toolbar icons.

Parameters

dockableToolbar

If set to true, the icon size will be returned for dockable window panel's toolbars.

Returns

a QSize object representing an icon's width and height.

Since

QGIS 3.8

Definition at line 273 of file qgsguiutils.cpp.

isNonStandardGeoPackageGeometryType()

bool GUI_EXPORT QgsGuiUtils::isNonStandardGeoPackageGeometryType

(

Qgis::WkbType

wkbType

)

Returns true if the given wkbType is a non-standard GeoPackage geometry type (PolyhedralSurface, TIN, or Triangle).

Parameters

wkbType

the geometry type to check

Returns

true if the geometry type is non-standard for GeoPackage

Since

QGIS 4.0

Definition at line 355 of file qgsguiutils.cpp.

openFilesRememberingFilter()

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

Note

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

Definition at line 41 of file qgsguiutils.cpp.

panelIconSize()

QSize GUI_EXPORT QgsGuiUtils::panelIconSize

(

QSize

size

)

Returns dockable panel toolbar icon width based on the provided window toolbar width.

Parameters

size	Icon size from which the output size will be derived from.

Returns

a QSize object representing an icon's width and height.

Since

QGIS 3.8

Definition at line 287 of file qgsguiutils.cpp.

restoreGeometry()

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

Restore the wigget geometry from settings.

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

Parameters

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

Returns

true if the geometry was restored.

Definition at line 242 of file qgsguiutils.cpp.

saveGeometry()

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

Save the wigget geometry into settings.

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

Parameters

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

Definition at line 235 of file qgsguiutils.cpp.

scaleIconSize()

int GUI_EXPORT 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.

Since

QGIS 3.6

Definition at line 268 of file qgsguiutils.cpp.

significantDigits()

int GUI_EXPORT QgsGuiUtils::significantDigits

(

const Qgis::DataType

rasterDataType

)

Returns the maximum number of significant digits a for the given rasterDataType.

Since

QGIS 3.16

Definition at line 320 of file qgsguiutils.cpp.

warnAboutNonStandardGeoPackageGeometryType()

bool GUI_EXPORT QgsGuiUtils::warnAboutNonStandardGeoPackageGeometryType	(	Qgis::WkbType	wkbType,
		QWidget *	parent,
		const QString &	dialogTitle,
		bool	showDialog = true,
		bool *	isNonStandard = nullptr )

Checks if the given wkbType is a non-standard GeoPackage geometry type (PolyhedralSurface, TIN, or Triangle) and displays a warning message box asking the user if they want to continue.

Parameters

wkbType	the geometry type to check
parent	the parent widget for the message box (can be nullptr)
dialogTitle	the title for the warning dialog
showDialog	if false, the dialog will not be shown and the function will return true for non-standard types (useful for automated testing)
isNonStandard	if not nullptr, will be set to true if the geometry type is non-standard for GeoPackage, false otherwise

Returns

true if the geometry type is standard, or if non-standard and the user chose to continue; false if non-standard and the user chose to cancel

Since

QGIS 4.0

Definition at line 361 of file qgsguiutils.cpp.

Variable Documentation

CANVAS_MAGNIFICATION_MAX

double QgsGuiUtils::CANVAS_MAGNIFICATION_MAX = 16.0

constexpr

Maximum magnification level allowed in map canvases.

See also

CANVAS_MAGNIFICATION_MAX

Definition at line 71 of file qgsguiutils.h.

CANVAS_MAGNIFICATION_MIN

double QgsGuiUtils::CANVAS_MAGNIFICATION_MIN = 0.1

constexpr

Minimum magnification level allowed in map canvases.

See also

CANVAS_MAGNIFICATION_MAX

Definition at line 64 of file qgsguiutils.h.