QgsLayoutView class

A graphical widget to display and interact with QgsLayouts.

Reference

QgsLayoutView manages the layout interaction tools and mouse/key events.

Public types

enum ClipboardOperation { ClipboardCut, ClipboardCopy }: Clipboard operations.
enum PasteMode { PasteModeCursor, PasteModeCenter, PasteModeInPlace }: Paste modes.

Constructors, destructors, conversion operators

QgsLayoutView(QWidget* parent = nullptr): Constructor for QgsLayoutView.

Public functions

void alignSelectedItems(QgsLayoutAligner::Alignment alignment): Aligns all selected items using the specified alignment.
void copyItems(const QList<QgsLayoutItem*>& items, ClipboardOperation operation): Cuts or copies the a list of items, respecting the specified operation.
void copySelectedItems(ClipboardOperation operation): Cuts or copies the selected items, respecting the specified operation.
auto currentLayout() -> QgsLayout*: Returns the current layout associated with the view.
auto currentLayout() const -> const QgsLayout*: Returns the current layout associated with the view.
auto currentPage() const -> int: Returns the page visible in the view.
auto deltaForKeyEvent(QKeyEvent* event) -> QPointF: Returns the delta (in layout coordinates) by which to move items for the given key event.
void distributeSelectedItems(QgsLayoutAligner::Distribution distribution): Distributes all selected items using the specified distribution.
auto hasItemsInClipboard() const -> bool: Returns true if the current clipboard contains layout items.
auto menuProvider() const -> QgsLayoutViewMenuProvider*: Returns the provider for context menus.
auto pasteItems(PasteMode mode) -> QList<QgsLayoutItem*>: Pastes items from clipboard, using the specified mode.
auto pasteItems(QPointF layoutPoint) -> QList<QgsLayoutItem*>: Pastes items from clipboard, at the specified layoutPoint, in layout units.
auto previewMode() const -> QgsPreviewEffect::PreviewMode: Returns the preview mode which may be used to modify the view's appearance.
auto previewModeEnabled() const -> bool: Returns true if a preview effect is being used to alter the view's appearance.
void resizeSelectedItems(QgsLayoutAligner::Resize resize): Resizes all selected items using the specified resize mode.
void scaleSafe(double scale): Scales the view in a safe way, by limiting the acceptable range of the scale applied.
void setCurrentLayout(QgsLayout* layout): Sets the current layout to edit in the view.
void setHorizontalRuler(QgsLayoutRuler* ruler): Sets a horizontal ruler to synchronize with the view state.
void setMenuProvider(QgsLayoutViewMenuProvider* provider): Sets a provider for context menus.
void setPaintingEnabled(bool enabled): Sets whether widget repainting should be allowed for the view.
void setPreviewMode(QgsPreviewEffect::PreviewMode mode): Sets the preview mode which should be used to modify the view's appearance.
void setPreviewModeEnabled(bool enabled): Sets whether a preview effect should be used to alter the view's appearance.
void setSectionLabel(const QString& label): Sets a section label, to display above the first page shown in the view.
void setTool(QgsLayoutViewTool* tool): Sets the tool currently being used in the view.
void setVerticalRuler(QgsLayoutRuler* ruler): Sets a vertical ruler to synchronize with the view state.
void setZoomLevel(double level): Sets the zoom level for the view, where a zoom level of 1.0 corresponds to 100%.
auto tool() -> QgsLayoutViewTool*: Returns the currently active tool for the view.
void unsetTool(QgsLayoutViewTool* tool): Unsets the current view tool, if it matches the specified tool.
auto visiblePageNumbers() const -> QList<int>: Returns a list of page numbers for pages which are currently visible in the view.
auto visiblePages() const -> QList<QgsLayoutItemPage*>: Returns a list of page items which are currently visible in the view.

Signals

void cursorPosChanged(QPointF layoutPoint): Is emitted when the mouse cursor coordinates change within the view.
void itemFocused(QgsLayoutItem* item): Emitted when an item is "focused" in the view, i.e.
void layoutSet(QgsLayout* layout): Emitted when a layout is set for the view.
void pageChanged(int page): Emitted when the page visible in the view is changed.
void statusMessage(const QString& message): Emitted when the view has a message for display in a parent window's status bar.
void toolSet(QgsLayoutViewTool* tool): Emitted when the current tool is changed.
void willBeDeleted(): Emitted in the destructor when the view is about to be deleted, but is still in a perfectly valid state.
void zoomLevelChanged(): Is emitted whenever the zoom level of the view is changed.

Public slots

