Class: QgsUnitSelectionWidget

A widget displaying a combobox allowing the user to choose between various display units, such as millimeters or map units.

If the user chooses map units, a button appears allowing adjustment of minimum and maximum scaling.

Class Hierarchy

Inheritance diagram of qgis.gui.QgsUnitSelectionWidget

Base classes

QWidget

QObject

QPaintDevice

Methods

getMapUnitScale

Returns the map unit scale

getUnit

Gets the selected unit index

setMapCanvas

Sets the map canvas associated with the widget.

setMapUnitScale

Sets the map unit scale

setShowMapScaleButton

Sets whether the widget can show the map scale button when the Map Units option is selected.

setUnit

Sets the selected unit

setUnitIndex

Sets the selected unit index

setUnits

Sets the units which the user can choose from in the combobox.

showMapScaleButton

Returns True if the widget can show the map scale button when the Map Units option is selected.

unit

Returns the current predefined selected unit (if applicable).

Signals

changed

Emitted when the selected unit is changed, or the definition of the map unit scale is changed.

class qgis.gui.QgsUnitSelectionWidget[source]

Bases: QWidget

__init__(parent: QWidget | None = None)

Constructor for QgsUnitSelectionWidget.

Parameters:

parent (Optional[QWidget] = None) – parent widget

signal changed[source]

Emitted when the selected unit is changed, or the definition of the map unit scale is changed.

getMapUnitScale(self) QgsMapUnitScale[source]

Returns the map unit scale

Return type:

QgsMapUnitScale

getUnit(self) int[source]

Gets the selected unit index

Return type:

int

setMapCanvas(self, canvas: QgsMapCanvas | None)[source]

Sets the map canvas associated with the widget. This allows the widget to retrieve the current map scale from the canvas.

Parameters:

canvas (Optional[QgsMapCanvas]) – map canvas

setMapUnitScale(self, scale: QgsMapUnitScale)[source]

Sets the map unit scale

Parameters:

scale (QgsMapUnitScale)

setShowMapScaleButton(self, show: bool)[source]

Sets whether the widget can show the map scale button when the Map Units option is selected.

Added in version 3.22.

Parameters:

show (bool)

setUnit(self, unit: Qgis.RenderUnit)[source]

Sets the selected unit

Parameters:

unit (Qgis.RenderUnit) – predefined unit to set as current

setUnitIndex(self, unitIndex: int)

Sets the selected unit index

Parameters:

unitIndex (int) – index of unit to set as current

setUnits(self, units: Iterable[str | None], mapUnitIdx: int)[source]

Sets the units which the user can choose from in the combobox.

Parameters:
  • units (Iterable[Optional[str]]) – list of strings for custom units to display in the widget

  • mapUnitIdx (int) – specifies which entry corresponds to the map units, or -1 if none

setUnits(self, units: Iterable[Qgis.RenderUnit])[source]

Sets the units which the user can choose from in the combobox. Clears any existing units.

Parameters:

units (Iterable[Qgis.RenderUnit]) – list of valid units

showMapScaleButton(self) bool[source]

Returns True if the widget can show the map scale button when the Map Units option is selected.

Added in version 3.22.

Return type:

bool

unit(self) Qgis.RenderUnit[source]

Returns the current predefined selected unit (if applicable).

Return type:

Qgis.RenderUnit

Returns:

selected output unit, or QgsUnitTypes.RenderUnknownUnit if the widget was populated with custom unit types