QgsLayoutItemScaleBar class

A layout item subclass for scale bars.

Contents

Base classes

class QgsLayoutItem
Base class for graphical items within a QgsLayout.

Public static functions

static auto create(QgsLayout* layout) -> QgsLayoutItemScaleBar*
Returns a new scale bar item for the specified layout.

Constructors, destructors, conversion operators

QgsLayoutItemScaleBar(QgsLayout* layout)
Constructor for QgsLayoutItemScaleBar, with the specified parent layout.

Public functions

auto alignment() const -> QgsScaleBarSettings::Alignment
Returns the scalebar alignment.
void applyDefaultSettings()
Applies the default scalebar settings to the scale bar.
void applyDefaultSize(QgsUnitTypes::DistanceUnit units = QgsUnitTypes::DistanceMeters)
Applies the default size to the scale bar (scale bar 1/5 of map item width)
auto boxContentSpace() const -> double
Returns the spacing (margin) between the scalebar box and content in millimeters.
auto brush() const -> QBrush
Returns the primary brush for the scalebar.
auto brush2() const -> QBrush
Returns the secondary brush for the scalebar.
auto fillColor() const -> QColor
Returns the color used for fills in the scalebar.
auto fillColor2() const -> QColor
Returns the secondary color used for fills in the scalebar.
void finalizeRestoreFromXml() override
Called after all pending items have been restored from XML.
auto font() const -> Q_DECL_DEPRECATED QFont deprecated
Returns the font used for drawing text in the scalebar.
auto fontColor() const -> Q_DECL_DEPRECATED QColor deprecated
Returns the color used for drawing text in the scalebar.
auto guessUnits() const -> QgsUnitTypes::DistanceUnit
Attempts to guess the most reasonable unit choice for the scalebar, given the current linked map's scale.
auto height() const -> double
Returns the scalebar height (in millimeters).
auto icon() const -> QIcon override
Returns the item's icon.
auto labelBarSpace() const -> double
Returns the spacing (in millimeters) between labels and the scalebar.
auto lineCapStyle() const -> Qt::PenCapStyle
Returns the cap style used for drawing lines in the scalebar.
auto lineColor() const -> QColor
Returns the color used for lines in the scalebar.
auto lineJoinStyle() const -> Qt::PenJoinStyle
Returns the join style used for drawing lines in the scalebar.
auto lineWidth() const -> double
Returns the line width in millimeters for lines in the scalebar.
auto linkedMap() const -> QgsLayoutItemMap*
Returns the map item linked to the scalebar.
auto mapUnitsPerScaleBarUnit() const -> double
Returns the number of map units per scale bar unit used by the scalebar.
auto maximumBarWidth() const -> double
Returns the maximum width (in millimeters) for scale bar segments.
auto minimumBarWidth() const -> double
Returns the minimum width (in millimeters) for scale bar segments.
auto minimumSize() const -> QgsLayoutSize override
Returns the minimum allowed size of the item, if applicable, or an empty size if item can be freely resized.
auto numberOfSegments() const -> int
Returns the number of segments included in the scalebar.
auto numberOfSegmentsLeft() const -> int
Returns the number of segments included in the left part of the scalebar.
auto pen() const -> QPen
Returns the pen used for drawing outlines in the scalebar.
void refreshDataDefinedProperty(QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties) override
Refreshes a data defined property for the item by reevaluating the property's value and redrawing the item with this new value.
void resizeToMinimumWidth()
Resizes the scale bar to its minimum width, without changing the height.
auto segmentSizeMode() const -> QgsScaleBarSettings::SegmentSizeMode
Returns the size mode for the scale bar segments.
void setAlignment(QgsScaleBarSettings::Alignment alignment)
Sets the scalebar alignment.
void setBoxContentSpace(double space)
Sets the space (margin) between the scalebar box and content in millimeters.
void setFillColor(const QColor& color)
Sets the color used for fills in the scalebar.
void setFillColor2(const QColor& color)
Sets the secondary color used for fills in the scalebar.
auto setFont(const QFont& font) -> Q_DECL_DEPRECATED void deprecated
Sets the font used for drawing text in the scalebar.
auto setFontColor(const QColor& color) -> Q_DECL_DEPRECATED void deprecated
Sets the color used for drawing text in the scalebar.
void setHeight(double height)
Sets the scalebar height (in millimeters).
void setLabelBarSpace(double space)
Sets the spacing (in millimeters) between labels and the scalebar.
void setLineCapStyle(Qt::PenCapStyle style)
Sets the cap style used when drawing the lines in the scalebar.
void setLineColor(const QColor& color)
Sets the color used for lines in the scalebar.
void setLineJoinStyle(Qt::PenJoinStyle style)
Sets the join style used when drawing the lines in the scalebar.
void setLineWidth(double width)
Sets the line width in millimeters for lines in the scalebar.
void setLinkedMap(QgsLayoutItemMap* map)
Sets the map item linked to the scalebar.
void setMapUnitsPerScaleBarUnit(double units)
Sets the number of map units per scale bar unit used by the scalebar.
void setMaximumBarWidth(double maxWidth)
Sets the maximum width (in millimeters) for scale bar segments.
void setMinimumBarWidth(double minWidth)
Sets the minimum width (in millimeters) for scale bar segments.
void setNumberOfSegments(int segments)
Sets the number of segments included in the scalebar.
void setNumberOfSegmentsLeft(int segments)
Sets the number of segments included in the left part of the scalebar.
void setSegmentSizeMode(QgsScaleBarSettings::SegmentSizeMode mode)
Sets the size mode for scale bar segments.
void setStyle(const QString& name)
Sets the scale bar style by name.
void setTextFormat(const QgsTextFormat& format)
Sets the text format used for drawing text in the scalebar.
void setUnitLabel(const QString& label)
Sets the label for units.
void setUnits(QgsUnitTypes::DistanceUnit units)
Sets the distance units used by the scalebar.
void setUnitsPerSegment(double units)
Sets the number of scalebar units per segment.
auto style() const -> QString
Returns the scale bar style name.
auto textFormat() const -> QgsTextFormat
Returns the text format used for drawing text in the scalebar.
auto unitLabel() const -> QString
Returns the label for units.
auto units() const -> QgsUnitTypes::DistanceUnit
Returns the distance units used by the scalebar.
auto unitsPerSegment() const -> double
Returns the number of scalebar units per segment.
void update()
Adjusts the scale bar box size and updates the item.

