Class: QgsLayoutItemMapGrid

class qgis.core.QgsLayoutItemMapGrid

Bases: QgsLayoutItemMapItem

An individual grid which is drawn above the map content in a QgsLayoutItemMap.

QgsLayoutItemMapGrid(name: str, map: QgsLayoutItemMap) Constructor for QgsLayoutItemMapGrid.

Parameters:
AboveTick = 4
class AnnotationCoordinate

Bases: int

class AnnotationDirection

Bases: int

class AnnotationFormat

Bases: int

class AnnotationPosition

Bases: int

class BorderSide

Bases: int

Bottom = 2
BoundaryDirection = 3
CM = 2
Cross = 1
CustomFormat = 8
Decimal = 0
DecimalWithSuffix = 3
DegreeMinute = 1
DegreeMinuteNoSuffix = 4
DegreeMinutePadded = 5
DegreeMinuteSecond = 2
DegreeMinuteSecondNoSuffix = 6
DegreeMinuteSecondPadded = 7
class DisplayMode

Bases: int

DynamicPageSizeBased = 3
ExteriorTicks = 3
FrameAnnotationsOnly = 3
FrameBottom = 8
FrameLeft = 1
FrameRight = 2
class FrameSideFlag

Bases: int

class FrameSideFlags
class FrameSideFlags(Union[QgsLayoutItemMapGrid.FrameSideFlags, QgsLayoutItemMapGrid.FrameSideFlag])
class FrameSideFlags(QgsLayoutItemMapGrid.FrameSideFlags)

Bases: sip.wrapper

class FrameStyle

Bases: int

FrameTop = 4
class GridStyle

Bases: int

class GridUnit

Bases: int

HideAll = 3
Horizontal = 0
InsideMapFrame = 0
InteriorExteriorTicks = 4
InteriorTicks = 2
Latitude = 1
LatitudeOnly = 1
Left = 0
LineBorder = 5
LineBorderNautical = 6
Longitude = 0
LongitudeOnly = 2
MM = 1
MapUnit = 0
Markers = 2
NoFrame = 0
NormalizedTicks = 1
OnTick = 5
OrthogonalTicks = 0
OutsideMapFrame = 1
Right = 1
ShowAll = 0
Solid = 0
class TickLengthMode

Bases: int

Top = 3
UnderTick = 6
Vertical = 1
VerticalDescending = 2
Zebra = 1
ZebraNautical = 7
accept(self, visitor: QgsStyleEntityVisitorInterface) bool
Parameters:

visitor (QgsStyleEntityVisitorInterface) –

Return type:

bool

annotationDirection(self, border: QgsLayoutItemMapGrid.BorderSide) QgsLayoutItemMapGrid.AnnotationDirection

Returns the direction for drawing frame annotations, on the specified side of the map.

Parameters:

border (QgsLayoutItemMapGrid.BorderSide) –

Return type:

QgsLayoutItemMapGrid.AnnotationDirection

annotationDisplay(self, border: QgsLayoutItemMapGrid.BorderSide) QgsLayoutItemMapGrid.DisplayMode

Returns the display mode for the grid annotations on a specified side of the map frame. This property also specifies whether annotations have been disabled from a side of the map frame.

Parameters:

border (QgsLayoutItemMapGrid.BorderSide) – side of map for annotations

Return type:

QgsLayoutItemMapGrid.DisplayMode

Returns:

display mode for grid annotations

annotationEnabled(self) bool

Returns whether annotations are shown for the grid.

Return type:

bool

annotationExpression(self) str

Returns the expression used for drawing grid annotations. This is only used when annotationFormat() is QgsLayoutItemMapGrid.CustomFormat.

Return type:

str

annotationFont(self) QFont

Returns the font used for drawing grid annotations. Shortcut for annotationTextFormat().font().

Deprecated since version use: annotationTextFormat() instead

Return type:

QFont

annotationFontColor(self) QColor

Returns the font color used for drawing grid annotations. Shortcut for annotationTextFormat().color() and annotationTextFormat().opacity().

Deprecated since version use: annotationTextFormat() instead

Return type:

QColor

annotationFormat(self) QgsLayoutItemMapGrid.AnnotationFormat

Returns the format for drawing grid annotations.

Return type:

QgsLayoutItemMapGrid.AnnotationFormat

annotationFrameDistance(self) float

Returns the distance between the map frame and annotations. Units are in layout units.

Return type:

float

