Class: QgsScaleComboBox

A combobox which lets the user select map scale from predefined list and highlights nearest to current scale value.

Class Hierarchy

Base classes

QComboBox
QWidget
QObject
QPaintDevice

Enums

RatioMode

Scale ratio modes.

Methods

allowNull	Returns True if the combobox can be set to a NULL value.
isNull	Returns True if the combo box is currently set to a "null" value.
minScale	Returns the minimum scale, or 0 if no minimum scale set.
ratioMode	Returns the ratio mode for the scale.
scale	Returns the selected scale as a double.
scaleString	Returns the selected scale as a string, e.g. "1:150".
setAllowNull	Sets whether the scale combobox can be set to a NULL value.
setMinScale	Set the minimum allowed scale.
setNull	Sets the combo box to the null value.
setPredefinedScales	Sets the list of predefined scales to show in the combobox.
setRatioMode	Sets the ratio mode for the scale.
setScale	Set the selected scale from a double.
setScaleString	Set the selected scale from a string, e.g. "1:150".
updateScales	Sets the list of predefined scales to show in the combobox.

Static Methods

toDouble	Helper function to convert a scale string to double.
toString	Helper function to convert a scale double to scale string.

Signals

ratioModeChanged	Emitted when the ratio mode for the widget is changed.
scaleChanged	Emitted when user has finished editing/selecting a new scale.

class qgis.gui.QgsScaleComboBox

Bases: QComboBox

__init__(parent: QWidget | None = None)

Constructor for QgsScaleComboBox.

Parameters:

parent (Optional[QWidget] = None)

class RatioMode(*values)

Bases: IntEnum

Scale ratio modes.

Added in version 4.0.

• ForceUnitNumerator: Default mode, forces the scale numerator to be 1, e.g. “1:1000”

• Flexible: Allows numerator values other than 1, e.g: “2:3”.

Flexible = 1

ForceUnitNumerator = 0

allowNull(self) → bool

Returns True if the combobox can be set to a NULL value.

See also

setAllowNull()

See also

isNull()

See also

setNull()

Added in version 3.8.

Return type:

bool

isNull(self) → bool

Returns True if the combo box is currently set to a “null” value.

See also

setAllowNull()

See also

setNull()

Added in version 3.8.

Return type:

bool

minScale(self) → float

Returns the minimum scale, or 0 if no minimum scale set. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. Any scale lower than the minimum scale will automatically be converted to the minimum scale. Except for 0 which is always allowed.

Return type:

float

ratioMode(self) → QgsScaleComboBox.RatioMode

Returns the ratio mode for the scale.

See also

setRatioMode()

Added in version 4.0.

Return type:

QgsScaleComboBox.RatioMode

signal ratioModeChanged(mode: QgsScaleComboBox.RatioMode)

Emitted when the ratio mode for the widget is changed.

Added in version 4.0.

Parameters:

mode (QgsScaleComboBox.RatioMode)

scale(self) → float

Returns the selected scale as a double. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

See also

setScale()

Return type:

float

signal scaleChanged(scale: float)

Emitted when user has finished editing/selecting a new scale. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

Parameters:

scale (float)

scaleString(self) → str

Returns the selected scale as a string, e.g. “1:150”.

See also

setScaleString()

Return type:

str

setAllowNull(self, allowNull: bool)

Sets whether the scale combobox can be set to a NULL value.

See also

allowNull()

See also

isNull()

See also

setNull()

Added in version 3.8.

Parameters:

allowNull (bool)

setMinScale(self, scale: float)

Set the minimum allowed scale. Set to 0 to disable the minimum scale. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. Any scale lower than the minimum scale will automatically be converted to the minimum scale. Except for 0 which is always allowed.

Parameters:

scale (float)

setNull(self)

Sets the combo box to the null value.

This only has an effect if allowNull() is True.

See also

allowNull()

See also

isNull()

Added in version 3.8.

setPredefinedScales(self, scales: Iterable[float])

Sets the list of predefined scales to show in the combobox. List elements are expected to be scale denominators, e.g. 1000.0 for a 1:1000 map.

If scales is empty then the default user scale options will be used instead.

Added in version 3.38.

Parameters:

scales (Iterable[float])

setRatioMode(self, mode: QgsScaleComboBox.RatioMode)

Sets the ratio mode for the scale.

See also

ratioMode()

Added in version 4.0.

Parameters:

mode (QgsScaleComboBox.RatioMode)

setScale(self, scale: float)

Set the selected scale from a double. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

See also

scale()

Parameters:

scale (float)

setScaleString(self, string: str | None) → bool

Set the selected scale from a string, e.g. “1:150”.

See also

scaleString()

Parameters:

string (Optional[str])

Return type:

bool

static toDouble(string: str | None)

Helper function to convert a scale string to double. The returned value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. If specified, ok will be set to True if the string was successfully interpreted as a scale.

See also

toString()

Parameters:

string (Optional[str]) -> (float)

static toString(scale: float, mode: QgsScaleComboBox.RatioMode = QgsScaleComboBox.RatioMode.ForceUnitNumerator) → str

Helper function to convert a scale double to scale string.

The returned string will be rounded (e.g. 1:1000, not 1:1000.345).

Parameters:

• scale (float) – scale value indicating the scale denominator, e.g. 1000.0 for a 1:1000 map.

• mode (QgsScaleComboBox.RatioMode = QgsScaleComboBox.RatioMode.ForceUnitNumerator) – ratio mode (since QGIS 4.0)

See also

toDouble()

Return type:

str

updateScales(self, scales: Iterable[str | None] = [])

Sets the list of predefined scales to show in the combobox. List elements are expected to be valid scale strings, such as “1:1000000”.

Parameters:

scales (Iterable[Optional[str]] = [])