Class: QgsScaleBarRenderer¶

Abstract base class for scale bar renderers.

Scalebar renderer subclasses implement custom drawing logic, with the possibility to implement custom labeling.

Class Hierarchy¶

Subclasses¶

`QgsDoubleBoxScaleBarRenderer`	Double box with alternating colors.
`QgsHollowScaleBarRenderer`	Scalebar style that draws a single box with alternating color for the segments, with horizontal lines through alternating segments. AKA “South African” style.
`QgsNumericScaleBarRenderer`	A scale bar style that draws text in the form of ‘1:XXXXX’.
`QgsSingleBoxScaleBarRenderer`	Scalebar style that draws a single box with alternating color for the segments.
`QgsSteppedLineScaleBarRenderer`	Scalebar style that draws a stepped line representation of a scalebar.
`QgsTicksScaleBarRenderer`	A scale bar that draws segments using short ticks.

Enums

Flag

Flags which control scalebar renderer behavior.

Methods

`applyDefaultSettings`	Applies any default settings relating to the scalebar to the passed settings object.
`calculateBoxSize`	Calculates the required box size (in millimeters) for a scalebar using the specified settings and scaleContext.
`clone`	Returns a clone of the renderer.
`draw`	Draws the scalebar using the specified settings and scaleContext to a destination render context.
`drawDefaultLabels`	Draws default scalebar labels using the specified settings and scaleContext to a destination render context.
`firstLabelString`	Returns the text used for the first label in the scalebar.
`firstLabelXOffset`	Returns the x-offset (in millimeters) used for the first label in the scalebar.
`flags`	Returns the scalebar rendering flags, which dictates the renderer's behavior.
`id`	Returns the unique ID for this renderer.
`name`	Returns the unique name for this style.
`segmentPositions`	Returns a list of positions for each segment within the scalebar.
`segmentWidths`	Returns a list of widths of each segment of the scalebar.
`sortKey`	Returns a sorting key value, where renderers with a lower sort key will be shown earlier in lists.
`visibleName`	Returns the user friendly, translated name for the renderer.

class qgis.core.QgsScaleBarRenderer[source]¶

Bases: object

class Flag(*values)¶

Bases: IntEnum

Flags which control scalebar renderer behavior.

Added in version 3.14.

FlagUsesLineSymbol: Renderer utilizes the scalebar line symbol (see QgsScaleBarSettings.lineSymbol() )
FlagUsesFillSymbol: Renderer utilizes the scalebar fill symbol (see QgsScaleBarSettings.fillSymbol() )
FlagUsesAlternateFillSymbol: Renderer utilizes the alternate scalebar fill symbol (see QgsScaleBarSettings.alternateFillSymbol() )
FlagRespectsUnits: Renderer respects the QgsScaleBarSettings.units() setting
FlagRespectsMapUnitsPerScaleBarUnit: Renderer respects the QgsScaleBarSettings.mapUnitsPerScaleBarUnit() setting
FlagUsesUnitLabel: Renderer uses the QgsScaleBarSettings.unitLabel() setting
FlagUsesSegments: Renderer uses the scalebar segments
FlagUsesLabelBarSpace: Renderer uses the QgsScaleBarSettings.labelBarSpace() setting
FlagUsesLabelVerticalPlacement: Renderer uses the QgsScaleBarSettings.labelVerticalPlacement() setting
FlagUsesLabelHorizontalPlacement: Renderer uses the QgsScaleBarSettings.labelHorizontalPlacement() setting
FlagUsesAlignment: Renderer uses the QgsScaleBarSettings.alignment() setting
FlagUsesSubdivisions: Renderer uses the scalebar subdivisions (see QgsScaleBarSettings.numberOfSubdivisions() )
FlagUsesDivisionSymbol: Renderer utilizes the scalebar division symbol (see QgsScaleBarSettings.divisionLineSymbol() )
FlagUsesSubdivisionSymbol: Renderer utilizes the scalebar subdivision symbol (see QgsScaleBarSettings.subdivisionLineSymbol() )
FlagUsesSubdivisionsHeight: Renderer uses the scalebar subdivisions height (see QgsScaleBarSettings.subdivisionsHeight() )

FlagRespectsMapUnitsPerScaleBarUnit = 16¶

FlagRespectsUnits = 8¶

FlagUsesAlignment = 512¶

FlagUsesAlternateFillSymbol = 4¶

FlagUsesDivisionSymbol = 2048¶

FlagUsesFillSymbol = 2¶

FlagUsesLabelBarSpace = 128¶

FlagUsesLabelHorizontalPlacement = 256¶

FlagUsesLabelVerticalPlacement = 256¶

FlagUsesLineSymbol = 1¶

FlagUsesSegments = 64¶

FlagUsesSubdivisionSymbol = 4096¶

FlagUsesSubdivisions = 1024¶

FlagUsesSubdivisionsHeight = 8192¶

FlagUsesUnitLabel = 32¶

class Flags¶
class Flags(f: QgsScaleBarRenderer.Flags | QgsScaleBarRenderer.Flag)
class Flags(a0: QgsScaleBarRenderer.Flags): Bases: object

class ScaleBarContext¶

Bases: object

Contains parameters regarding scalebar calculations.

Note

The need to attribute the parameters vary depending on the targeted scalebar.

flags¶: Scalebar renderer flags

isValid(self) → bool¶

Returns True if the context has valid settings.

Added in version 3.40.

Return type:: bool

scale¶: Scale denominator

segmentWidth¶: The width, in millimeters, of each individual segment drawn.