Protected functions

void draw(QgsLayoutItemRenderContext& context) override
Draws the item's contents using the specified item render context.
auto readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override
Sets item state from a DOM element.
auto writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override
Stores item state within an XML DOM element.

Function documentation

static QgsLayoutItemScaleBar* QgsLayoutItemScaleBar::create(QgsLayout* layout)

Returns a new scale bar item for the specified layout.

The caller takes responsibility for deleting the returned object.

QgsScaleBarSettings::Alignment QgsLayoutItemScaleBar::alignment() const

Returns the scalebar alignment.

void QgsLayoutItemScaleBar::applyDefaultSettings()

Applies the default scalebar settings to the scale bar.

void QgsLayoutItemScaleBar::applyDefaultSize(QgsUnitTypes::DistanceUnit units = QgsUnitTypes::DistanceMeters)

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

double QgsLayoutItemScaleBar::boxContentSpace() const

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

QBrush QgsLayoutItemScaleBar::brush() const

Returns the primary brush for the scalebar.

Returns QBrush used for filling the scalebar

QBrush QgsLayoutItemScaleBar::brush2() const

Returns the secondary brush for the scalebar.

Returns QBrush used for secondary color areas

This is used for alternating color style scalebars, such as single and double box styles.

QColor QgsLayoutItemScaleBar::fillColor() const

Returns the color used for fills in the scalebar.

QColor QgsLayoutItemScaleBar::fillColor2() const

Returns the secondary color used for fills in the scalebar.

void QgsLayoutItemScaleBar::finalizeRestoreFromXml() override

Called after all pending items have been restored from XML.

Items can use this method to run steps which must take place after all items have been restored to the layout, such as connecting to signals emitted by other items, which may not have existed in the layout at the time readXml() was called. E.g. a scalebar can use this to connect to its linked map item after restoration from XML.

Q_DECL_DEPRECATED QFont QgsLayoutItemScaleBar::font() const

Returns the font used for drawing text in the scalebar.

Q_DECL_DEPRECATED QColor QgsLayoutItemScaleBar::fontColor() const

Returns the color used for drawing text in the scalebar.

QgsUnitTypes::DistanceUnit QgsLayoutItemScaleBar::guessUnits() const

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.

double QgsLayoutItemScaleBar::height() const

Returns the scalebar height (in millimeters).

double QgsLayoutItemScaleBar::labelBarSpace() const

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

Qt::PenCapStyle QgsLayoutItemScaleBar::lineCapStyle() const

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

QColor QgsLayoutItemScaleBar::lineColor() const

Returns the color used for lines in the scalebar.

Qt::PenJoinStyle QgsLayoutItemScaleBar::lineJoinStyle() const

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

double QgsLayoutItemScaleBar::lineWidth() const

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

QgsLayoutItemMap* QgsLayoutItemScaleBar::linkedMap() const

Returns the map item linked to the scalebar.

double QgsLayoutItemScaleBar::mapUnitsPerScaleBarUnit() const

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

double QgsLayoutItemScaleBar::maximumBarWidth() const

Returns the maximum width (in millimeters) for scale bar segments.

This property is only effective if the segmentSizeMode() is set to SegmentSizeFitWidth.

double QgsLayoutItemScaleBar::minimumBarWidth() const

Returns the minimum width (in millimeters) for scale bar segments.

This property is only effective if the segmentSizeMode() is set to SegmentSizeFitWidth.

QgsLayoutSize QgsLayoutItemScaleBar::minimumSize() const override

Returns the minimum allowed size of the item, if applicable, or an empty size if item can be freely resized.

int QgsLayoutItemScaleBar::numberOfSegments() const