void deleteItems(const QList<QgsLayoutItem*>& items): Delete the specified items.
void deleteSelectedItems(): Deletes all selected items.
void deselectAll(): Deselects all items in the view.
void emitZoomLevelChanged(): Emits the zoomLevelChanged() signal.
void groupSelectedItems(): Groups all selected items.
void invertSelection(): Inverts the current selection, selecting deselected items and deselecting and selected items.
void lockSelectedItems(): Locks any selected items, preventing them from being interacted with by mouse interactions.
void lowerSelectedItems(): Lowers the selected items down the z-order.
void moveSelectedItemsToBottom(): Lowers the selected items to the bottom of the z-order.
void moveSelectedItemsToTop(): Raises the selected items to the top of the z-order.
void pushStatusMessage(const QString& message): Pushes a new status bar message to the view.
void raiseSelectedItems(): Raises the selected items up the z-order.
void selectAll(): Selects all items in the view.
void selectNextItemAbove(): Selects the next item above the existing selection, by item z order.
void selectNextItemBelow(): Selects the next item below the existing selection, by item z order.
void ungroupSelectedItems(): Ungroups all selected items.
void unlockAllItems(): Unlocks all locked items in the layout.
void viewChanged(): Updates associated rulers and other widgets after view extent or zoom has changed.
void zoomActual(): Zooms to the actual size of the layout.
void zoomFull(): Zooms the view to the full extent of the layout.
void zoomIn(): Zooms in to the view by a preset amount.
void zoomOut(): Zooms out of the view by a preset amount.
void zoomWidth(): Zooms the view to the full width of the layout.

Enum documentation

enum QgsLayoutView::ClipboardOperation

Clipboard operations.

Enumerators
ClipboardCut	Cut items.
ClipboardCopy	Copy items.

enum QgsLayoutView::PasteMode

Paste modes.

Enumerators
PasteModeCursor	Paste items at cursor position.
PasteModeCenter	Paste items in center of view.
PasteModeInPlace	Paste items in place.

Function documentation

void QgsLayoutView::alignSelectedItems(QgsLayoutAligner::Alignment alignment)

Aligns all selected items using the specified alignment.

void QgsLayoutView::copyItems(const QList<QgsLayoutItem*>& items, ClipboardOperation operation)

Cuts or copies the a list of items, respecting the specified operation.

void QgsLayoutView::copySelectedItems(ClipboardOperation operation)

Cuts or copies the selected items, respecting the specified operation.

QgsLayout* QgsLayoutView::currentLayout()

Returns the current layout associated with the view.

const QgsLayout* QgsLayoutView::currentLayout() const

Returns the current layout associated with the view.

int QgsLayoutView::currentPage() const

Returns the page visible in the view.

This method considers the page at the center of the view as the current visible page.

void QgsLayoutView::distributeSelectedItems(QgsLayoutAligner::Distribution distribution)

Distributes all selected items using the specified distribution.

bool QgsLayoutView::hasItemsInClipboard() const

Returns true if the current clipboard contains layout items.

QgsLayoutViewMenuProvider* QgsLayoutView::menuProvider() const

Returns the provider for context menus.

Returned value may be nullptr if no provider is set.

QList<QgsLayoutItem*> QgsLayoutView::pasteItems(PasteMode mode)

Pastes items from clipboard, using the specified mode.

A list of pasted items is returned.

QList<QgsLayoutItem*> QgsLayoutView::pasteItems(QPointF layoutPoint)

Pastes items from clipboard, at the specified layoutPoint, in layout units.

A list of pasted items is returned.

QgsPreviewEffect::PreviewMode QgsLayoutView::previewMode() const

Returns the preview mode which may be used to modify the view's appearance.

Preview modes are only used if previewModeEnabled() is true.

bool QgsLayoutView::previewModeEnabled() const

Returns true if a preview effect is being used to alter the view's appearance.

void QgsLayoutView::resizeSelectedItems(QgsLayoutAligner::Resize resize)

Resizes all selected items using the specified resize mode.

void QgsLayoutView::scaleSafe(double scale)

Scales the view in a safe way, by limiting the acceptable range of the scale applied.

The scale parameter specifies the zoom factor to scale the view by.

void QgsLayoutView::setCurrentLayout(QgsLayout* layout)

Sets the current layout to edit in the view.

void QgsLayoutView::setHorizontalRuler(QgsLayoutRuler* ruler)

Sets a horizontal ruler to synchronize with the view state.

void QgsLayoutView::setMenuProvider(QgsLayoutViewMenuProvider* provider)

Sets a provider for context menus.

Ownership of the provider is transferred to the view.

void QgsLayoutView::setPaintingEnabled(bool enabled)

Sets whether widget repainting should be allowed for the view.

This is used to temporarily halt painting while exporting layouts.

void QgsLayoutView::setPreviewMode(QgsPreviewEffect::PreviewMode mode)

