Class: QgsLayoutItemScaleBar

A layout item subclass for scale bars.

Class Hierarchy

Base classes

QgsLayoutItem	Base class for graphical items within a QgsLayout.
QgsLayoutObject	A base class for objects which belong to a layout.
QObject
QgsExpressionContextGenerator	Abstract interface for generating an expression context.
QGraphicsRectItem
QAbstractGraphicsShapeItem
QGraphicsItem
QgsLayoutUndoObjectInterface	Interface for layout objects which support undo/redo commands.

class qgis.core.QgsLayoutItemScaleBar

Bases: QgsLayoutItem

__init__(layout: QgsLayout | None)

Constructor for QgsLayoutItemScaleBar, with the specified parent layout.

Parameters:

layout (Optional[QgsLayout])

alignment(self) → Qgis.ScaleBarAlignment

Returns the scalebar alignment.

See also

setAlignment()

Return type:

Qgis.ScaleBarAlignment

alternateFillSymbol(self) → QgsFillSymbol | None

Returns the secondary fill symbol used to render the scalebar (only used for some scalebar types).

Ownership is not transferred.

See also

setAlternateFillSymbol()

See also

fillSymbol()

Added in version 3.14.

Return type:

Optional[QgsFillSymbol]

applyDefaultRendererSettings(self, renderer: QgsScaleBarRenderer | None) → bool

Applies any default settings relating to the specified renderer to the item.

Returns True if settings were applied.

Added in version 3.14.

Parameters:

renderer (Optional[QgsScaleBarRenderer])

Return type:

bool

applyDefaultSettings(self)

Applies the default scalebar settings to the scale bar.

See also

applyDefaultSize()

applyDefaultSize(self, units: Qgis.DistanceUnit = Qgis.DistanceUnit.Meters)

Applies the default size to the scale bar (scale bar 1/5 of map item width)

See also

applyDefaultSettings()

Parameters:

units (Qgis.DistanceUnit = Qgis.DistanceUnit.Meters)

boxContentSpace(self) → float

Returns the spacing (margin) between the scalebar box and content in millimeters.

See also

setBoxContentSpace()

Return type:

float

brush(self) → QBrush

Returns the primary brush for the scalebar.

Return type:

QBrush

Returns:

QBrush used for filling the scalebar

See also

brush2()

See also

pen()

Deprecated since version 3.40: Use fillSymbol() instead.

brush2(self) → QBrush

Returns the secondary brush for the scalebar. This is used for alternating color style scalebars, such as single and double box styles.

Return type:

QBrush

Returns:

QBrush used for secondary color areas

See also

brush()

Deprecated since version 3.40: Use alternateFillSymbol() instead.

static create(layout: QgsLayout | None) → QgsLayoutItemScaleBar | None

Returns a new scale bar item for the specified layout.

The caller takes responsibility for deleting the returned object.

Parameters:

layout (Optional[QgsLayout])

Return type:

Optional[QgsLayoutItemScaleBar]

divisionLineSymbol(self) → QgsLineSymbol | None

Returns the line symbol used to render the scalebar divisions (only used for some scalebar types).

Ownership is not transferred.

See also

setDivisionLineSymbol()

See also

lineSymbol()

See also

subdivisionLineSymbol()

Added in version 3.14.

Return type:

Optional[QgsLineSymbol]

fillColor(self) → QColor

Returns the color used for fills in the scalebar.

See also

setFillColor()

See also

fillColor2()

Deprecated since version 3.40: Use fillSymbol() instead.

Return type:

QColor

fillColor2(self) → QColor

Returns the secondary color used for fills in the scalebar.

See also

setFillColor2()

See also

fillColor()

Deprecated since version 3.40: Use alternateFillSymbol() instead.

Return type:

QColor

fillSymbol(self) → QgsFillSymbol | None

Returns the primary fill symbol used to render the scalebar (only used for some scalebar types).

Ownership is not transferred.

See also

setFillSymbol()

See also

alternateFillSymbol()

Added in version 3.14.

Return type:

