Class: QgsScaleBarRenderer¶

Abstract base class for scale bar renderers.

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

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: clone(), draw(), id(), visibleName()

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.
`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.

Abstract Methods

`clone`	Returns a clone of the renderer.
`draw`	Draws the scalebar using the specified settings and scaleContext to a destination render context.
`id`	Returns the unique ID for this renderer.
`visibleName`	Returns the user friendly, translated name for the renderer.

Methods

`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.
`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.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsScaleBarRenderer. See the FAQ for more details.

`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.
`flags`	Returns the scalebar rendering flags, which dictates the renderer's behavior.
`sortKey`	Returns a sorting key value, where renderers with a lower sort key will be shown earlier in lists.

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: QgsScaleBarRenderer.Flags¶: Scalebar renderer flags

isValid(self) → bool¶

Returns True if the context has valid settings.

Added in version 3.40.

Return type:: bool

scale: float¶: Scale denominator

segmentWidth: float¶: 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: QSizeF¶: 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).

virtual 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

virtual 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

virtual 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

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

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

Return type:: Optional[QgsScaleBarRenderer]

abstract 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

virtual 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

abstract 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]

virtual 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

abstract visibleName(self) → str[source]¶

Returns the user friendly, translated name for the renderer.

Added in version 3.14.

Return type:: str