Class: QgsScaleBarSettings¶

Stores the appearance and layout settings for scalebar drawing with QgsScaleBarRenderer.

Enums

`Alignment`	alias of `ScaleBarAlignment`
`LabelHorizontalPlacement`	alias of `ScaleBarDistanceLabelHorizontalPlacement`
`LabelVerticalPlacement`	alias of `ScaleBarDistanceLabelVerticalPlacement`
`SegmentSizeMode`	alias of `ScaleBarSegmentSizeMode`

Methods

`alignment`	Returns the scalebar alignment.
`alternateFillSymbol`	Returns the secondary fill symbol used to render the scalebar (only used for some scalebar types).
`boxContentSpace`	Returns the spacing (margin) between the scalebar box and content in millimeters.
`brush`	Returns the primary brush used for filling the scalebar.
`brush2`	Returns the secondary brush for the scalebar.
`divisionLineSymbol`	Returns the line symbol used to render the scalebar divisions (only used for some scalebar types).
`fillColor`	Returns the color used for fills in the scalebar.
`fillColor2`	Returns the secondary color used for fills in the scalebar.
`fillSymbol`	Returns the primary fill symbol used to render the scalebar (only used for some scalebar types).
`font`	Returns the font used for drawing text in the scalebar.
`fontColor`	Returns the color used for drawing text in the scalebar.
`height`	Returns the scalebar height (in millimeters).
`labelBarSpace`	Returns the spacing (in millimeters) between labels and the scalebar.
`labelHorizontalPlacement`	Returns the horizontal placement of text labels.
`labelVerticalPlacement`	Returns the vertical placement of text labels.
`lineCapStyle`	Returns the cap style used for drawing lines in the scalebar.
`lineColor`	Returns the color used for lines in the scalebar.
`lineJoinStyle`	Returns the join style used for drawing lines in the scalebar.
`lineSymbol`	Returns the line symbol used to render the scalebar (only used for some scalebar types).
`lineWidth`	Returns the line width in millimeters for lines in the scalebar.
`mapUnitsPerScaleBarUnit`	Returns the number of map units per scale bar unit used by the scalebar.
`maximumBarWidth`	Returns the maximum width (in millimeters) for scale bar segments.
`minimumBarWidth`	Returns the minimum width (in millimeters) for scale bar segments.
`numberOfSegments`	Returns the number of segments included in the scalebar.
`numberOfSegmentsLeft`	Returns the number of segments included in the left part of the scalebar.
`numberOfSubdivisions`	Returns the number of subdivisions for segments included in the right part of the scalebar (only used for some scalebar types).
`numericFormat`	Returns the numeric format used for numbers in the scalebar.
`pen`	Returns the pen used for drawing outlines in the scalebar.
`segmentSizeMode`	Returns the size mode for the scale bar segments.
`setAlignment`	Sets the scalebar alignment.
`setAlternateFillSymbol`	Sets the secondary fill symbol used to render the scalebar (only used for some scalebar types).
`setBoxContentSpace`	Sets the space (margin) between the scalebar box and content in millimeters.
`setBrush`	Sets the primary brush used for filling the scalebar.
`setBrush2`	Sets the secondary brush used for filling the scalebar.
`setDivisionLineSymbol`	Sets the line symbol used to render the scalebar divisions (only used for some scalebar types).
`setFillColor`	Sets the color used for fills in the scalebar.
`setFillColor2`	Sets the secondary color used for fills in the scalebar.
`setFillSymbol`	Sets the primary fill symbol used to render the scalebar (only used for some scalebar types).
`setFont`	Sets the font used for drawing text in the scalebar.
`setFontColor`	Sets the color used for drawing text in the scalebar.
`setHeight`	Sets the scalebar height (in millimeters).
`setLabelBarSpace`	Sets the spacing (in millimeters) between labels and the scalebar.
`setLabelHorizontalPlacement`	Sets the horizontal placement of text labels.
`setLabelVerticalPlacement`	Sets the vertical placement of text labels.
`setLineCapStyle`	Sets the cap style used when drawing the lines in the scalebar.
`setLineColor`	Sets the color used for lines in the scalebar.
`setLineJoinStyle`	Sets the join style used when drawing the lines in the scalebar
`setLineSymbol`	Sets the line symbol used to render the scalebar (only used for some scalebar types).
`setLineWidth`	Sets the line width in millimeters for lines in the scalebar.
`setMapUnitsPerScaleBarUnit`	Sets the number of map units per scale bar unit used by the scalebar.
`setMaximumBarWidth`	Sets the maximum width (in millimeters) for scale bar segments.
`setMinimumBarWidth`	Sets the minimum width (in millimeters) for scale bar segments.
`setNumberOfSegments`	Sets the number of segments included in the scalebar.
`setNumberOfSegmentsLeft`	Sets the number of segments included in the left part of the scalebar.
`setNumberOfSubdivisions`	Sets the number of subdivisions for segments included in the right part of the scalebar (only used for some scalebar types).
`setNumericFormat`	Sets the numeric format used for numbers in the scalebar.
`setPen`	Sets the pen used for drawing outlines in the scalebar.
`setSegmentSizeMode`	Sets the size mode for scale bar segments.
`setSubdivisionLineSymbol`	Sets the line symbol used to render the scalebar subdivisions (only used for some scalebar types).
`setSubdivisionsHeight`	Sets the scalebar subdivisions height (in millimeters) for segments included in the right part of the scalebar (only used for some scalebar types).
`setTextFormat`	Sets the text format used for drawing text in the scalebar.
`setUnitLabel`	Sets the label for units.
`setUnits`	Sets the distance units used by the scalebar.
`setUnitsPerSegment`	Sets the number of scalebar units per segment.
`subdivisionLineSymbol`	Returns the line symbol used to render the scalebar subdivisions (only used for some scalebar types).
`subdivisionsHeight`	Returns the scalebar subdivisions height (in millimeters) for segments included in the right part of the scalebar (only used for some scalebar types).
`textFormat`	Returns the text format used for drawing text in the scalebar.
`unitLabel`	Returns the label for units.
`units`	Returns the distance units used by the scalebar.
`unitsPerSegment`	Returns the number of scalebar units per segment.