annotationPosition(self, side: QgsLayoutItemMapGrid.BorderSide) QgsLayoutItemMapGrid.AnnotationPosition

Returns the position for the grid annotations on a specified side of the map frame.

Parameters:

side (QgsLayoutItemMapGrid.BorderSide) –

Return type:

QgsLayoutItemMapGrid.AnnotationPosition

annotationPrecision(self) int

Returns the coordinate precision for grid annotations, which is the number of decimal places shown when drawing grid annotations.

Return type:

int

annotationTextFormat(self) QgsTextFormat

Returns the text format used when rendering grid annotations.

New in version 3.16.

Return type:

QgsTextFormat

blendMode(self) QPainter.CompositionMode

Retrieves the blending mode used for drawing the grid.

See also

setBlendMode()

Return type:

QPainter.CompositionMode

calculateMaxExtension(self) Tuple[float, float, float, float]

Calculates the maximum distance the grid extends beyond the QgsLayoutItemMap’s item rect. This method calculates the distance for each side of the map item separately.

See also

maxExtension()

Return type:

Tuple[float, float, float, float]

childEvent(self, QChildEvent)
connectNotify(self, QMetaMethod)
createExpressionContext(self) QgsExpressionContext
Return type:

QgsExpressionContext

crossLength(self) float

Retrieves the length (in layout units) of the cross segments drawn for the grid. This is only used for grids with QgsLayoutItemMapGrid.Cross styles.

See also

setCrossLength()

Return type:

float

crs(self) QgsCoordinateReferenceSystem

Retrieves the CRS for the grid.

See also

setCrs()

Return type:

QgsCoordinateReferenceSystem

crsChanged

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
draw(self, painter: QPainter)
Parameters:

painter (QPainter) –

frameDivisions(self, side: QgsLayoutItemMapGrid.BorderSide) QgsLayoutItemMapGrid.DisplayMode

Returns the type of grid divisions which are used for frames on a specified side of the map.

Parameters:

side (QgsLayoutItemMapGrid.BorderSide) –

Return type:

QgsLayoutItemMapGrid.DisplayMode

frameFillColor1(self) QColor

Retrieves the first fill color for the grid frame.

See also

framePenColor()

Return type:

QColor

frameFillColor2(self) QColor

Retrieves the second fill color for the grid frame.

See also

framePenColor()

Return type:

QColor

frameMargin(self) float

Sets the grid frame Margin (in layout units). This property controls distance between the map frame and the grid frame.

See also

setFrameMargin()

New in version 3.6.

Return type:

float

framePenColor(self) QColor

Retrieves the color of the stroke drawn in the grid frame.

See also

framePenSize()

Return type:

QColor

framePenSize(self) float

Retrieves the width of the stroke drawn in the grid frame.

See also

framePenColor()

Return type:

float

frameSideFlags(self) QgsLayoutItemMapGrid.FrameSideFlags

Returns the flags which control which sides of the map item the grid frame is drawn on.

Return type:

QgsLayoutItemMapGrid.FrameSideFlags

frameStyle(self) QgsLayoutItemMapGrid.FrameStyle

Returns the grid frame style.

See also

setFrameStyle()

Return type:

QgsLayoutItemMapGrid.FrameStyle

frameWidth(self) float

Gets the grid frame width in layout units. This property controls how wide the grid frame is. The size of the line outlines drawn in the frame can be retrieved via the framePenSize method.

See also

setFrameWidth()

Return type:

float

intervalX(self) float

Returns the interval between grid lines in the x-direction. The units are retrieved through the units() method.

See also

setIntervalX()

See also

intervalY()

Return type:

float

intervalY(self) float

Returns the interval between grid lines in the y-direction. The units are retrieved through the units() method.

See also

setIntervalY()

See also

intervalX()

Return type:

float

isSignalConnected(self, QMetaMethod) bool
lineSymbol(self) QgsLineSymbol

Returns the line symbol used for drawing grid lines. This is only used for grids with QgsLayoutItemMapGrid.Solid or QgsLayoutItemMapGrid.Cross styles.

See also

setLineSymbol()

See also

markerSymbol()

See also

style()

Return type:

QgsLineSymbol

markerSymbol(self) QgsMarkerSymbol

Returns the marker symbol used for drawing grid points. This is only used for grids with a QgsLayoutItemMapGrid.Markers style.

See also

lineSymbol()

See also

style()

Return type:

QgsMarkerSymbol

maxExtension(self) float

Calculates the maximum distance the grid extends beyond the QgsLayoutItemMap’s item rect (in layout units).

