Class: QgsLayoutItemScaleBar

class qgis.core.QgsLayoutItemScaleBar(layout: QgsLayout)

Bases: QgsLayoutItem

Constructor for QgsLayoutItemScaleBar, with the specified parent layout.

A layout item subclass for scale bars.

New in version 3.0.

Parameters

layout

accept(self, visitor: QgsStyleEntityVisitorInterface) → bool
Parameters

visitor (QgsStyleEntityVisitorInterface) –

Return type

bool

adjustPointForReferencePosition(self, point: Union[QPointF, QPoint], size: QSizeF, reference: QgsLayoutItem.ReferencePoint) → QPointF

Adjusts the specified point at which a reference position of the item sits and returns the top left corner of the item, if reference point were placed at the specified position.

alignment(self)QgsScaleBarSettings.Alignment

Returns the scalebar alignment.

See also

setAlignment()

Return type

QgsScaleBarSettings.Alignment

alternateFillSymbol(self)QgsFillSymbol

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

Ownership is not transferred.

See also

fillSymbol()

New in version 3.14.

Return type

QgsFillSymbol

applyDataDefinedSize(self, size: QgsLayoutSize)QgsLayoutSize

Applies any present data defined size overrides to the specified layout size.

applyDefaultRendererSettings(self, renderer: QgsScaleBarRenderer) → bool

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

Returns True if settings were applied.

New in version 3.14.

Parameters

renderer (QgsScaleBarRenderer) –

Return type

bool

applyDefaultSettings(self)

Applies the default scalebar settings to the scale bar.

applyDefaultSize(self, units: QgsUnitTypes.DistanceUnit = QgsUnitTypes.DistanceMeters)

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

Parameters

units (QgsUnitTypes.DistanceUnit = QgsUnitTypes.DistanceMeters) –

applyItemSizeConstraint(self, targetSize: QSizeF) → QSizeF

Applies any item-specific size constraint handling to a given targetSize in layout units. Subclasses can override this method if they need to apply advanced logic regarding item sizes, which cannot be covered by setFixedSize() or setMinimumSize(). Item size constraints are applied after fixed, minimum and data defined size constraints.

See also

setFixedSize()

See also

setMinimumSize()

boxContentSpace(self) → float

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

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 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 use: alternateFillSymbol() instead

childEvent(self, QChildEvent)
connectNotify(self, QMetaMethod)
contextMenuEvent(self, QGraphicsSceneContextMenuEvent)
create(layout: QgsLayout)QgsLayoutItemScaleBar

Returns a new scale bar item for the specified layout.

The caller takes responsibility for deleting the returned object.

Parameters

layout (QgsLayout) –

Return type

QgsLayoutItemScaleBar

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
divisionLineSymbol(self)QgsLineSymbol

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

Ownership is not transferred.

See also

lineSymbol()

New in version 3.14.

Return type

QgsLineSymbol

dragEnterEvent(self, QGraphicsSceneDragDropEvent)
dragLeaveEvent(self, QGraphicsSceneDragDropEvent)
dragMoveEvent(self, QGraphicsSceneDragDropEvent)
draw(self, context: QgsLayoutItemRenderContext)
Parameters

context (QgsLayoutItemRenderContext) –

drawBackground(self, context: QgsRenderContext)

Draws the background for the item.

See also

framePath()

drawDebugRect(self, painter: QPainter)

Draws a debugging rectangle of the item’s current bounds within the specified painter.

Parameters

painter – destination QPainter

drawFrame(self, context: QgsRenderContext)

Draws the frame around the item.

See also

framePath()

dropEvent(self, QGraphicsSceneDragDropEvent)
exportLayerBehavior(self)QgsLayoutItem.ExportLayerBehavior
Return type

QgsLayoutItem.ExportLayerBehavior

fillColor(self) → QColor

Returns the color used for fills in the scalebar.

See also

setFillColor()

See also

fillColor2()

Deprecated since version 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 use: alternateFillSymbol() instead

Return type

QColor

fillSymbol(self)QgsFillSymbol

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

Ownership is not transferred.

See also

setFillSymbol()

New in version 3.14.

Return type

QgsFillSymbol

finalizeRestoreFromXml(self)
focusInEvent(self, QFocusEvent)
focusOutEvent(self, QFocusEvent)
font(self) → QFont

Returns the font used for drawing text in the scalebar.

See also

setFont()

Deprecated since version 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 use: textFormat() instead

Return type

QColor

framePath(self) → QPainterPath

Returns the path to use when drawing the item’s frame or background.

See also

drawFrame()

See also

drawBackground()

New in version 3.16.

guessUnits(self)QgsUnitTypes.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

QgsUnitTypes.DistanceUnit

height(self) → float

Returns the scalebar height (in millimeters).

See also

setHeight()

Return type

float

hoverEnterEvent(self, QGraphicsSceneHoverEvent)
hoverLeaveEvent(self, QGraphicsSceneHoverEvent)
hoverMoveEvent(self, QGraphicsSceneHoverEvent)
icon(self) → QIcon
Return type

QIcon

inputMethodEvent(self, QInputMethodEvent)
inputMethodQuery(self, Qt.InputMethodQuery) → Any
isSignalConnected(self, QMetaMethod) → bool
itemChange(self, QGraphicsItem.GraphicsItemChange, Any) → Any
keyPressEvent(self, QKeyEvent)
keyReleaseEvent(self, QKeyEvent)
labelBarSpace(self) → float

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

Return type

float

labelHorizontalPlacement(self)QgsScaleBarSettings.LabelHorizontalPlacement

Returns the horizontal placement of text labels.

New in version 3.10.

Return type

QgsScaleBarSettings.LabelHorizontalPlacement

labelVerticalPlacement(self)QgsScaleBarSettings.LabelVerticalPlacement

Returns the vertical placement of text labels.

New in version 3.10.

Return type

QgsScaleBarSettings.LabelVerticalPlacement

lineCapStyle(self) → Qt.PenCapStyle

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

Deprecated since version 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 use: lineSymbol() instead

Return type

QColor

lineJoinStyle(self) → Qt.PenJoinStyle

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

Deprecated since version use: lineSymbol() instead

Return type

Qt.PenJoinStyle

lineSymbol(self)QgsLineSymbol

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

Ownership is not transferred.

See also

setLineSymbol()

New in version 3.14.

Return type

QgsLineSymbol

lineWidth(self) → float

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

See also

setLineWidth()

Deprecated since version use: lineSymbol() instead

Return type

float

linkedMap(self)QgsLayoutItemMap

Returns the map item linked to the scalebar.

See also

setLinkedMap()

Return type

QgsLayoutItemMap

mapUnitsPerScaleBarUnit(self) → float

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

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.

Return type

float

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.

Return type

float

minimumSize(self)QgsLayoutSize
Return type

QgsLayoutSize

mouseDoubleClickEvent(self, QGraphicsSceneMouseEvent)
mouseMoveEvent(self, QGraphicsSceneMouseEvent)
mousePressEvent(self, QGraphicsSceneMouseEvent)
mouseReleaseEvent(self, QGraphicsSceneMouseEvent)
numberOfSegments(self) → int

Returns the number of segments included in the scalebar.

Return type

int

numberOfSegmentsLeft(self) → int

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

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.

New in version 3.14.

Return type

int

numericFormat(self)QgsNumericFormat

Returns the numeric format used for numbers in the scalebar.

New in version 3.12.

Return type

QgsNumericFormat

pen(self) → QPen

Returns the pen used for drawing outlines in the scalebar.

See also

brush()

Deprecated since version use: lineSymbol() instead

Return type

QPen

positionAtReferencePoint(self, reference: QgsLayoutItem.ReferencePoint) → QPointF

Returns the current position (in layout units) of a reference point for the item.

prepareGeometryChange(self)
readObjectPropertiesFromElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool

Sets object properties from a DOM element

Parameters
  • parentElement – is the parent DOM element for the object

  • document – DOM document

  • context – read write context

Returns

True if read was successful