Optional[QgsFillSymbol]

font(self) → QFont

Returns the font used for drawing text in the scalebar.

See also

setFont()

Deprecated since version 3.40: Use textFormat() instead.

Return type:

QFont

fontColor(self) → QColor

Returns the color used for drawing text in the scalebar.

See also

setFontColor()

See also

font()

Deprecated since version 3.40: Use textFormat() instead.

Return type:

QColor

guessUnits(self) → Qgis.DistanceUnit

Attempts to guess the most reasonable unit choice for the scalebar, given the current linked map’s scale.

This method also considers the linked map’s CRS, in order to determine if metric or imperial units are more appropriate.

Return type:

Qgis.DistanceUnit

height(self) → float

Returns the scalebar height (in millimeters).

See also

setHeight()

Return type:

float

labelBarSpace(self) → float

Returns the spacing (in millimeters) between labels and the scalebar.

See also

setLabelBarSpace()

Return type:

float

labelHorizontalPlacement(self) → Qgis.ScaleBarDistanceLabelHorizontalPlacement

Returns the horizontal placement of text labels.

See also

setLabelHorizontalPlacement()

Added in version 3.10.

Return type:

Qgis.ScaleBarDistanceLabelHorizontalPlacement

labelVerticalPlacement(self) → Qgis.ScaleBarDistanceLabelVerticalPlacement

Returns the vertical placement of text labels.

See also

setLabelVerticalPlacement()

Added in version 3.10.

Return type:

Qgis.ScaleBarDistanceLabelVerticalPlacement

lineCapStyle(self) → Qt.PenCapStyle

Returns the cap style used for drawing lines in the scalebar.

See also

setLineCapStyle()

Deprecated since version 3.40: Use lineSymbol() instead.

Return type:

Qt.PenCapStyle

lineColor(self) → QColor

Returns the color used for lines in the scalebar.

See also

setLineColor()

Deprecated since version 3.40: Use lineSymbol() instead.

Return type:

QColor

lineJoinStyle(self) → Qt.PenJoinStyle

Returns the join style used for drawing lines in the scalebar.

See also

setLineJoinStyle()

Deprecated since version 3.40: Use lineSymbol() instead.

Return type:

Qt.PenJoinStyle

lineSymbol(self) → QgsLineSymbol | None

Returns the line symbol used to render the scalebar (only used for some scalebar types).

Ownership is not transferred.

See also

setLineSymbol()

See also

divisionLineSymbol()

See also

subdivisionLineSymbol()

Added in version 3.14.

Return type:

Optional[QgsLineSymbol]

lineWidth(self) → float

Returns the line width in millimeters for lines in the scalebar.

See also

setLineWidth()

Deprecated since version 3.40: Use lineSymbol() instead.

Return type:

float

linkedMap(self) → QgsLayoutItemMap | None

Returns the map item linked to the scalebar.

See also

setLinkedMap()

Return type:

Optional[QgsLayoutItemMap]

mapUnitsPerScaleBarUnit(self) → float

Returns the number of map units per scale bar unit used by the scalebar.

See also

setMapUnitsPerScaleBarUnit()

Return type:

float

maximumBarWidth(self) → float

Returns the maximum width (in millimeters) for scale bar segments. This property is only effective if the segmentSizeMode() is set to SegmentSizeFitWidth.

See also

segmentSizeMode()

See also

setMaximumBarWidth()

See also

minimumBarWidth()

Return type:

float

method(self) → Qgis.ScaleCalculationMethod

Returns the scale calculation method, which determines how the bar’s scale will be calculated.

See also

setMethod()

Added in version 3.40.

Return type:

Qgis.ScaleCalculationMethod

minimumBarWidth(self) → float

Returns the minimum width (in millimeters) for scale bar segments. This property is only effective if the segmentSizeMode() is set to SegmentSizeFitWidth.

See also

segmentSizeMode()

See also

setMinimumBarWidth()

See also

maximumBarWidth()

Return type:

float

numberOfSegments(self) → int

Returns the number of segments included in the scalebar.

See also