Note

The number of map units per segment needs to be set via QgsScaleBarSettings.setUnitsPerSegment.

size¶: Destination size for scalebar. This is used for scalebars which alter their appearance or alignment based on the desired scalebar size (e.g. correctly aligning text in a numeric scale bar).

applyDefaultSettings(self, settings: QgsScaleBarSettings) → bool[source]¶

Applies any default settings relating to the scalebar to the passed settings object.

Returns True if settings were applied.

Added in version 3.14.

Parameters:: settings (QgsScaleBarSettings)
Return type:: bool

calculateBoxSize(self, settings: QgsScaleBarSettings, scaleContext: QgsScaleBarRenderer.ScaleBarContext) → QSizeF[source]¶

Calculates the required box size (in millimeters) for a scalebar using the specified settings and scaleContext.

Deprecated since version 3.40: Use the version with a QgsRenderContext instead.

Parameters:

settings (QgsScaleBarSettings)
scaleContext (QgsScaleBarRenderer.ScaleBarContext)

Return type:

QSizeF

calculateBoxSize(self, context: QgsRenderContext, settings: QgsScaleBarSettings, scaleContext: QgsScaleBarRenderer.ScaleBarContext) → QSizeF[source]

Calculates the required box size (in millimeters) for a scalebar using the specified settings and scaleContext.

Added in version 3.14.

Parameters:

context (QgsRenderContext)
settings (QgsScaleBarSettings)
scaleContext (QgsScaleBarRenderer.ScaleBarContext)

Return type:

QSizeF

clone(self) → QgsScaleBarRenderer | None[source]¶

Returns a clone of the renderer. The caller takes ownership of the returned value.

Return type:: Optional[QgsScaleBarRenderer]

draw(self, context: QgsRenderContext, settings: QgsScaleBarSettings, scaleContext: QgsScaleBarRenderer.ScaleBarContext)[source]¶

Draws the scalebar using the specified settings and scaleContext to a destination render context.

Parameters:

context (QgsRenderContext)
settings (QgsScaleBarSettings)
scaleContext (QgsScaleBarRenderer.ScaleBarContext)

drawDefaultLabels(self, context: QgsRenderContext, settings: QgsScaleBarSettings, scaleContext: QgsScaleBarRenderer.ScaleBarContext)[source]¶

Draws default scalebar labels using the specified settings and scaleContext to a destination render context.

Parameters:

context (QgsRenderContext)
settings (QgsScaleBarSettings)
scaleContext (QgsScaleBarRenderer.ScaleBarContext)

firstLabelString(self, settings: QgsScaleBarSettings) → str[source]¶

Returns the text used for the first label in the scalebar.

Parameters:: settings (QgsScaleBarSettings)
Return type:: str

firstLabelXOffset(self, settings: QgsScaleBarSettings) → float[source]¶

Returns the x-offset (in millimeters) used for the first label in the scalebar.

Deprecated since version 3.40: Use the version with QgsRenderContext instead.

Parameters:: settings (QgsScaleBarSettings)
Return type:: float

firstLabelXOffset(self, settings: QgsScaleBarSettings, context: QgsRenderContext, scaleContext: QgsScaleBarRenderer.ScaleBarContext) → float[source]

Returns the x-offset (in render context painter units) used for the first label in the scalebar.

Added in version 3.2.

Parameters:

settings (QgsScaleBarSettings)
context (QgsRenderContext)
scaleContext (QgsScaleBarRenderer.ScaleBarContext)

Return type:

float

flags(self) → QgsScaleBarRenderer.Flags[source]¶

Returns the scalebar rendering flags, which dictates the renderer’s behavior.

Added in version 3.14.

Return type:: QgsScaleBarRenderer.Flags

id(self) → str[source]¶

Returns the unique ID for this renderer.

Added in version 3.14.

Return type:: str

name(self) → str[source]¶

Returns the unique name for this style.

Deprecated since version 3.40: Use id() instead.

Return type:: str

segmentPositions(self, scaleContext: QgsScaleBarRenderer.ScaleBarContext, settings: QgsScaleBarSettings) → List[float]¶

Returns a list of positions for each segment within the scalebar.

Deprecated since version 3.40: Use the version with a QgsRenderContext instead.

Parameters:

scaleContext (QgsScaleBarRenderer.ScaleBarContext)
settings (QgsScaleBarSettings)

Return type:

List[float]

segmentPositions(self, context: QgsRenderContext, scaleContext: QgsScaleBarRenderer.ScaleBarContext, settings: QgsScaleBarSettings) → List[float]

Returns a list of positions for each segment within the scalebar.

Added in version 3.14.

Parameters:

context (QgsRenderContext)
scaleContext (QgsScaleBarRenderer.ScaleBarContext)
settings (QgsScaleBarSettings)

Return type:

List[float]

segmentWidths(self, scaleContext: QgsScaleBarRenderer.ScaleBarContext, settings: QgsScaleBarSettings) → List[float]¶

Returns a list of widths of each segment of the scalebar.

Parameters:

scaleContext (QgsScaleBarRenderer.ScaleBarContext)
settings (QgsScaleBarSettings)

Return type:

List[float]

sortKey(self) → int[source]¶

Returns a sorting key value, where renderers with a lower sort key will be shown earlier in lists.

Generally, subclasses should return QgsScaleBarRenderer.sortKey() as their sorting key.

Return type:: int

visibleName(self) → str[source]¶

Returns the user friendly, translated name for the renderer.

Added in version 3.14.

Return type:: str