Returns the number of segments included in the scalebar.

int QgsLayoutItemScaleBar::numberOfSegmentsLeft() const

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

QPen QgsLayoutItemScaleBar::pen() const

Returns the pen used for drawing outlines in the scalebar.

void QgsLayoutItemScaleBar::refreshDataDefinedProperty(QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties) override

Refreshes a data defined property for the item by reevaluating the property's value and redrawing the item with this new value.

If property is set to QgsLayoutObject::AllProperties then all data defined properties for the item will be refreshed.

QgsScaleBarSettings::SegmentSizeMode QgsLayoutItemScaleBar::segmentSizeMode() const

Returns the size mode for the scale bar segments.

void QgsLayoutItemScaleBar::setAlignment(QgsScaleBarSettings::Alignment alignment)

Sets the scalebar alignment.

void QgsLayoutItemScaleBar::setBoxContentSpace(double space)

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

void QgsLayoutItemScaleBar::setFillColor(const QColor& color)

Sets the color used for fills in the scalebar.

void QgsLayoutItemScaleBar::setFillColor2(const QColor& color)

Sets the secondary color used for fills in the scalebar.

Q_DECL_DEPRECATED void QgsLayoutItemScaleBar::setFont(const QFont& font)

Sets the font used for drawing text in the scalebar.

Q_DECL_DEPRECATED void QgsLayoutItemScaleBar::setFontColor(const QColor& color)

Sets the color used for drawing text in the scalebar.

void QgsLayoutItemScaleBar::setHeight(double height)

Sets the scalebar height (in millimeters).

void QgsLayoutItemScaleBar::setLabelBarSpace(double space)

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

void QgsLayoutItemScaleBar::setLineCapStyle(Qt::PenCapStyle style)

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

void QgsLayoutItemScaleBar::setLineColor(const QColor& color)

Sets the color used for lines in the scalebar.

void QgsLayoutItemScaleBar::setLineJoinStyle(Qt::PenJoinStyle style)

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

void QgsLayoutItemScaleBar::setLineWidth(double width)

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

void QgsLayoutItemScaleBar::setLinkedMap(QgsLayoutItemMap* map)

Sets the map item linked to the scalebar.

void QgsLayoutItemScaleBar::setMapUnitsPerScaleBarUnit(double units)

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

void QgsLayoutItemScaleBar::setMaximumBarWidth(double maxWidth)

Sets the maximum width (in millimeters) for scale bar segments.

This property is only effective if the segmentSizeMode() is set to SegmentSizeFitWidth.

void QgsLayoutItemScaleBar::setMinimumBarWidth(double minWidth)

Sets the minimum width (in millimeters) for scale bar segments.

This property is only effective if the segmentSizeMode() is set to SegmentSizeFitWidth.

void QgsLayoutItemScaleBar::setNumberOfSegments(int segments)

Sets the number of segments included in the scalebar.

void QgsLayoutItemScaleBar::setNumberOfSegmentsLeft(int segments)

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

void QgsLayoutItemScaleBar::setSegmentSizeMode(QgsScaleBarSettings::SegmentSizeMode mode)

Sets the size mode for scale bar segments.

void QgsLayoutItemScaleBar::setStyle(const QString& name)

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'

void QgsLayoutItemScaleBar::setTextFormat(const QgsTextFormat& format)

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

void QgsLayoutItemScaleBar::setUnitLabel(const QString& label)

Sets the label for units.

void QgsLayoutItemScaleBar::setUnits(QgsUnitTypes::DistanceUnit units)

Sets the distance units used by the scalebar.

void QgsLayoutItemScaleBar::setUnitsPerSegment(double units)

Sets the number of scalebar units per segment.

QString QgsLayoutItemScaleBar::style() const

Returns the scale bar style name.

QgsTextFormat QgsLayoutItemScaleBar::textFormat() const

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

QString QgsLayoutItemScaleBar::unitLabel() const

Returns the label for units.

QgsUnitTypes::DistanceUnit QgsLayoutItemScaleBar::units() const

Returns the distance units used by the scalebar.

double QgsLayoutItemScaleBar::unitsPerSegment() const

Returns the number of scalebar units per segment.

void QgsLayoutItemScaleBar::draw(QgsLayoutItemRenderContext& context) override protected

Draws the item's contents using the specified item render context.

Note that the context's painter has been scaled so that painter units are pixels. Use the QgsRenderContext methods to convert from millimeters or other units to the painter's units.

bool QgsLayoutItemScaleBar::readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) override protected

Sets item state from a DOM element.

Parameters
element is the DOM element for the item
document DOM document
context read write context

Note that item subclasses should not rely on all other items being present in the layout at the time this method is called. Instead, any connections and links to other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring a scalebar, the connection to the linked map's signals should be implemented in finalizeRestoreFromXml(), not readPropertiesFromElement().

bool QgsLayoutItemScaleBar::writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const override protected

Stores item state within an XML DOM element.

Parameters
element is the DOM element to store the item's properties in
document DOM document
context read write context