readPropertiesFromElement(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool
Parameters
Return type

bool

receivers(self, PYQT_SIGNAL) → int
refreshBackgroundColor(self, updateItem: bool = True)

Refresh item’s background color, considering data defined colors. If updateItem is set to False, the item will not be automatically updated after the frame color is set and a later call to update() must be made.

refreshBlendMode(self)

Refresh item’s blend mode, considering data defined blend mode.

refreshDataDefinedProperty(self, property: QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.AllProperties)
Parameters

property (QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.AllProperties) –

refreshFrame(self, updateItem: bool = True)

Refresh item’s frame, considering data defined colors and frame size. If updateItem is set to False, the item will not be automatically updated after the frame is set and a later call to update() must be made.

refreshItemPosition(self)

Refreshes an item’s position by rechecking it against any possible overrides such as data defined positioning.

refreshItemRotation(self, origin: Union[QPointF, QPoint] = None)

Refreshes an item’s rotation by rechecking it against any possible overrides such as data defined rotation.

The optional origin point specifies the origin (in item coordinates) around which the rotation should be applied.

refreshItemSize(self)

Refreshes an item’s size by rechecking it against any possible item fixed or minimum sizes.

See also

setFixedSize()

See also

setMinimumSize()

refreshOpacity(self, updateItem: bool = True)

Refresh item’s opacity, considering data defined opacity. If updateItem is set to False the item will not be automatically updated after the opacity is set and a later call to update() must be made.

resizeToMinimumWidth(self)

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

sceneEvent(self, QEvent) → bool
sceneEventFilter(self, QGraphicsItem, QEvent) → bool
segmentSizeMode(self)QgsScaleBarSettings.SegmentSizeMode

Returns the size mode for the scale bar segments.

Return type

QgsScaleBarSettings.SegmentSizeMode

sender(self) → QObject
senderSignalIndex(self) → int
setAlignment(self, alignment: QgsScaleBarSettings.Alignment)

Sets the scalebar alignment.

See also

alignment()

Parameters

alignment (QgsScaleBarSettings.Alignment) –

setAlternateFillSymbol(self, symbol: QgsFillSymbol)

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

setFillSymbol()

New in version 3.14.

Parameters

symbol (QgsFillSymbol) –

setBoxContentSpace(self, space: float)

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

Parameters

space (float) –

setDivisionLineSymbol(self, symbol: QgsLineSymbol)

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

setLineSymbol()

New in version 3.14.

Parameters

symbol (QgsLineSymbol) –

setFillColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets the color used for fills in the scalebar.

See also

fillColor()

See also

setFillColor2()

Deprecated since version use: setFillSymbol() instead

Parameters

color (Union[QColor) –

setFillColor2(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets the secondary color used for fills in the scalebar.

See also

fillColor2()

See also

setFillColor2()

Deprecated since version use: setAlternateFillSymbol() instead

Parameters

color (Union[QColor) –

setFillSymbol(self, symbol: QgsFillSymbol)

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()

New in version 3.14.

Parameters

symbol (QgsFillSymbol) –

setFixedSize(self, size: QgsLayoutSize)

Sets a fixed size for the layout item, which prevents it from being freely resized. Set an empty size if item can be freely resized.

See also

fixedSize()

See also

setMinimumSize()

setFont(self, font: QFont)

Sets the font used for drawing text in the scalebar.

See also

font()

Deprecated since version use: setTextFormat() instead

Parameters

font (QFont) –

setFontColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets the color used for drawing text in the scalebar.

See also

fontColor()

See also

setFont()

Deprecated since version use: setTextFormat() instead

Parameters

color (Union[QColor) –

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: QgsScaleBarSettings.LabelHorizontalPlacement)

Sets the horizontal placement of text labels.

New in version 3.10.

Parameters

placement (QgsScaleBarSettings.LabelHorizontalPlacement) –

setLabelVerticalPlacement(self, placement: QgsScaleBarSettings.LabelVerticalPlacement)

Sets the vertical placement of text labels.

New in version 3.10.

Parameters

placement (QgsScaleBarSettings.LabelVerticalPlacement) –

setLineCapStyle(self, style: Qt.PenCapStyle)

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

See also

lineCapStyle()

Deprecated since version use: setLineSymbol() instead

Parameters

style (Qt.PenCapStyle) –

setLineColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets the color used for lines in the scalebar.

See also

lineColor()

Deprecated since version use: setLineSymbol() instead

Parameters

color (Union[QColor) –

setLineJoinStyle(self, style: Qt.PenJoinStyle)

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

See also

lineJoinStyle()

Deprecated since version use: setLineSymbol() instead

Parameters

style (Qt.PenJoinStyle) –

setLineSymbol(self, symbol: QgsLineSymbol)

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()

New in version 3.14.

Parameters

symbol (QgsLineSymbol) –

setLineWidth(self, width: float)

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

See also

lineWidth()

Deprecated since version use: setLineSymbol() instead

Parameters

width (float) –

setLinkedMap(self, map: QgsLayoutItemMap)

Sets the map item linked to the scalebar.

See also

linkedMap()

Parameters

map (QgsLayoutItemMap) –

setMapUnitsPerScaleBarUnit(self, units: float)

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

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.

Parameters

maxWidth (float) –

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.

Parameters

minWidth (float) –

setMinimumSize(self, size: QgsLayoutSize)

Sets the minimum allowed size for the layout item. Set an empty size if item can be freely resized.

See also

minimumSize()

See also

setFixedSize()

setNumberOfSegments(self, segments: int)

Sets the number of segments included in the scalebar.

Parameters

segments (int) –

setNumberOfSegmentsLeft(self, segments: int)

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

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.

New in version 3.14.

Parameters

subdivisions (int) –

setNumericFormat(self, format: QgsNumericFormat)

Sets the numeric format used for numbers in the scalebar.

Ownership of format is transferred to the scalebar.

See also

numericFormat()

New in version 3.12.

Parameters

format (QgsNumericFormat) –

setSegmentSizeMode(self, mode: QgsScaleBarSettings.SegmentSizeMode)

Sets the size mode for scale bar segments.

Parameters

mode (QgsScaleBarSettings.SegmentSizeMode) –

setStyle(self, name: str)

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’, ‘Numeric’

See also

style()

Parameters

name (str) –

setSubdivisionLineSymbol(self, symbol: QgsLineSymbol)

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

setLineSymbol()

New in version 3.14.

Parameters

symbol (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).

New 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()

New in version 3.2.

Parameters

format (QgsTextFormat) –

setUnitLabel(self, label: str)

Sets the label for units.

See also

unitLabel()

Parameters

label (str) –

setUnits(self, units: QgsUnitTypes.DistanceUnit)

Sets the distance units used by the scalebar.

See also

units()

Parameters

units (QgsUnitTypes.DistanceUnit) –

setUnitsPerSegment(self, units: float)

Sets the number of scalebar units per segment.

Parameters

units (float) –

style(self) → str

Returns the scale bar style name.

See also

setStyle()

Return type

str

subdivisionLineSymbol(self)QgsLineSymbol

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

Ownership is not transferred.

See also

lineSymbol()

New in version 3.14.

Return type

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

New in version 3.14.

Return type

float

textFormat(self)QgsTextFormat

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

See also

setTextFormat()

New in version 3.2.

Return type

QgsTextFormat

timerEvent(self, QTimerEvent)
topLeftToReferencePoint(self, point: QgsLayoutPoint)QgsLayoutPoint

Returns the position for the reference point of the item, if the top-left of the item was placed at the specified point.

type(self) → int
Return type

int

unitLabel(self) → str

Returns the label for units.

See also

setUnitLabel()

Return type

str

units(self)QgsUnitTypes.DistanceUnit

Returns the distance units used by the scalebar.

See also

setUnits()

Return type

QgsUnitTypes.DistanceUnit

unitsPerSegment(self) → float

Returns the number of scalebar units per segment.

Return type

float

update(self)

Adjusts the scale bar box size and updates the item.

updateMicroFocus(self)
wheelEvent(self, QGraphicsSceneWheelEvent)
writeObjectPropertiesToElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool

Stores object properties within an XML DOM element.

Parameters
  • parentElement – is the parent DOM element to store the object’s properties in

  • document – DOM document

  • context – read write context

Returns

True if write was successful

writePropertiesToElement(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool
Parameters
Return type

bool