class qgis.core.QgsScaleBarSettings[source]¶

Bases: object

Alignment¶: alias of ScaleBarAlignment

LabelHorizontalPlacement¶: alias of ScaleBarDistanceLabelHorizontalPlacement

LabelVerticalPlacement¶: alias of ScaleBarDistanceLabelVerticalPlacement

SegmentSizeMode¶: alias of ScaleBarSegmentSizeMode

alignment(self) → Qgis.ScaleBarAlignment[source]¶

Returns the scalebar alignment.

See also

setAlignment()

Return type:: Qgis.ScaleBarAlignment

alternateFillSymbol(self) → QgsFillSymbol | None[source]¶

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]

boxContentSpace(self) → float[source]¶

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

See also

setBoxContentSpace()

Return type:: float

brush(self) → QBrush[source]¶

Returns the primary brush used for filling the scalebar.

See also

setBrush()

See also

brush2()

See also

pen()

Deprecated since version 3.40: Use fillSymbol() instead.

Return type:: QBrush

brush2(self) → QBrush[source]¶

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

See also

setBrush2()

See also

brush()

Deprecated since version 3.40: Use alternateFillSymbol() instead.

Return type:: QBrush

divisionLineSymbol(self) → QgsLineSymbol | None[source]¶

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[source]¶

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[source]¶

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[source]¶

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[source]¶

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[source]¶

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

height(self) → float[source]¶

Returns the scalebar height (in millimeters).

See also

setHeight()

Return type:: float

labelBarSpace(self) → float[source]¶

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

See also

setLabelBarSpace()

Return type:: float

labelHorizontalPlacement(self) → Qgis.ScaleBarDistanceLabelHorizontalPlacement[source]¶

Returns the horizontal placement of text labels.

See also

setLabelHorizontalPlacement()

Added in version 3.10.

Return type:: Qgis.ScaleBarDistanceLabelHorizontalPlacement

labelVerticalPlacement(self) → Qgis.ScaleBarDistanceLabelVerticalPlacement[source]¶

Returns the vertical placement of text labels.

See also

setLabelVerticalPlacement()

Added in version 3.10.

Return type:: Qgis.ScaleBarDistanceLabelVerticalPlacement

lineCapStyle(self) → Qt.PenCapStyle[source]¶

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[source]¶

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[source]¶

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[source]¶

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[source]¶

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

mapUnitsPerScaleBarUnit(self) → float[source]¶

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

See also

setMapUnitsPerScaleBarUnit()

Return type:: float

maximumBarWidth(self) → float[source]¶

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

minimumBarWidth(self) → float[source]¶

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[source]¶

Returns the number of segments included in the scalebar.

See also

setNumberOfSegments()

See also

numberOfSegmentsLeft()

Return type:: int

numberOfSegmentsLeft(self) → int[source]¶

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[source]¶

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[source]¶

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[source]¶

Returns the pen used for drawing outlines in the scalebar.

See also