setNumberOfSegments()

See also

numberOfSegmentsLeft()

Return type:

int

numberOfSegmentsLeft(self) → int

Returns the number of segments included in the left part of the scalebar.

See also

setNumberOfSegmentsLeft()

See also

numberOfSegments()

Return type:

int

numberOfSubdivisions(self) → int

Returns the number of subdivisions for segments included in the right part of the scalebar (only used for some scalebar types).

Note

The number of subdivisions represents the number of subdivision segments, not the number of subdivision lines. E.g. if the number is 1 then NO subdivision lines will be shown.

See also

setNumberOfSubdivisions()

Added in version 3.14.

Return type:

int

numericFormat(self) → QgsNumericFormat | None

Returns the numeric format used for numbers in the scalebar.

See also

setNumericFormat()

Added in version 3.12.

Return type:

Optional[QgsNumericFormat]

pen(self) → QPen

Returns the pen used for drawing outlines in the scalebar.

See also

brush()

Deprecated since version 3.40: Use lineSymbol() instead.

Return type:

QPen

resizeToMinimumWidth(self)

Resizes the scale bar to its minimum width, without changing the height.

segmentSizeMode(self) → Qgis.ScaleBarSegmentSizeMode

Returns the size mode for the scale bar segments.

See also

setSegmentSizeMode()

See also

minimumBarWidth()

See also

maximumBarWidth()

Return type:

Qgis.ScaleBarSegmentSizeMode

setAlignment(self, alignment: Qgis.ScaleBarAlignment)

Sets the scalebar alignment.

See also

alignment()

Parameters:

alignment (Qgis.ScaleBarAlignment)

setAlternateFillSymbol(self, symbol: QgsFillSymbol | None)

Sets the secondary fill symbol used to render the scalebar (only used for some scalebar types). Ownership of symbol is transferred to the scalebar.

See also

alternateFillSymbol()

See also

setFillSymbol()

Added in version 3.14.

Parameters:

symbol (Optional[QgsFillSymbol])

setBoxContentSpace(self, space: float)

Sets the space (margin) between the scalebar box and content in millimeters.

See also

boxContentSpace()

Parameters:

space (float)

setDivisionLineSymbol(self, symbol: QgsLineSymbol | None)

Sets the line symbol used to render the scalebar divisions (only used for some scalebar types). Ownership of symbol is transferred to the scalebar.

See also

divisionLineSymbol()

See also

setLineSymbol()

See also

setSubdivisionLineSymbol()

Added in version 3.14.

Parameters:

symbol (Optional[QgsLineSymbol])

setFillColor(self, color: QColor | Qt.GlobalColor)

Sets the color used for fills in the scalebar.

See also

fillColor()

See also

setFillColor2()

Deprecated since version 3.40: Use setFillSymbol() instead.

Parameters:

color (Union[QColor, Qt.GlobalColor])

setFillColor2(self, color: QColor | Qt.GlobalColor)

Sets the secondary color used for fills in the scalebar.

See also

fillColor2()

See also

setFillColor2()

Deprecated since version 3.40: Use setAlternateFillSymbol() instead.

Parameters:

color (Union[QColor, Qt.GlobalColor])

setFillSymbol(self, symbol: QgsFillSymbol | None)

Sets the primary fill symbol used to render the scalebar (only used for some scalebar types). Ownership of symbol is transferred to the scalebar.

See also

fillSymbol()

See also

setAlternateFillSymbol()

Added in version 3.14.

Parameters:

symbol (Optional[QgsFillSymbol])

setFont(self, font: QFont)

Sets the font used for drawing text in the scalebar.

See also

font()

Deprecated since version 3.40: Use setTextFormat() instead.

Parameters:

font (QFont)

setFontColor(self, color: QColor | Qt.GlobalColor)

Sets the color used for drawing text in the scalebar.

See also

fontColor()

See also

setFont()

Deprecated since version 3.40: Use setTextFormat() instead.

Parameters:

color (Union[QColor, Qt.GlobalColor])

setHeight(self, height: float)

Sets the scalebar height (in millimeters).

See also

height()

Parameters:

height (float)

setLabelBarSpace(self, space: float)

Sets the spacing (in millimeters) between labels and the scalebar.

See also

labelBarSpace()

Parameters:

space (float)

setLabelHorizontalPlacement(self, placement: Qgis.ScaleBarDistanceLabelHorizontalPlacement)

Sets the horizontal placement of text labels.

See also

labelHorizontalPlacement()

Added in version 3.10.

Parameters:

placement (Qgis.ScaleBarDistanceLabelHorizontalPlacement)

setLabelVerticalPlacement(self, placement: Qgis.ScaleBarDistanceLabelVerticalPlacement)

Sets the vertical placement of text labels.

See also

labelVerticalPlacement()

Added in version 3.10.

Parameters:

placement (Qgis.ScaleBarDistanceLabelVerticalPlacement)

setLineCapStyle(self, style: Qt.PenCapStyle)

Sets the cap style used when drawing the lines in the scalebar.

See also

lineCapStyle()

Deprecated since version 3.40: Use setLineSymbol() instead.

Parameters:

style (Qt.PenCapStyle)

setLineColor(self, color: QColor | Qt.GlobalColor)

Sets the color used for lines in the scalebar.

See also

lineColor()

Deprecated since version 3.40: Use setLineSymbol() instead.

Parameters:

color (Union[QColor, Qt.GlobalColor])

setLineJoinStyle(self, style: Qt.PenJoinStyle)

Sets the join style used when drawing the lines in the scalebar

See also

lineJoinStyle()

Deprecated since version 3.40: Use setLineSymbol() instead.

Parameters:

style (Qt.PenJoinStyle)

setLineSymbol(self, symbol: QgsLineSymbol | None)

Sets the line symbol used to render the scalebar (only used for some scalebar types). Ownership of symbol is transferred to the scalebar.

See also

lineSymbol()

See also

setDivisionLineSymbol()

See also

setSubdivisionLineSymbol()

Added in version 3.14.

Parameters:

symbol (Optional[QgsLineSymbol])

setLineWidth(self, width: float)

Sets the line width in millimeters for lines in the scalebar.

See also

lineWidth()

Deprecated since version 3.40: Use setLineSymbol() instead.

Parameters:

width (float)

setLinkedMap(self, map: QgsLayoutItemMap | None)

Sets the map item linked to the scalebar.

See also

linkedMap()

Parameters:

map (Optional[QgsLayoutItemMap])

setMapUnitsPerScaleBarUnit(self, units: float)

Sets the number of map units per scale bar unit used by the scalebar.

See also

mapUnitsPerScaleBarUnit()

Parameters:

units (float)

setMaximumBarWidth(self, maxWidth: float)

Sets the maximum width (in millimeters) for scale bar segments. This property is only effective if the segmentSizeMode() is set to SegmentSizeFitWidth.

See also

minimumBarWidth()

See also

setMinimumBarWidth()

See also

setSegmentSizeMode()

Parameters:

maxWidth (float)

setMethod(self, method: Qgis.ScaleCalculationMethod)

Sets the scale calculation method, which determines how the bar’s scale will be calculated.

See also

method()

Added in version 3.40.

Parameters:

method (Qgis.ScaleCalculationMethod)

setMinimumBarWidth(self, minWidth: float)

Sets the minimum width (in millimeters) for scale bar segments. This property is only effective if the segmentSizeMode() is set to SegmentSizeFitWidth.

See also

minimumBarWidth()

See also

setMaximumBarWidth()

See also

setSegmentSizeMode()

Parameters:

minWidth (float)

setNumberOfSegments(self, segments: int)

Sets the number of segments included in the scalebar.

See also

numberOfSegments()

See also

setNumberOfSegmentsLeft()

Parameters:

segments (int)

setNumberOfSegmentsLeft(self, segments: int)

Sets the number of segments included in the left part of the scalebar.

See also

numberOfSegmentsLeft()

See also

setNumberOfSegments()

Parameters:

segments (int)

setNumberOfSubdivisions(self, subdivisions: int)

Sets the number of subdivisions for segments included in the right part of the scalebar (only used for some scalebar types).

Note

The number of subdivisions represents the number of subdivision segments, not the number of subdivision lines. E.g. if the number is 1 then NO subdivision lines will be shown.

See also

numberOfSubdivisions()

Added in version 3.14.

Parameters:

subdivisions (int)

setNumericFormat(self, format: QgsNumericFormat | None)

Sets the numeric format used for numbers in the scalebar.

Ownership of format is transferred to the scalebar.

See also

numericFormat()

Added in version 3.12.

Parameters:

format (Optional[QgsNumericFormat])

setSegmentSizeMode(self, mode: Qgis.ScaleBarSegmentSizeMode)

Sets the size mode for scale bar segments.

See also

segmentSizeMode()

See also

setMinimumBarWidth()

See also

setMaximumBarWidth()

Parameters:

mode (Qgis.ScaleBarSegmentSizeMode)

setStyle(self, name: str | None)

Sets the scale bar style by name.

The name parameter gives the (untranslated) style name. Possibilities are: ‘Single Box’, ‘Double Box’, ‘Line Ticks Middle’, ‘Line Ticks Down’, ‘Line Ticks Up’, ‘Stepped Line’, ‘Hollow’, ‘Numeric’.

See also

style()

Parameters:

name (Optional[str])

setSubdivisionLineSymbol(self, symbol: QgsLineSymbol | None)

Sets the line symbol used to render the scalebar subdivisions (only used for some scalebar types). Ownership of symbol is transferred to the scalebar.

See also

subdivisionLineSymbol()

See also

setLineSymbol()

See also

setDivisionLineSymbol()

Added in version 3.14.

Parameters:

symbol (Optional[QgsLineSymbol])

setSubdivisionsHeight(self, height: float)

Sets the scalebar subdivisions height (in millimeters) for segments included in the right part of the scalebar (only used for some scalebar types).

See also

subdivisionsHeight()

Added in version 3.14.

Parameters:

height (float)

setTextFormat(self, format: QgsTextFormat)

Sets the text format used for drawing text in the scalebar.

See also

textFormat()

Added in version 3.2.

Parameters:

format (QgsTextFormat)

setUnitLabel(self, label: str | None)

Sets the label for units.

See also

unitLabel()

Parameters:

label (Optional[str])

setUnits(self, units: Qgis.DistanceUnit)

Sets the distance units used by the scalebar.

See also

units()

Parameters:

units (Qgis.DistanceUnit)

setUnitsPerSegment(self, units: float)

Sets the number of scalebar units per segment.

See also

unitsPerSegment()

Parameters:

units (float)

style(self) → str

Returns the scale bar style name.

See also

setStyle()

Return type:

str

subdivisionLineSymbol(self) → QgsLineSymbol | None

Returns the line symbol used to render the scalebar subdivisions (only used for some scalebar types).

Ownership is not transferred.

See also

setSubdivisionLineSymbol()

See also

lineSymbol()

See also

divisionLineSymbol()

Added in version 3.14.

Return type:

Optional[QgsLineSymbol]

subdivisionsHeight(self) → float

Returns the scalebar subdivisions height (in millimeters) for segments included in the right part of the scalebar (only used for some scalebar types).

See also

setSubdivisionsHeight()

Added in version 3.14.

Return type:

float

textFormat(self) → QgsTextFormat

Returns the text format used for drawing text in the scalebar.

See also

setTextFormat()

Added in version 3.2.

Return type:

QgsTextFormat

unitLabel(self) → str

Returns the label for units.

See also

setUnitLabel()

Return type:

str

units(self) → Qgis.DistanceUnit

Returns the distance units used by the scalebar.

See also

setUnits()

Return type:

Qgis.DistanceUnit

unitsPerSegment(self) → float

Returns the number of scalebar units per segment.

See also

setUnitsPerSegment()

Return type:

float

update(self)

Adjusts the scale bar box size and updates the item.