Sets the preview mode which should be used to modify the view's appearance.

Preview modes are only used if previewModeEnabled() is true.

void QgsLayoutView::setPreviewModeEnabled(bool enabled)

Sets whether a preview effect should be used to alter the view's appearance.

Parameters
enabled	Set to true to enable the preview effect on the view.

void QgsLayoutView::setTool(QgsLayoutViewTool* tool)

Sets the tool currently being used in the view.

void QgsLayoutView::setVerticalRuler(QgsLayoutRuler* ruler)

Sets a vertical ruler to synchronize with the view state.

QgsLayoutViewTool* QgsLayoutView::tool()

Returns the currently active tool for the view.

void QgsLayoutView::unsetTool(QgsLayoutViewTool* tool)

Unsets the current view tool, if it matches the specified tool.

This is called from destructor of view tools to make sure that the tool won't be used any more. You don't have to call it manually, QgsLayoutViewTool takes care of it.

QList<int> QgsLayoutView::visiblePageNumbers() const

Returns a list of page numbers for pages which are currently visible in the view.

QList<QgsLayoutItemPage*> QgsLayoutView::visiblePages() const

Returns a list of page items which are currently visible in the view.

void QgsLayoutView::cursorPosChanged(QPointF layoutPoint) signal

Is emitted when the mouse cursor coordinates change within the view.

The layoutPoint argument indicates the cursor position within the layout coordinate system.

void QgsLayoutView::itemFocused(QgsLayoutItem* item) signal

Emitted when an item is "focused" in the view, i.e.

it becomes the active item and should have its properties displayed in any designer windows.

void QgsLayoutView::layoutSet(QgsLayout* layout) signal

Emitted when a layout is set for the view.

void QgsLayoutView::pageChanged(int page) signal

Emitted when the page visible in the view is changed.

This signal considers the page at the center of the view as the current visible page.

void QgsLayoutView::statusMessage(const QString& message) signal

Emitted when the view has a message for display in a parent window's status bar.

void QgsLayoutView::toolSet(QgsLayoutViewTool* tool) signal

Emitted when the current tool is changed.

void QgsLayoutView::deleteItems(const QList<QgsLayoutItem*>& items) public slot

Delete the specified items.

void QgsLayoutView::deleteSelectedItems() public slot

Deletes all selected items.

void QgsLayoutView::deselectAll() public slot

Deselects all items in the view.

void QgsLayoutView::emitZoomLevelChanged() public slot

Emits the zoomLevelChanged() signal.

This should be called after calling any of the QGraphicsView base class methods which alter the view's zoom level, i.e. QGraphicsView::fitInView().

void QgsLayoutView::groupSelectedItems() public slot

Groups all selected items.

void QgsLayoutView::invertSelection() public slot

Inverts the current selection, selecting deselected items and deselecting and selected items.

void QgsLayoutView::lockSelectedItems() public slot

Locks any selected items, preventing them from being interacted with by mouse interactions.

void QgsLayoutView::lowerSelectedItems() public slot

Lowers the selected items down the z-order.

void QgsLayoutView::moveSelectedItemsToBottom() public slot

Lowers the selected items to the bottom of the z-order.

void QgsLayoutView::moveSelectedItemsToTop() public slot

Raises the selected items to the top of the z-order.

void QgsLayoutView::pushStatusMessage(const QString& message) public slot

Pushes a new status bar message to the view.

This causes statusMessage() to be emitted, which should cause the message to appear in the status bar for the parent window.

void QgsLayoutView::raiseSelectedItems() public slot

Raises the selected items up the z-order.

void QgsLayoutView::selectAll() public slot

Selects all items in the view.

void QgsLayoutView::selectNextItemAbove() public slot

Selects the next item above the existing selection, by item z order.

void QgsLayoutView::selectNextItemBelow() public slot

Selects the next item below the existing selection, by item z order.

void QgsLayoutView::ungroupSelectedItems() public slot

Ungroups all selected items.

void QgsLayoutView::unlockAllItems() public slot

Unlocks all locked items in the layout.

void QgsLayoutView::viewChanged() public slot

Updates associated rulers and other widgets after view extent or zoom has changed.

This should be called after calling any of the QGraphicsView base class methods which alter the view's zoom level or extent, i.e. QGraphicsView::fitInView().

void QgsLayoutView::zoomActual() public slot

Zooms to the actual size of the layout.

void QgsLayoutView::zoomFull() public slot

Zooms the view to the full extent of the layout.

void QgsLayoutView::zoomIn() public slot

Zooms in to the view by a preset amount.

void QgsLayoutView::zoomOut() public slot

Zooms out of the view by a preset amount.

void QgsLayoutView::zoomWidth() public slot

Zooms the view to the full width of the layout.