setPen()

See also

brush()

Deprecated since version 3.40: Use lineSymbol() instead.

Return type:: QPen

segmentSizeMode(self) → Qgis.ScaleBarSegmentSizeMode[source]¶

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)[source]¶

Sets the scalebar alignment.

See also

alignment()

Parameters:: alignment (Qgis.ScaleBarAlignment)

setAlternateFillSymbol(self, symbol: QgsFillSymbol | None)[source]¶

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)[source]¶

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

See also

boxContentSpace()

Parameters:: space (float)

setBrush(self, brush: QBrush | QColor | Qt.GlobalColor | QGradient)[source]¶

Sets the primary brush used for filling the scalebar.

See also

brush()

Deprecated since version 3.40: Use setFillSymbol() instead.

Parameters:: brush (Union[QBrush, Union[QColor, Qt.GlobalColor], QGradient])

setBrush2(self, brush: QBrush | QColor | Qt.GlobalColor | QGradient)[source]¶

Sets the secondary brush used for filling the scalebar.

See also

brush()

Deprecated since version 3.40: Use setAlternateFillSymbol() instead.

Parameters:: brush (Union[QBrush, Union[QColor, Qt.GlobalColor], QGradient])

setDivisionLineSymbol(self, symbol: QgsLineSymbol | None)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Sets the color used for drawing text in the scalebar.

See also

fontColor()

See also

setFont()

Deprecated since version 3.40: Use textFormat() instead.

Parameters:: color (Union[QColor, Qt.GlobalColor])

setHeight(self, height: float)[source]¶

Sets the scalebar height (in millimeters).

See also

height()

Parameters:: height (float)

setLabelBarSpace(self, space: float)[source]¶

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

See also

labelBarSpace()

Parameters:: space (float)

setLabelHorizontalPlacement(self, placement: Qgis.ScaleBarDistanceLabelHorizontalPlacement)[source]¶

Sets the horizontal placement of text labels.

See also

labelHorizontalPlacement()

Added in version 3.10.

Parameters:: placement (Qgis.ScaleBarDistanceLabelHorizontalPlacement)

setLabelVerticalPlacement(self, placement: Qgis.ScaleBarDistanceLabelVerticalPlacement)[source]¶

Sets the vertical placement of text labels.

See also

labelVerticalPlacement()

Added in version 3.10.

Parameters:: placement (Qgis.ScaleBarDistanceLabelVerticalPlacement)

setLineCapStyle(self, style: Qt.PenCapStyle)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)

setMapUnitsPerScaleBarUnit(self, units: float)[source]¶

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

See also

mapUnitsPerScaleBarUnit()

Parameters:: units (float)

setMaximumBarWidth(self, width: float)[source]¶

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:: width (float)

setMinimumBarWidth(self, width: float)[source]¶

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:: width (float)

setNumberOfSegments(self, segments: int)[source]¶

Sets the number of segments included in the scalebar.

See also

numberOfSegments()

See also

setNumberOfSegmentsLeft()

Parameters:: segments (int)

setNumberOfSegmentsLeft(self, segments: int)[source]¶

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)[source]¶

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)[source]¶

Sets the numeric format used for numbers in the scalebar.

Ownership of format is transferred to the settings.

See also

numericFormat()

Added in version 3.12.

Parameters:: format (Optional[QgsNumericFormat])

setPen(self, pen: QPen | QColor | Qt.GlobalColor)[source]¶

Sets the pen used for drawing outlines in the scalebar.

See also

pen()

Deprecated since version 3.40: Use setLineSymbol() instead.

Parameters:: pen (Union[QPen, Union[QColor, Qt.GlobalColor]])

setSegmentSizeMode(self, mode: Qgis.ScaleBarSegmentSizeMode)[source]¶

Sets the size mode for scale bar segments.

See also

segmentSizeMode()

See also

setMinimumBarWidth()

See also

setMaximumBarWidth()

Parameters:: mode (Qgis.ScaleBarSegmentSizeMode)

setSubdivisionLineSymbol(self, symbol: QgsLineSymbol | None)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Sets the label for units.

See also

unitLabel()

Parameters:: label (Optional[str])

setUnits(self, units: Qgis.DistanceUnit)[source]¶

Sets the distance units used by the scalebar.

See also

units()

Parameters:: units (Qgis.DistanceUnit)

setUnitsPerSegment(self, units: float)[source]¶

Sets the number of scalebar units per segment.

See also

unitsPerSegment()

Parameters:: units (float)

subdivisionLineSymbol(self) → QgsLineSymbol | None[source]¶

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[source]¶

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.