Return type:

float

maximumIntervalWidth(self) float

Returns the maximum width (in millimeters) for grid segments. This property is only effective if the units() is set to DynamicPageSizeBased.

See also

units()

New in version 3.10.

Return type:

float

minimumIntervalWidth(self) float

Returns the minimum width (in millimeters) for grid segments. This property is only effective if the units() is set to DynamicPageSizeBased.

See also

units()

New in version 3.10.

Return type:

float

offsetX(self) float

Returns the offset for grid lines in the x-direction. The units are retrieved through the units() method.

See also

setOffsetX()

See also

offsetY()

Return type:

float

offsetY(self) float

Returns the offset for grid lines in the y-direction. The units are retrieved through the units() method.

See also

setOffsetY()

See also

offsetX()

Return type:

float

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

readXml(self, itemElem: QDomElement, doc: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool

receivers(self, PYQT_SIGNAL) int
refresh(self)
rotatedAnnotationsEnabled(self) float

Gets whether annotations rotation for rotated or reprojected grids is enabled.

New in version 3.16.

Return type:

float

rotatedAnnotationsLengthMode(self) QgsLayoutItemMapGrid.TickLengthMode

Returns the annotation length calculation mode.

New in version 3.16.

Return type:

QgsLayoutItemMapGrid.TickLengthMode

rotatedAnnotationsMarginToCorner(self) float

Gets the margin to corners (in canvas units) below which outwards facing annotations are not drawn.

New in version 3.16.

Return type:

float

rotatedAnnotationsMinimumAngle(self) float

Gets the minimum angle (in degrees) below which annotations are not drawn.

New in version 3.16.

Return type:

float

rotatedTicksEnabled(self) float

Gets whether ticks rotation for rotated or reprojected grids is enabled.

New in version 3.16.

Return type:

float

rotatedTicksLengthMode(self) QgsLayoutItemMapGrid.TickLengthMode

Returns the grid frame style.

New in version 3.16.

Return type:

QgsLayoutItemMapGrid.TickLengthMode

rotatedTicksMarginToCorner(self) float

Gets the margin to corners (in canvas units) below which outwards facing ticks are not drawn.

New in version 3.16.

Return type:

float

rotatedTicksMinimumAngle(self) float

Gets the minimum angle (in degrees) below which ticks are not drawn.

New in version 3.16.

Return type:

float

sender(self) QObject
senderSignalIndex(self) int
setAnnotationDirection(self, direction: QgsLayoutItemMapGrid.AnnotationDirection, side: QgsLayoutItemMapGrid.BorderSide)

Sets the direction for drawing frame annotations for the specified map side.

setAnnotationDirection(self, direction: QgsLayoutItemMapGrid.AnnotationDirection) Sets the direction for drawing all frame annotations.

Parameters:
setAnnotationDisplay(self, display: QgsLayoutItemMapGrid.DisplayMode, border: QgsLayoutItemMapGrid.BorderSide)

Sets what types of grid annotations should be drawn for a specified side of the map frame, or whether grid annotations should be disabled for the side.

Parameters:
setAnnotationEnabled(self, enabled: bool)

Sets whether annotations should be shown for the grid.

Parameters:

enabled (bool) –

setAnnotationExpression(self, expression: str)

Sets the expression used for drawing grid annotations. This is only used when annotationFormat() is QgsLayoutItemMapGrid.CustomFormat.

Parameters:

expression (str) –

setAnnotationFont(self, font: QFont)

Sets the font used for drawing grid annotations. Shortcut for annotationTextFormat().setFont().

See also

annotationFont()

Deprecated since version use: setAnnotationTextFormat() instead

Parameters:

font (QFont) –

setAnnotationFontColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the font color used for drawing grid annotations. Shortcut for annotationTextFormat().setColor() and annotationTextFormat().setOpacity().

Deprecated since version use: setAnnotationTextFormat() instead

Parameters:

color (Union[QColor) –

setAnnotationFormat(self, format: QgsLayoutItemMapGrid.AnnotationFormat)

Sets the format for drawing grid annotations.

Parameters:

format (QgsLayoutItemMapGrid.AnnotationFormat) –

setAnnotationFrameDistance(self, distance: float)

Sets the distance between the map frame and annotations. Units are layout units.

Parameters:

distance (float) –

setAnnotationPosition(self, position: QgsLayoutItemMapGrid.AnnotationPosition, side: QgsLayoutItemMapGrid.BorderSide)

Sets the position for the grid annotations on a specified side of the map frame.

Parameters:
setAnnotationPrecision(self, precision: int)

Sets the coordinate precision for grid annotations. The precision indicates the number of decimal places to show when drawing grid annotations.

Parameters:

precision (int) –

setAnnotationTextFormat(self, format: QgsTextFormat)

Sets the text format to use when rendering grid annotations.

New in version 3.16.

Parameters:

format (QgsTextFormat) –

setBlendMode(self, mode: QPainter.CompositionMode)

Sets the blending mode used for drawing the grid.

See also

blendMode()

Parameters:

mode (QPainter.CompositionMode) –

setCrossLength(self, length: float)

Sets the length (in layout units) of the cross segments drawn for the grid. This is only used for grids with QgsLayoutItemMapGrid.Cross styles.

See also

crossLength()

Parameters:

length (float) –

setCrs(self, crs: QgsCoordinateReferenceSystem)

Sets the crs for the grid.

See also

crs()

Parameters:

crs (QgsCoordinateReferenceSystem) –

setEnabled(self, enabled: bool)
Parameters:

enabled (bool) –

setFrameDivisions(self, divisions: QgsLayoutItemMapGrid.DisplayMode, side: QgsLayoutItemMapGrid.BorderSide)

Sets what type of grid divisions should be used for frames on a specified side of the map.

See also

frameDivisions()

Parameters:
setFrameFillColor1(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the first fill color used for the grid frame.

Parameters:

color (Union[QColor) –

setFrameFillColor2(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the second fill color used for the grid frame.

Parameters:

color (Union[QColor) –

setFrameMargin(self, margin: float)

Sets the grid frame margin (in layout units). This property controls distance between the map frame and the grid frame.

See also

frameMargin()

New in version 3.6.

Parameters:

margin (float) –

setFramePenColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the color of the stroke drawn in the grid frame.

See also

framePenColor()

Parameters:

color (Union[QColor) –

setFramePenSize(self, width: float)

Sets the width of the stroke drawn in the grid frame.

See also

framePenSize()

Parameters:

width (float) –

setFrameSideFlag(self, flag: QgsLayoutItemMapGrid.FrameSideFlag, on: bool = True)

Sets whether the grid frame is drawn for a certain side of the map item.

Parameters:

See also

frameSideFlags()

setFrameSideFlags(self, flags: QgsLayoutItemMapGrid.FrameSideFlags | QgsLayoutItemMapGrid.FrameSideFlag)

Sets flags for grid frame sides. Setting these flags controls which sides of the map item the grid frame is drawn on.

See also

frameSideFlags()

Parameters:

flags (Union[QgsLayoutItemMapGrid.FrameSideFlags) –

setFrameStyle(self, style: QgsLayoutItemMapGrid.FrameStyle)

Sets the grid frame style.

See also

frameStyle()

Parameters:

style (QgsLayoutItemMapGrid.FrameStyle) –

setFrameWidth(self, width: float)

Sets the grid frame width (in layout units). This property controls how wide the grid frame is. The size of the line outlines drawn in the frame is controlled through the setFramePenSize method.

See also

frameWidth()

Parameters:

width (float) –

setGridLineColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the color of grid lines. This is only used for grids with QgsLayoutItemMapGrid.Solid or QgsLayoutItemMapGrid.Cross styles. For more control over grid line appearance, use setLineSymbol instead.

See also

setLineSymbol()

Parameters:

color (Union[QColor) –

setGridLineWidth(self, width: float)

Sets the width of grid lines (in layout units). This is only used for grids with QgsLayoutItemMapGrid.Solid or QgsLayoutItemMapGrid.Cross styles. For more control over grid line appearance, use setLineSymbol instead.

See also

setLineSymbol()

Parameters:

width (float) –

setIntervalX(self, interval: float)

Sets the interval between grid lines in the x-direction. The units are controlled through the setUnits method

See also

setIntervalY()

See also

intervalX()

Parameters:

interval (float) –

setIntervalY(self, interval: float)

Sets the interval between grid lines in the y-direction. The units are controlled through the setUnits method

See also

setIntervalX()

See also

intervalY()

Parameters:

interval (float) –

setLineSymbol(self, symbol: QgsLineSymbol)

Sets the line symbol used for drawing grid lines. This is only used for grids with QgsLayoutItemMapGrid.Solid or QgsLayoutItemMapGrid.Cross styles. Ownership of symbol is transferred to the grid.

See also

lineSymbol()

See also

setStyle()

Parameters:

symbol (QgsLineSymbol) –

setMarkerSymbol(self, symbol: QgsMarkerSymbol)

Sets the marker symbol used for drawing grid points. This is only used for grids with a QgsLayoutItemMapGrid.Markers style. Ownership of symbol is transferred to the grid.

See also

markerSymbol()

See also

setLineSymbol()

See also

setStyle()

Parameters:

symbol (QgsMarkerSymbol) –

setMaximumIntervalWidth(self, width: float)

Sets the maximum width (in millimeters) for grid segments. This property is only effective if the units() is set to DynamicPageSizeBased.

See also

setUnits()

New in version 3.10.

Parameters:

width (float) –

setMinimumIntervalWidth(self, width: float)

Sets the minimum width (in millimeters) for grid segments. This property is only effective if the units() is set to DynamicPageSizeBased.

See also

setUnits()

New in version 3.10.

Parameters:

width (float) –

setOffsetX(self, offset: float)

Sets the offset for grid lines in the x-direction. The units are controlled through the setUnits method.

See also

setOffsetY()

See also

offsetX()

Parameters:

offset (float) –

setOffsetY(self, offset: float)

Sets the offset for grid lines in the y-direction. The units are controlled through the setUnits method.

See also

setOffsetX()

See also

offsetY()

Parameters:

offset (float) –

setRotatedAnnotationsEnabled(self, state: bool)

Enable/disable annotations rotation for rotated or reprojected grids.

New in version 3.16.

Parameters:

state (bool) –

setRotatedAnnotationsLengthMode(self, mode: QgsLayoutItemMapGrid.TickLengthMode)

Sets the annotation length calculation mode.

New in version 3.16.

Parameters:

mode (QgsLayoutItemMapGrid.TickLengthMode) –

setRotatedAnnotationsMarginToCorner(self, margin: float)

Sets the margin to corners (in canvas units) below which outwards facing annotations are not drawn.

New in version 3.16.

Parameters:

margin (float) –

setRotatedAnnotationsMinimumAngle(self, angle: float)

Sets the minimum angle (in degrees) below which annotations are not drawn.

New in version 3.16.

Parameters:

angle (float) –

setRotatedTicksEnabled(self, state: bool)

Enable/disable ticks rotation for rotated or reprojected grids.

New in version 3.16.

Parameters:

state (bool) –

setRotatedTicksLengthMode(self, mode: QgsLayoutItemMapGrid.TickLengthMode)

Sets the tick length calculation mode.

New in version 3.16.

Parameters:

mode (QgsLayoutItemMapGrid.TickLengthMode) –

setRotatedTicksMarginToCorner(self, margin: float)

Sets the margin to corners (in canvas units) below which outwards facing ticks are not drawn.

New in version 3.16.

Parameters:

margin (float) –

setRotatedTicksMinimumAngle(self, angle: float)

Sets the minimum angle (in degrees) below which ticks are not drawn.

New in version 3.16.

Parameters:

angle (float) –

setStyle(self, style: QgsLayoutItemMapGrid.GridStyle)

Sets the grid style, which controls how the grid is drawn over the map’s contents.

See also

style()

Parameters:

style (QgsLayoutItemMapGrid.GridStyle) –

setUnits(self, unit: QgsLayoutItemMapGrid.GridUnit)

Sets the unit to use for grid measurements such as the interval and offset for grid lines.

See also

units()

Parameters:

unit (QgsLayoutItemMapGrid.GridUnit) –

style(self) QgsLayoutItemMapGrid.GridStyle

Returns the grid’s style, which controls how the grid is drawn over the map’s contents.

See also

setStyle()

Return type:

QgsLayoutItemMapGrid.GridStyle

testFrameSideFlag(self, flag: QgsLayoutItemMapGrid.FrameSideFlag) bool

Tests whether the grid frame should be drawn on a specified side of the map item.

Parameters:

flag (QgsLayoutItemMapGrid.FrameSideFlag) – flag for grid frame side

Return type:

bool

Returns:

True if grid frame should be drawn for that side of the map

See also

frameSideFlags()

timerEvent(self, QTimerEvent)
units(self) QgsLayoutItemMapGrid.GridUnit

Returns the units used for grid measurements such as the interval and offset for grid lines.

See also

setUnits()

Return type:

QgsLayoutItemMapGrid.GridUnit

usesAdvancedEffects(self) bool
Return type:

bool

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

writeXml(self, elem: QDomElement, doc: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool