diff --git a/python/auto_sip.blacklist b/python/auto_sip.blacklist index 9526f0481e7..989901af3e8 100644 --- a/python/auto_sip.blacklist +++ b/python/auto_sip.blacklist @@ -1,14 +1,5 @@ core/conversions.sip core/qgsexception.sip -core/composer/qgscomposerutils.sip -core/composer/qgscomposition.sip -core/composer/qgsdoubleboxscalebarstyle.sip -core/composer/qgslayoutmanager.sip -core/composer/qgsnumericscalebarstyle.sip -core/composer/qgspaperitem.sip -core/composer/qgsscalebarstyle.sip -core/composer/qgssingleboxscalebarstyle.sip -core/composer/qgsticksscalebarstyle.sip analysis/vector/qgsgeometryanalyzer.sip analysis/vector/qgsgeometrysnapper.sip analysis/vector/qgspointsample.sip diff --git a/python/core/composer/qgscomposerutils.sip b/python/core/composer/qgscomposerutils.sip index 5acc7c00620..89479e78056 100644 --- a/python/core/composer/qgscomposerutils.sip +++ b/python/core/composer/qgscomposerutils.sip @@ -1,227 +1,305 @@ -/** \ingroup core - * Utilities for compositions. - */ +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/composer/qgscomposerutils.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ + + + + class QgsComposerUtils { -%TypeHeaderCode -#include +%Docstring + Utilities for compositions. %End +%TypeHeaderCode +#include "qgscomposerutils.h" +%End public: - /** Draws an arrow head on to a QPainter. - * @param p destination painter - * @param x x-coordinate of arrow center - * @param y y-coordinate of arrow center - * @param angle angle in degrees which arrow should point toward, measured - * clockwise from pointing vertical upward - * @param arrowHeadWidth size of arrow head - */ static void drawArrowHead( QPainter *p, const double x, const double y, const double angle, const double arrowHeadWidth ); +%Docstring + Draws an arrow head on to a QPainter. + \param p destination painter + \param x x-coordinate of arrow center + \param y y-coordinate of arrow center + \param angle angle in degrees which arrow should point toward, measured + clockwise from pointing vertical upward + \param arrowHeadWidth size of arrow head +%End - /** Calculates the angle of the line from p1 to p2 (counter clockwise, - * starting from a line from north to south) - * @param p1 start point of line - * @param p2 end point of line - * @returns angle in degrees, clockwise from south - */ static double angle( QPointF p1, QPointF p2 ); +%Docstring + Calculates the angle of the line from p1 to p2 (counter clockwise, + starting from a line from north to south) + \param p1 start point of line + \param p2 end point of line + :return: angle in degrees, clockwise from south + :rtype: float +%End - /** Rotates a point / vector around the origin. - * @param angle rotation angle in degrees, counterclockwise - * @param x in/out: x coordinate before / after the rotation - * @param y in/out: y cooreinate before / after the rotation - */ static void rotate( const double angle, double &x, double &y ); +%Docstring + Rotates a point / vector around the origin. + \param angle rotation angle in degrees, counterclockwise + \param x in/out: x coordinate before / after the rotation + \param y in/out: y cooreinate before / after the rotation +%End - /** Ensures that an angle is in the range 0 <= angle < 360 - * @param angle angle in degrees - * @returns equivalent angle within the range [0, 360) - * @see snappedAngle - */ static double normalizedAngle( const double angle ); +%Docstring + Ensures that an angle is in the range 0 <= angle < 360 + \param angle angle in degrees + :return: equivalent angle within the range [0, 360) +.. seealso:: snappedAngle + :rtype: float +%End - /** Snaps an angle to its closest 45 degree angle - * @param angle angle in degrees - * @returns angle snapped to 0, 45/90/135/180/225/270 or 315 degrees - */ static double snappedAngle( const double angle ); +%Docstring + Snaps an angle to its closest 45 degree angle + \param angle angle in degrees + :return: angle snapped to 0, 45/90/135/180/225/270 or 315 degrees + :rtype: float +%End - /** Calculates the largest scaled version of originalRect which fits within boundsRect, when it is rotated by - * a specified amount. - * @param originalRect QRectF to be rotated and scaled - * @param boundsRect QRectF specifying the bounds which the rotated and scaled rectangle must fit within - * @param rotation the rotation in degrees to be applied to the rectangle - * @returns largest scaled version of the rectangle possible - */ - static QRectF largestRotatedRectWithinBounds( const QRectF originalRect, const QRectF boundsRect, const double rotation ); + static QRectF largestRotatedRectWithinBounds( const QRectF &originalRect, const QRectF &boundsRect, const double rotation ); +%Docstring + Calculates the largest scaled version of originalRect which fits within boundsRect, when it is rotated by + a specified amount. + \param originalRect QRectF to be rotated and scaled + \param boundsRect QRectF specifying the bounds which the rotated and scaled rectangle must fit within + \param rotation the rotation in degrees to be applied to the rectangle + :return: largest scaled version of the rectangle possible + :rtype: QRectF +%End - /** Returns the size in mm corresponding to a font point size - * @param pointSize font size in points - * @see mmToPoints - */ static double pointsToMM( const double pointSize ); +%Docstring + Returns the size in mm corresponding to a font point size + \param pointSize font size in points +.. seealso:: mmToPoints + :rtype: float +%End - /** Returns the size in mm corresponding to a font point size - * @param mmSize font size in mm - * @see pointsToMM - */ static double mmToPoints( const double mmSize ); +%Docstring + Returns the size in mm corresponding to a font point size + \param mmSize font size in mm +.. seealso:: pointsToMM + :rtype: float +%End - /** Resizes a QRectF relative to a resized bounding rectangle. - * @param rectToResize QRectF to resize, contained within boundsBefore. The - * rectangle is linearly scaled to retain its relative position and size within - * boundsAfter. - * @param boundsBefore QRectF of bounds before resize - * @param boundsAfter QRectF of bounds after resize - */ static void relativeResizeRect( QRectF &rectToResize, const QRectF &boundsBefore, const QRectF &boundsAfter ); +%Docstring + Resizes a QRectF relative to a resized bounding rectangle. + \param rectToResize QRectF to resize, contained within boundsBefore. The + rectangle is linearly scaled to retain its relative position and size within + boundsAfter. + \param boundsBefore QRectF of bounds before resize + \param boundsAfter QRectF of bounds after resize +%End - /** Returns a scaled position given a before and after range - * @param position initial position within before range to scale - * @param beforeMin minimum value in before range - * @param beforeMax maximum value in before range - * @param afterMin minimum value in after range - * @param afterMax maximum value in after range - * @returns position scaled to range specified by afterMin and afterMax - */ static double relativePosition( const double position, const double beforeMin, const double beforeMax, const double afterMin, const double afterMax ); +%Docstring + Returns a scaled position given a before and after range + \param position initial position within before range to scale + \param beforeMin minimum value in before range + \param beforeMax maximum value in before range + \param afterMin minimum value in after range + \param afterMax maximum value in after range + :return: position scaled to range specified by afterMin and afterMax + :rtype: float +%End - /** Decodes a string representing a paper orientation - * @param orientationString string to decode - * @param ok will be true if string could be decoded - * @returns decoded paper orientation - */ static QgsComposition::PaperOrientation decodePaperOrientation( const QString &orientationString, bool &ok ); +%Docstring + Decodes a string representing a paper orientation + \param orientationString string to decode + \param ok will be true if string could be decoded + :return: decoded paper orientation + :rtype: QgsComposition.PaperOrientation +%End - /** Decodes a string representing a preset page size - * @param presetString string to decode - * @param width double for decoded paper width - * @param height double for decoded paper height - * @returns true if string could be decoded successfully - */ static bool decodePresetPaperSize( const QString &presetString, double &width, double &height ); +%Docstring + Decodes a string representing a preset page size + \param presetString string to decode + \param width double for decoded paper width + \param height double for decoded paper height + :return: true if string could be decoded successfully + :rtype: bool +%End - /** Reads all pre 3.0 data defined properties from an XML element. - * @note this method was added in version 3.0 - * @see readDataDefinedProperty - * @see writeDataDefinedPropertyMap - */ static void readOldDataDefinedPropertyMap( const QDomElement &itemElem, QgsPropertyCollection &dataDefinedProperties ); +%Docstring + Reads all pre 3.0 data defined properties from an XML element. +.. versionadded:: 3.0 +.. seealso:: readDataDefinedProperty +.. seealso:: writeDataDefinedPropertyMap +%End - /** Reads a pre 3.0 data defined property from an XML DOM element. - * @note this method was added in version 3.0 - * @see readDataDefinedPropertyMap - */ static QgsProperty readOldDataDefinedProperty( const QgsComposerObject::DataDefinedProperty property, const QDomElement &ddElem ); +%Docstring + Reads a pre 3.0 data defined property from an XML DOM element. +.. versionadded:: 3.0 +.. seealso:: readDataDefinedPropertyMap + :rtype: QgsProperty +%End - /** Returns a font where size is set in pixels and the size has been upscaled with FONT_WORKAROUND_SCALE - * to workaround QT font rendering bugs - * @param font source font with size set in points - * @returns font with size set in pixels - * @note added in version 2.5 - */ static QFont scaledFontPixelSize( const QFont &font ); +%Docstring + Returns a font where size is set in pixels and the size has been upscaled with FONT_WORKAROUND_SCALE + to workaround QT font rendering bugs + \param font source font with size set in points + :return: font with size set in pixels +.. versionadded:: 2.5 + :rtype: QFont +%End - /** Calculate font ascent in millimeters, including workarounds for QT font rendering issues - * @param font input font - * @returns font ascent in millimeters - * @note added in version 2.5 - * @see fontDescentMM - * @see fontHeightMM - * @see fontHeightCharacterMM - * @see textWidthMM - */ static double fontAscentMM( const QFont &font ); +%Docstring + Calculate font ascent in millimeters, including workarounds for QT font rendering issues + \param font input font + :return: font ascent in millimeters +.. versionadded:: 2.5 +.. seealso:: fontDescentMM +.. seealso:: fontHeightMM +.. seealso:: fontHeightCharacterMM +.. seealso:: textWidthMM + :rtype: float +%End - /** Calculate font descent in millimeters, including workarounds for QT font rendering issues - * @param font input font - * @returns font descent in millimeters - * @note added in version 2.5 - * @see fontAscentMM - * @see fontHeightMM - * @see fontHeightCharacterMM - * @see textWidthMM - */ static double fontDescentMM( const QFont &font ); +%Docstring + Calculate font descent in millimeters, including workarounds for QT font rendering issues + \param font input font + :return: font descent in millimeters +.. versionadded:: 2.5 +.. seealso:: fontAscentMM +.. seealso:: fontHeightMM +.. seealso:: fontHeightCharacterMM +.. seealso:: textWidthMM + :rtype: float +%End - /** Calculate font height in millimeters, including workarounds for QT font rendering issues - * The font height is the font ascent + descent + 1 (for the baseline). - * @param font input font - * @returns font height in millimeters - * @note added in version 2.5 - * @see fontAscentMM - * @see fontDescentMM - * @see fontHeightCharacterMM - * @see textWidthMM - */ static double fontHeightMM( const QFont &font ); +%Docstring + Calculate font height in millimeters, including workarounds for QT font rendering issues + The font height is the font ascent + descent + 1 (for the baseline). + \param font input font + :return: font height in millimeters +.. versionadded:: 2.5 +.. seealso:: fontAscentMM +.. seealso:: fontDescentMM +.. seealso:: fontHeightCharacterMM +.. seealso:: textWidthMM + :rtype: float +%End - /** Calculate font height in millimeters of a single character, including workarounds for QT font - * rendering issues - * @param font input font - * @param character character to calculate height for - * @returns character height in millimeters - * @note added in version 2.5 - * @see fontAscentMM - * @see fontDescentMM - * @see fontHeightMM - * @see textWidthMM - */ static double fontHeightCharacterMM( const QFont &font, QChar character ); +%Docstring + Calculate font height in millimeters of a single character, including workarounds for QT font + rendering issues + \param font input font + \param character character to calculate height for + :return: character height in millimeters +.. versionadded:: 2.5 +.. seealso:: fontAscentMM +.. seealso:: fontDescentMM +.. seealso:: fontHeightMM +.. seealso:: textWidthMM + :rtype: float +%End - /** Calculate font width in millimeters for a string, including workarounds for QT font - * rendering issues - * @param font input font - * @param text string to calculate width of - * @returns string width in millimeters - * @note added in version 2.5 - * @see fontAscentMM - * @see fontDescentMM - * @see fontHeightMM - * @see fontHeightCharacterMM - * @see textHeightMM - */ static double textWidthMM( const QFont &font, const QString &text ); +%Docstring + Calculate font width in millimeters for a string, including workarounds for QT font + rendering issues + \param font input font + \param text string to calculate width of + :return: string width in millimeters +.. versionadded:: 2.5 +.. seealso:: fontAscentMM +.. seealso:: fontDescentMM +.. seealso:: fontHeightMM +.. seealso:: fontHeightCharacterMM +.. seealso:: textHeightMM + :rtype: float +%End - /** Calculate font height in millimeters for a string, including workarounds for QT font - * rendering issues. Note that this method uses a non-standard measure of text height, - * where only the font ascent is considered for the first line of text. - * @param font input font - * @param text string to calculate height of - * @param multiLineHeight line spacing factor - * @returns string height in millimeters - * @note added in version 2.12 - * @see textWidthMM - */ static double textHeightMM( const QFont &font, const QString &text, double multiLineHeight = 1.0 ); +%Docstring + Calculate font height in millimeters for a string, including workarounds for QT font + rendering issues. Note that this method uses a non-standard measure of text height, + where only the font ascent is considered for the first line of text. + \param font input font + \param text string to calculate height of + \param multiLineHeight line spacing factor + :return: string height in millimeters +.. versionadded:: 2.12 +.. seealso:: textWidthMM + :rtype: float +%End - /** Draws text on a painter at a specific position, taking care of composer specific issues (calculation to pixel, - * scaling of font and painter to work around Qt font bugs) - * @param painter destination QPainter - * @param pos position to draw text - * @param text string to draw - * @param font font to use for drawing text - * @param color color to draw text - * @note added in version 2.5 - */ static void drawText( QPainter *painter, QPointF pos, const QString &text, const QFont &font, const QColor &color = QColor() ); +%Docstring + Draws text on a painter at a specific position, taking care of composer specific issues (calculation to pixel, + scaling of font and painter to work around Qt font bugs) + \param painter destination QPainter + \param pos position to draw text + \param text string to draw + \param font font to use for drawing text + \param color color to draw text +.. versionadded:: 2.5 +%End - /** Draws text on a painter within a rectangle, taking care of composer specific issues (calculation to pixel, - * scaling of font and painter to work around Qt font bugs) - * @param painter destination QPainter - * @param rect rectangle to draw into - * @param text string to draw - * @param font font to use for drawing text - * @param color color to draw text - * @param halignment optional horizontal alignment - * @param valignment optional vertical alignment - * @param flags allows for passing Qt::TextFlags to control appearance of rendered text - * @note added in version 2.5 - */ static void drawText( QPainter *painter, const QRectF &rect, const QString &text, const QFont &font, const QColor &color = QColor(), const Qt::AlignmentFlag halignment = Qt::AlignLeft, const Qt::AlignmentFlag valignment = Qt::AlignTop, const int flags = Qt::TextWordWrap ); +%Docstring + Draws text on a painter within a rectangle, taking care of composer specific issues (calculation to pixel, + scaling of font and painter to work around Qt font bugs) + \param painter destination QPainter + \param rect rectangle to draw into + \param text string to draw + \param font font to use for drawing text + \param color color to draw text + \param halignment optional horizontal alignment + \param valignment optional vertical alignment + \param flags allows for passing Qt.TextFlags to control appearance of rendered text +.. versionadded:: 2.5 +%End static QgsRenderContext createRenderContextForMap( QgsComposerMap *map, QPainter *painter, double dpi = -1 ); +%Docstring + Creates a render context suitable for the specified composer ``map`` and ``painter`` destination. + This method returns a new QgsRenderContext which matches the scale and settings of the + target map. If the ``dpi`` argument is not specified then the dpi will be taken from the destinatation + painter device. +.. versionadded:: 3.0 +.. seealso:: createRenderContextForComposition() + :rtype: QgsRenderContext +%End + static QgsRenderContext createRenderContextForComposition( QgsComposition *composition, QPainter *painter ); +%Docstring + Creates a render context suitable for the specified ``composition`` and ``painter`` destination. + This method returns a new QgsRenderContext which matches the scale and settings from the composition's + QgsComposition.referenceMap(). +.. versionadded:: 3.0 +.. seealso:: createRenderContextForMap() + :rtype: QgsRenderContext +%End + }; + +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/composer/qgscomposerutils.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ diff --git a/python/core/composer/qgscomposition.sip b/python/core/composer/qgscomposition.sip index b0f963a2956..28866dfaa4c 100644 --- a/python/core/composer/qgscomposition.sip +++ b/python/core/composer/qgscomposition.sip @@ -1,9 +1,28 @@ +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/composer/qgscomposition.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ + + + + + class QgsComposition : QGraphicsScene, QgsExpressionContextGenerator { -%TypeHeaderCode -#include +%Docstring + Graphics scene for map printing. The class manages the paper item which always + is the item in the back (z-value 0). It maintains the z-Values of the items and stores + them in a list in ascending z-Order. This list can be changed to lower/raise items one position + or to bring them to front/back. + * %End +%TypeHeaderCode +#include "qgscomposition.h" +%End public: enum PlotStyle @@ -33,6 +52,9 @@ class QgsComposition : QGraphicsScene, QgsExpressionContextGenerator }; explicit QgsComposition( QgsProject *project ); +%Docstring + Construct a new composition linked to the specified project. +%End enum AtlasMode { @@ -44,247 +66,521 @@ class QgsComposition : QGraphicsScene, QgsExpressionContextGenerator ~QgsComposition(); QgsProject *project() const; +%Docstring + The project associated with the composition. Used to get access to layers, map themes, + relations and various other bits. It is never null. + +.. versionadded:: 3.0 + :rtype: QgsProject +%End + QString name() const; +%Docstring + Returns the composition's name. +.. seealso:: setName() +.. versionadded:: 3.0 + :rtype: str +%End + void setName( const QString &name ); +%Docstring + Sets the composition's name. +.. seealso:: name() +.. versionadded:: 3.0 +%End + void setPaperSize( double width, double height, bool keepRelativeItemPosition = true ); +%Docstring + Changes size of paper item. + \param width page width in mm + \param height page height in mm + \param keepRelativeItemPosition if true, all items and guides will be moved so that they retain + their same relative position to the top left corner of their current page. +.. seealso:: paperHeight +.. seealso:: paperWidth +%End + double paperHeight() const; +%Docstring + Height of paper item + :return: height in mm +.. seealso:: paperWidth +.. seealso:: setPaperSize + :rtype: float +%End + double paperWidth() const; +%Docstring + Width of paper item + :return: width in mm +.. seealso:: paperHeight +.. seealso:: setPaperSize + :rtype: float +%End + void resizePageToContents( double marginTop = 0.0, double marginRight = 0.0, double marginBottom = 0.0, double marginLeft = 0.0 ); +%Docstring + Resizes the composition page to fit the current contents of the composition. + Calling this method resets the number of pages to 1, with the size set to the + minimum size required to fit all existing composer items. Items will also be + repositioned so that the new top-left bounds of the composition is at the point + (marginLeft, marginTop). An optional margin can be specified. + \param marginTop top margin (millimeters) + \param marginRight right margin (millimeters) + \param marginBottom bottom margin (millimeters) + \param marginLeft left margin (millimeters) +.. versionadded:: 2.12 +.. seealso:: setResizeToContentsMargins() +.. seealso:: resizeToContentsMargins() +%End + void setResizeToContentsMargins( double marginTop, double marginRight, double marginBottom, double marginLeft ); +%Docstring + Sets the resize to contents margins. These margins are saved in the composition + so that they can be restored with the composer. + \param marginTop top margin (millimeters) + \param marginRight right margin (millimeters) + \param marginBottom bottom margin (millimeters) + \param marginLeft left margin (millimeters) +.. versionadded:: 2.12 +.. seealso:: resizePageToContents() +.. seealso:: resizeToContentsMargins() +%End + void resizeToContentsMargins( double &marginTop /Out/, double &marginRight /Out/, double &marginBottom /Out/, double &marginLeft /Out/ ) const; +%Docstring + Returns the resize to contents margins. These margins are saved in the composition + so that they can be restored with the composer. + \param marginTop reference for top margin (millimeters) + \param marginRight reference for right margin (millimeters) + \param marginBottom reference for bottom margin (millimeters) + \param marginLeft reference for left margin (millimeters) +.. versionadded:: 2.12 +.. seealso:: resizePageToContents() +.. seealso:: setResizeToContentsMargins() +%End + double spaceBetweenPages() const; +%Docstring + Returns the vertical space between pages in a composer view + :return: space between pages in mm + :rtype: float +%End + void setNumPages( const int pages ); +%Docstring + Sets the number of pages for the composition. + \param pages number of pages +.. seealso:: numPages +%End + int numPages() const; +%Docstring + Returns the number of pages in the composition. + :return: number of pages +.. seealso:: setNumPages + :rtype: int +%End + bool pageIsEmpty( const int page ) const; +%Docstring + Returns whether a page is empty, ie, it contains no items except for the background + paper item. + \param page page number, starting with 1 + :return: true if page is empty +.. versionadded:: 2.5 +.. seealso:: numPages +.. seealso:: setNumPages +.. seealso:: shouldExportPage + :rtype: bool +%End + bool shouldExportPage( const int page ) const; +%Docstring + Returns whether a specified page number should be included in exports of the composition. + \param page page number, starting with 1 + :return: true if page should be exported +.. versionadded:: 2.5 +.. seealso:: numPages +.. seealso:: pageIsEmpty + :rtype: bool +%End + void setPageStyleSymbol( QgsFillSymbol *symbol ); +%Docstring +Note: added in version 2.1 +%End QgsFillSymbol *pageStyleSymbol(); +%Docstring +Note: added in version 2.1 + :rtype: QgsFillSymbol +%End + QPointF positionOnPage( QPointF position ) const; +%Docstring + Returns the position within a page of a point in the composition +.. versionadded:: 2.1 + :rtype: QPointF +%End + int pageNumberForPoint( QPointF position ) const; +%Docstring + Returns the page number corresponding to a point in the composition +.. versionadded:: 2.1 + :rtype: int +%End + void setStatusMessage( const QString &message ); +%Docstring + Sets the status bar message for the composer window +.. versionadded:: 2.1 +%End + void updateSettings(); +%Docstring + Refreshes the composition when composer related options change +.. versionadded:: 2.1 +%End void setSnapToGridEnabled( const bool b ); bool snapToGridEnabled() const; +%Docstring + :rtype: bool +%End void setGridVisible( const bool b ); bool gridVisible() const; +%Docstring + :rtype: bool +%End void setSnapLinesVisible( const bool visible ); +%Docstring +Hides / shows custom snap lines +%End bool snapLinesVisible() const; +%Docstring + :rtype: bool +%End void setAlignmentSnap( const bool s ); bool alignmentSnap() const; +%Docstring + :rtype: bool +%End void setSmartGuidesEnabled( const bool b ); bool smartGuidesEnabled() const; +%Docstring + :rtype: bool +%End - /** Sets whether the page items should be visible in the composition. Removing - * them will prevent both display of the page boundaries in composer views and - * will also prevent them from being rendered in composition exports. - * @param visible set to true to show pages, false to hide pages - * @note added in QGIS 2.12 - * @see pagesVisible() - */ void setPagesVisible( bool visible ); +%Docstring + Sets whether the page items should be visible in the composition. Removing + them will prevent both display of the page boundaries in composer views and + will also prevent them from being rendered in composition exports. + \param visible set to true to show pages, false to hide pages +.. versionadded:: 2.12 +.. seealso:: pagesVisible() +%End - /** Returns whether the page items are be visible in the composition. This setting - * effects both display of the page boundaries in composer views and - * whether they will be rendered in composition exports. - * @note added in QGIS 2.12 - * @see setPagesVisible() - */ bool pagesVisible() const; +%Docstring + Returns whether the page items are be visible in the composition. This setting + effects both display of the page boundaries in composer views and + whether they will be rendered in composition exports. +.. versionadded:: 2.12 +.. seealso:: setPagesVisible() + :rtype: bool +%End - /** Removes all snap lines*/ void clearSnapLines(); +%Docstring +Removes all snap lines +%End void setSnapGridResolution( const double r ); double snapGridResolution() const; +%Docstring + :rtype: float +%End void setSnapGridOffsetX( const double offset ); double snapGridOffsetX() const; +%Docstring + :rtype: float +%End void setSnapGridOffsetY( const double offset ); double snapGridOffsetY() const; +%Docstring + :rtype: float +%End void setGridPen( const QPen &p ); QPen gridPen() const; +%Docstring + :rtype: QPen +%End void setGridStyle( const GridStyle s ); GridStyle gridStyle() const; +%Docstring + :rtype: GridStyle +%End - /** Sets the snap tolerance to use when automatically snapping items during movement and resizing to guides - * and the edges and centers of other items. - * @param snapTolerance snap tolerance in pixels - * @see alignmentSnapTolerance - * @note Added in QGIS 2.5 - */ void setSnapTolerance( const int snapTolerance ); +%Docstring + Sets the snap tolerance to use when automatically snapping items during movement and resizing to guides + and the edges and centers of other items. + \param snapTolerance snap tolerance in pixels +.. seealso:: alignmentSnapTolerance +.. versionadded:: 2.5 +%End - /** Returns the snap tolerance to use when automatically snapping items during movement and resizing to guides - * and the edges and centers of other items. - * @returns snap tolerance in pixels - * @see setAlignmentSnapTolerance - * @note Added in QGIS 2.5 - */ int snapTolerance() const; +%Docstring + Returns the snap tolerance to use when automatically snapping items during movement and resizing to guides + and the edges and centers of other items. + :return: snap tolerance in pixels +.. seealso:: setAlignmentSnapTolerance +.. versionadded:: 2.5 + :rtype: int +%End - /** Sets whether selection bounding boxes should be shown in the composition - * @param boundsVisible set to true to show selection bounding box - * @see boundingBoxesVisible - * @note added in QGIS 2.7 - */ void setBoundingBoxesVisible( const bool boundsVisible ); +%Docstring + Sets whether selection bounding boxes should be shown in the composition + \param boundsVisible set to true to show selection bounding box +.. seealso:: boundingBoxesVisible +.. versionadded:: 2.7 +%End - /** Returns whether selection bounding boxes should be shown in the composition - * @returns true if selection bounding boxes should be shown - * @see setBoundingBoxesVisible - * @note added in QGIS 2.7 - */ bool boundingBoxesVisible() const; +%Docstring + Returns whether selection bounding boxes should be shown in the composition + :return: true if selection bounding boxes should be shown +.. seealso:: setBoundingBoxesVisible +.. versionadded:: 2.7 + :rtype: bool +%End - /** Returns pointer to undo/redo command storage*/ QUndoStack *undoStack(); +%Docstring +Returns pointer to undo/redo command storage + :rtype: QUndoStack +%End - /** Returns the topmost composer item at a specified position. Ignores paper items. - * @param position point to search for item at - * @param ignoreLocked set to true to ignore locked items - * @returns composer item at position - */ QgsComposerItem *composerItemAt( QPointF position, const bool ignoreLocked = false ) const; +%Docstring + Returns the topmost composer item at a specified position. Ignores paper items. + \param position point to search for item at + \param ignoreLocked set to true to ignore locked items + :return: composer item at position + :rtype: QgsComposerItem +%End - /** Returns the topmost composer item at a specified position which is below a specified item. Ignores paper items. - * @param position point to search for item at - * @param belowItem item to search below - * @param ignoreLocked set to true to ignore locked items - * @returns composer item at position which is below specified item - */ QgsComposerItem *composerItemAt( QPointF position, const QgsComposerItem *belowItem, const bool ignoreLocked = false ) const; +%Docstring + Returns the topmost composer item at a specified position which is below a specified item. Ignores paper items. + \param position point to search for item at + \param belowItem item to search below + \param ignoreLocked set to true to ignore locked items + :return: composer item at position which is below specified item + :rtype: QgsComposerItem +%End - /** Returns the page number (0-based) given a coordinate */ int pageNumberAt( QPointF position ) const; +%Docstring +Returns the page number (0-based) given a coordinate + :rtype: int +%End - /** Returns on which page number (0-based) is displayed an item */ - int itemPageNumber( const QgsComposerItem* ) const; + int itemPageNumber( const QgsComposerItem * ) const; +%Docstring +Returns on which page number (0-based) is displayed an item + :rtype: int +%End - /** Returns list of selected composer items - * @param includeLockedItems set to true to include locked items in list - * @returns list of selected items - */ - QList selectedComposerItems( const bool includeLockedItems = true ); + QList selectedComposerItems( const bool includeLockedItems = true ); +%Docstring + Returns list of selected composer items + \param includeLockedItems set to true to include locked items in list + :return: list of selected items + :rtype: list of QgsComposerItem +%End - /** Returns pointers to all composer maps in the scene - * @note available in python bindings only with PyQt >= 4.8.4 - */ - QList composerMapItems() const; + QList composerMapItems() const; +%Docstring + Returns pointers to all composer maps in the scene +.. note:: + + available in Python bindings only with PyQt >= 4.8.4 + :rtype: list of const QgsComposerMap +%End - /** Return composer items of a specific type - * @param itemList list of item type to store matching items in - * @note not available in python bindings - */ - // template void composerItems( QList &itemList ); - /** Return composer items of a specific type on a specified page - * @param itemList list of item type to store matching items in - * @param pageNumber page number (0 based) - * @note not available in python bindings - * @note added in QGIS 2.5 - */ - //template void composerItemsOnPage( QList &itemList, const int pageNumber ); - /** Returns the composer map with specified id - * @return QgsComposerMap or 0 pointer if the composer map item does not exist - */ const QgsComposerMap *getComposerMapById( const int id ) const; +%Docstring + Returns the composer map with specified id + :return: QgsComposerMap or 0 pointer if the composer map item does not exist + :rtype: QgsComposerMap +%End - /** Returns a composer item given its text identifier. - * Ids are not necessarely unique, but this function returns only one element. - * @param id - A QString representing the identifier of the item to retrieve. - * @return QgsComposerItem pointer or 0 pointer if no such item exists. - */ const QgsComposerItem *getComposerItemById( const QString &id ) const; +%Docstring + Returns a composer item given its text identifier. + Ids are not necessarely unique, but this function returns only one element. + \param id - A QString representing the identifier of the item to retrieve. + :return: QgsComposerItem pointer or 0 pointer if no such item exists. + :rtype: QgsComposerItem +%End - /** Returns a composer item given its unique identifier. - * @param uuid A QString representing the UUID of the item to - */ const QgsComposerItem *getComposerItemByUuid( const QString &uuid ) const; +%Docstring + Returns a composer item given its unique identifier. + \param uuid A QString representing the UUID of the item to + :rtype: QgsComposerItem +%End int printResolution() const; +%Docstring + :rtype: int +%End void setPrintResolution( const int dpi ); bool printAsRaster() const; +%Docstring + :rtype: bool +%End void setPrintAsRaster( const bool enabled ); - /** Returns true if the composition will generate corresponding world files when pages - * are exported. - * @see setGenerateWorldFile() - * @see worldFileMap() - */ bool generateWorldFile() const; +%Docstring + Returns true if the composition will generate corresponding world files when pages + are exported. +.. seealso:: setGenerateWorldFile() +.. seealso:: referenceMap() + :rtype: bool +%End - /** Sets whether the composition will generate corresponding world files when pages - * are exported. - * @param enabled set to true to generate world files - * @see generateWorldFile() - * @see setWorldFileMap() - */ void setGenerateWorldFile( bool enabled ); +%Docstring + Sets whether the composition will generate corresponding world files when pages + are exported. + \param enabled set to true to generate world files +.. seealso:: generateWorldFile() +.. seealso:: setReferenceMap() +%End QgsComposerMap *referenceMap() const; +%Docstring + Returns the map item which will be used to generate corresponding world files when the + composition is exported. If no map was explicitly set via setReferenceMap(), the largest + map in the composition will be returned (or None if there are no maps in the composition). +.. seealso:: setReferenceMap() +.. seealso:: generateWorldFile() + :rtype: QgsComposerMap +%End void setReferenceMap( QgsComposerMap *map ); +%Docstring + Sets the map item which will be used to generate corresponding world files when the + composition is exported. + \param map composer map item +.. seealso:: referenceMap() +.. seealso:: setGenerateWorldFile() +%End - /** Returns true if a composition should use advanced effects such as blend modes */ bool useAdvancedEffects() const; - /** Used to enable or disable advanced effects such as blend modes in a composition */ +%Docstring +Returns true if a composition should use advanced effects such as blend modes + :rtype: bool +%End void setUseAdvancedEffects( const bool effectsEnabled ); +%Docstring +Used to enable or disable advanced effects such as blend modes in a composition +%End QgsComposition::PlotStyle plotStyle() const; +%Docstring + :rtype: QgsComposition.PlotStyle +%End void setPlotStyle( const QgsComposition::PlotStyle style ); - /** Writes settings to xml (paper dimension)*/ bool writeXml( QDomElement &composerElem, QDomDocument &doc ); +%Docstring +Writes settings to xml (paper dimension) + :rtype: bool +%End - /** Reads settings from xml file*/ bool readXml( const QDomElement &compositionElem, const QDomDocument &doc ); +%Docstring +Reads settings from xml file + :rtype: bool +%End - bool loadFromTemplate( const QDomDocument& doc, QMap* substitutionMap = 0, + bool loadFromTemplate( const QDomDocument &doc, QMap *substitutionMap = 0, bool addUndoCommands = false, const bool clearComposition = true ); - void addItemsFromXml( const QDomElement &elem, const QDomDocument &doc, - bool addUndoCommands = false, QPointF *pos = 0, bool pasteInPlace = false ); +%Docstring + Load a template document + \param doc template document + \param substitutionMap map with text to replace. Text needs to be enclosed by brackets (e.g. '[text]' ) + \param addUndoCommands whether or not to add undo commands + \param clearComposition set to true to clear the existing composition and read all composition and + atlas properties from the template. Set to false to only add new items from the template, without + overwriting the existing items or composition settings. + :rtype: bool +%End void addItemToZList( QgsComposerItem *item ); - +%Docstring +Adds item to z list. Usually called from constructor of QgsComposerItem +%End void removeItemFromZList( QgsComposerItem *item ); +%Docstring +Removes item from z list. Usually called from destructor of QgsComposerItem +%End - - //functions to move selected items in hierarchy void raiseSelectedItems(); - //returns true if successful bool raiseItem( QgsComposerItem *item ); +%Docstring + :rtype: bool +%End void lowerSelectedItems(); - //returns true if successful bool lowerItem( QgsComposerItem *item ); +%Docstring + :rtype: bool +%End void moveSelectedItemsToTop(); - //returns true if successful bool moveItemToTop( QgsComposerItem *item ); +%Docstring + :rtype: bool +%End void moveSelectedItemsToBottom(); - //returns true if successful bool moveItemToBottom( QgsComposerItem *item ); +%Docstring + :rtype: bool +%End - //functions to find items by their position in the z list void selectNextByZOrder( const ZValueDirection direction ); QgsComposerItem *getComposerItemBelow( QgsComposerItem *item ) const; +%Docstring + :rtype: QgsComposerItem +%End QgsComposerItem *getComposerItemAbove( QgsComposerItem *item ) const; +%Docstring + :rtype: QgsComposerItem +%End - //functions to align selected items void alignSelectedItemsLeft(); void alignSelectedItemsHCenter(); void alignSelectedItemsRight(); @@ -292,368 +588,518 @@ class QgsComposition : QGraphicsScene, QgsExpressionContextGenerator void alignSelectedItemsVCenter(); void alignSelectedItemsBottom(); - //functions to lock and unlock items - /** Lock the selected items*/ void lockSelectedItems(); - /** Unlock all items*/ +%Docstring +Lock the selected items +%End void unlockAllItems(); +%Docstring +Unlock all items +%End - /** Creates a new group from a list of composer items and adds it to the composition. - * @param items items to include in group - * @returns QgsComposerItemGroup of grouped items, if grouping was possible - * @note added in QGIS 2.6 - */ - QgsComposerItemGroup *groupItems( QList items ); + QgsComposerItemGroup *groupItems( QList items ); +%Docstring + Creates a new group from a list of composer items and adds it to the composition. + \param items items to include in group + :return: QgsComposerItemGroup of grouped items, if grouping was possible +.. versionadded:: 2.6 + :rtype: QgsComposerItemGroup +%End - /** Ungroups items by removing them from an item group and removing the group from the - * composition. - * @param group item group to ungroup - * @returns list of items removed from the group, or an empty list if ungrouping - * was not successful - * @note added in QGIS 2.6 - */ - QList ungroupItems( QgsComposerItemGroup *group ); + QList ungroupItems( QgsComposerItemGroup *group ); +%Docstring + Ungroups items by removing them from an item group and removing the group from the + composition. + \param group item group to ungroup + :return: list of items removed from the group, or an empty list if ungrouping + was not successful +.. versionadded:: 2.6 + :rtype: list of QgsComposerItem +%End - /** Rebuilds the z order list by adding any item which are present in the composition - * but missing from the z order list. - */ void refreshZList(); +%Docstring + Rebuilds the z order list by adding any item which are present in the composition + but missing from the z order list. +%End - /** Snaps a scene coordinate point to grid*/ QPointF snapPointToGrid( QPointF scenePoint ) const; +%Docstring +Snaps a scene coordinate point to grid + :rtype: QPointF +%End - /** Returns pointer to snap lines collection*/ - QList< QGraphicsLineItem* > *snapLines(); + QList< QGraphicsLineItem * > *snapLines(); +%Docstring +Returns pointer to snap lines collection + :rtype: list of QGraphicsLineItem +%End - /** Returns pointer to selection handles - * @note not available in python bindings - */ - // QgsComposerMouseHandles *selectionHandles(); - /** Add a custom snap line (can be horizontal or vertical)*/ QGraphicsLineItem *addSnapLine(); - /** Remove custom snap line (and delete the object)*/ +%Docstring +Add a custom snap line (can be horizontal or vertical) + :rtype: QGraphicsLineItem +%End void removeSnapLine( QGraphicsLineItem *line ); - /** Get nearest snap line - * @note not available in python bindings - */ - // QGraphicsLineItem *nearestSnapLine( const bool horizontal, const double x, const double y, const double tolerance, QList< QPair< QgsComposerItem*, QgsComposerItem::ItemPositionMode > > &snappedItems ); +%Docstring +Remove custom snap line (and delete the object) +%End + - /** Allocates new item command and saves initial state in it - * @param item target item - * @param commandText descriptive command text - * @param c context for merge commands (unknown for non-mergeable commands) - */ void beginCommand( QgsComposerItem *item, const QString &commandText, const QgsComposerMergeCommand::Context c = QgsComposerMergeCommand::Unknown ); +%Docstring + Allocates new item command and saves initial state in it + \param item target item + \param commandText descriptive command text + \param c context for merge commands (unknown for non-mergeable commands) +%End - /** Saves end state of item and pushes command to the undo history*/ void endCommand(); - /** Deletes current command*/ +%Docstring +Saves end state of item and pushes command to the undo history +%End void cancelCommand(); +%Docstring +Deletes current command +%End void beginMultiFrameCommand( QgsComposerMultiFrame *multiFrame, const QString &text, const QgsComposerMultiFrameMergeCommand::Context c = QgsComposerMultiFrameMergeCommand::Unknown ); void endMultiFrameCommand(); - /** Deletes current multi frame command*/ void cancelMultiFrameCommand(); +%Docstring +Deletes current multi frame command +%End - /** Adds multiframe. The object is owned by QgsComposition until removeMultiFrame is called*/ void addMultiFrame( QgsComposerMultiFrame *multiFrame ); - /** Removes multi frame (but does not delete it)*/ +%Docstring +Adds multiframe. The object is owned by QgsComposition until removeMultiFrame is called +%End void removeMultiFrame( QgsComposerMultiFrame *multiFrame ); - /** Adds an arrow item to the graphics scene and advises composer to create a widget for it (through signal) - @note not available in python bindings*/ - void addComposerArrow( QgsComposerArrow *arrow ); - /** Adds label to the graphics scene and advises composer to create a widget for it (through signal)*/ +%Docstring +Removes multi frame (but does not delete it) +%End + void addComposerLabel( QgsComposerLabel *label ); - /** Adds map to the graphics scene and advises composer to create a widget for it (through signal)*/ +%Docstring +Adds label to the graphics scene and advises composer to create a widget for it (through signal) +%End void addComposerMap( QgsComposerMap *map ); - /** Adds scale bar to the graphics scene and advises composer to create a widget for it (through signal)*/ +%Docstring +Adds map to the graphics scene and advises composer to create a widget for it (through signal) +%End void addComposerScaleBar( QgsComposerScaleBar *scaleBar ); - /** Adds legend to the graphics scene and advises composer to create a widget for it (through signal)*/ +%Docstring +Adds scale bar to the graphics scene and advises composer to create a widget for it (through signal) +%End void addComposerLegend( QgsComposerLegend *legend ); - /** Adds picture to the graphics scene and advises composer to create a widget for it (through signal)*/ +%Docstring +Adds legend to the graphics scene and advises composer to create a widget for it (through signal) +%End void addComposerPicture( QgsComposerPicture *picture ); - /** Adds a composer shape to the graphics scene and advises composer to create a widget for it (through signal)*/ +%Docstring +Adds picture to the graphics scene and advises composer to create a widget for it (through signal) +%End void addComposerShape( QgsComposerShape *shape ); - /** Adds a composer polygon and advises composer to create a widget for it (through signal)*/ +%Docstring +Adds a composer shape to the graphics scene and advises composer to create a widget for it (through signal) +%End void addComposerPolygon( QgsComposerPolygon *polygon ); - /** Adds a composer polyline and advises composer to create a widget for it (through signal)*/ +%Docstring +Adds a composer polygon and advises composer to create a widget for it (through signal) +%End void addComposerPolyline( QgsComposerPolyline *polyline ); - /** Adds composer html frame and advises composer to create a widget for it (through signal)*/ - void addComposerHtmlFrame( QgsComposerHtml *html /Transfer/, QgsComposerFrame *frame /Transfer/); - /** Adds composer tablev2 frame and advises composer to create a widget for it (through signal)*/ - void addComposerTableFrame( QgsComposerAttributeTableV2 *table /Transfer/, QgsComposerFrame *frame /Transfer/); +%Docstring +Adds a composer polyline and advises composer to create a widget for it (through signal) +%End + void addComposerHtmlFrame( QgsComposerHtml *html, QgsComposerFrame *frame ); +%Docstring +Adds composer html frame and advises composer to create a widget for it (through signal) +%End + void addComposerTableFrame( QgsComposerAttributeTableV2 *table, QgsComposerFrame *frame ); +%Docstring +Adds composer tablev2 frame and advises composer to create a widget for it (through signal) +%End - /** Remove item from the graphics scene. Additionally to QGraphicsScene::removeItem, this function considers undo/redo command*/ void removeComposerItem( QgsComposerItem *item, const bool createCommand = true, const bool removeGroupItems = true ); +%Docstring +Remove item from the graphics scene. Additionally to QGraphicsScene.removeItem, this function considers undo/redo command +%End - /** Convenience function to create a QgsAddRemoveItemCommand, connect its signals and push it to the undo stack*/ void pushAddRemoveCommand( QgsComposerItem *item, const QString &text, const QgsAddRemoveItemCommand::State state = QgsAddRemoveItemCommand::Added ); +%Docstring +Convenience function to create a QgsAddRemoveItemCommand, connect its signals and push it to the undo stack +%End - /** If true, prevents any mouse cursor changes by the composition or by any composer items - * Used by QgsComposer and QgsComposerView to prevent unwanted cursor changes - */ void setPreventCursorChange( const bool preventChange ); +%Docstring + If true, prevents any mouse cursor changes by the composition or by any composer items + Used by QgsComposer and QgsComposerView to prevent unwanted cursor changes +%End bool preventCursorChange() const; +%Docstring + :rtype: bool +%End - //printing - - /** Prepare the printer for printing */ void beginPrint( QPrinter &printer, const bool evaluateDDPageSize = false ); - /** Prepare the printer for printing in a PDF */ +%Docstring +Prepare the printer for printing +%End void beginPrintAsPDF( QPrinter &printer, const QString &file ); +%Docstring +Prepare the printer for printing in a PDF +%End - /** Print on a preconfigured printer - * @param printer QPrinter destination - * @param painter QPainter source - * @param startNewPage set to true to begin the print on a new page - */ void doPrint( QPrinter &printer, QPainter &painter, bool startNewPage = false ); +%Docstring + Print on a preconfigured printer + \param printer QPrinter destination + \param painter QPainter source + \param startNewPage set to true to begin the print on a new page +%End - /** Convenience function that prepares the printer and prints - * @returns true if print was successful - */ bool print( QPrinter &printer, const bool evaluateDDPageSize = false ); +%Docstring + Convenience function that prepares the printer and prints + :return: true if print was successful + :rtype: bool +%End - /** Convenience function that prepares the printer for printing in PDF and prints - * @returns true if export was successful - */ bool exportAsPDF( const QString &file ); +%Docstring + Convenience function that prepares the printer for printing in PDF and prints + :return: true if export was successful + :rtype: bool +%End - /** Renders a composer page to an image. - * @param page page number, 0 based such that the first page is page 0 - * @param imageSize optional target image size, in pixels. It is the caller's responsibility - * to ensure that the ratio of the target image size matches the ratio of the composition - * page size. - * @param dpi optional dpi override, or 0 to use default composition print resolution. This - * parameter has no effect if imageSize is specified. - * @returns rendered image, or null image if image does not fit into available memory - * @see renderRectAsRaster() - * @see renderPage() - */ QImage printPageAsRaster( int page, QSize imageSize = QSize(), int dpi = 0 ); +%Docstring + Renders a composer page to an image. + \param page page number, 0 based such that the first page is page 0 + \param imageSize optional target image size, in pixels. It is the caller's responsibility + to ensure that the ratio of the target image size matches the ratio of the composition + page size. + \param dpi optional dpi override, or 0 to use default composition print resolution. This + parameter has no effect if imageSize is specified. + :return: rendered image, or null image if image does not fit into available memory +.. seealso:: renderRectAsRaster() +.. seealso:: renderPage() + :rtype: QImage +%End - /** Renders a portion of the composition to an image. This method can be used to render - * sections of pages rather than full pages. - * @param rect region of composition to render - * @param imageSize optional target image size, in pixels. It is the caller's responsibility - * to ensure that the ratio of the target image size matches the ratio of the specified - * region of the composition. - * @param dpi optional dpi override, or 0 to use default composition print resolution. This - * parameter has no effect if imageSize is specified. - * @returns rendered image, or null image if image does not fit into available memory - * @note added in QGIS 2.12 - * @see printPageAsRaster() - * @see renderRect() - */ QImage renderRectAsRaster( const QRectF &rect, QSize imageSize = QSize(), int dpi = 0 ); +%Docstring + Renders a portion of the composition to an image. This method can be used to render + sections of pages rather than full pages. + \param rect region of composition to render + \param imageSize optional target image size, in pixels. It is the caller's responsibility + to ensure that the ratio of the target image size matches the ratio of the specified + region of the composition. + \param dpi optional dpi override, or 0 to use default composition print resolution. This + parameter has no effect if imageSize is specified. + :return: rendered image, or null image if image does not fit into available memory +.. versionadded:: 2.12 +.. seealso:: printPageAsRaster() +.. seealso:: renderRect() + :rtype: QImage +%End - /** Renders a full page to a paint device. - * @param p destination painter - * @param page page number, 0 based such that the first page is page 0 - * @see renderRect() - * @see printPageAsRaster() - */ void renderPage( QPainter *p, int page ); +%Docstring + Renders a full page to a paint device. + \param p destination painter + \param page page number, 0 based such that the first page is page 0 +.. seealso:: renderRect() +.. seealso:: printPageAsRaster() +%End - /** Renders a portion of the composition to a paint device. This method can be used - * to render sections of pages rather than full pages. - * @param p destination painter - * @param rect region of composition to render - * @note added in QGIS 2.12 - * @see renderPage() - * @see renderRectAsRaster() - */ void renderRect( QPainter *p, const QRectF &rect ); +%Docstring + Renders a portion of the composition to a paint device. This method can be used + to render sections of pages rather than full pages. + \param p destination painter + \param rect region of composition to render +.. versionadded:: 2.12 +.. seealso:: renderPage() +.. seealso:: renderRectAsRaster() +%End - /** Georeferences a file (image of PDF) exported from the composition. - * @param file filename of exported file - * @param referenceMap map item to use for georeferencing, or leave as nullptr to use the - * currently defined worldFileMap(). - * @param exportRegion set to a valid rectangle to indicate that only part of the composition was - * exported - * @param dpi set to DPI of exported file, or leave as -1 to use composition's DPI. - * @note added in QGIS 2.16 - */ - void georeferenceOutput( const QString& file, QgsComposerMap* referenceMap = 0, + void georeferenceOutput( const QString &file, QgsComposerMap *referenceMap = 0, const QRectF &exportRegion = QRectF(), double dpi = -1 ) const; +%Docstring + Georeferences a file (image of PDF) exported from the composition. + \param file filename of exported file + \param referenceMap map item to use for georeferencing, or leave as None to use the + currently defined referenceMap(). + \param exportRegion set to a valid rectangle to indicate that only part of the composition was + exported + \param dpi set to DPI of exported file, or leave as -1 to use composition's DPI. +.. versionadded:: 2.16 +%End - /** Compute world file parameters. Assumes the whole page containing the associated map item - * will be exported. - */ void computeWorldFileParameters( double &a, double &b, double &c, double &d, double &e, double &f ) const; +%Docstring + Compute world file parameters. Assumes the whole page containing the associated map item + will be exported. +%End - /** Computes the world file parameters for a specified region of the composition. - * @param exportRegion region of the composition which will be associated with world file - * @param a - * @param b - * @param c - * @param d - * @param e - * @param f - * @note added in QGIS 2.12 - */ void computeWorldFileParameters( const QRectF &exportRegion, double &a, double &b, double &c, double &d, double &e, double &f ) const; +%Docstring + Computes the world file parameters for a specified region of the composition. + \param exportRegion region of the composition which will be associated with world file + \param a + \param b + \param c + \param d + \param e + \param f +.. versionadded:: 2.12 +%End QgsAtlasComposition &atlasComposition(); +%Docstring + :rtype: QgsAtlasComposition +%End - /** Returns the current atlas mode of the composition - * @returns current atlas mode - * @see setAtlasMode - */ QgsComposition::AtlasMode atlasMode() const; +%Docstring + Returns the current atlas mode of the composition + :return: current atlas mode +.. seealso:: setAtlasMode + :rtype: QgsComposition.AtlasMode +%End - /** Sets the current atlas mode of the composition. - * @param mode atlas mode to switch to - * @returns false if the mode could not be changed. - * @see atlasMode - */ bool setAtlasMode( const QgsComposition::AtlasMode mode ); +%Docstring + Sets the current atlas mode of the composition. + \param mode atlas mode to switch to + :return: false if the mode could not be changed. +.. seealso:: atlasMode + :rtype: bool +%End - /** Return pages in the correct order - * @note composerItems(QList< QgsPaperItem* > &) may not return pages in the correct order - * @note added in version 2.4 - */ - QList< QgsPaperItem* > pages(); + QList< QgsPaperItem * > pages(); +%Docstring + Return pages in the correct order +.. note:: + + composerItems(QList< QgsPaperItem* > &) may not return pages in the correct order +.. versionadded:: 2.4 + :rtype: list of QgsPaperItem +%End - /** Returns the items model attached to the composition - * @returns QgsComposerModel for composition - * @note this method was added in version 2.5 - */ QgsComposerModel *itemsModel(); +%Docstring + Returns the items model attached to the composition + :return: QgsComposerModel for composition +.. versionadded:: 2.5 + :rtype: QgsComposerModel +%End - /** Set a custom property for the composition. - * @param key property key. If a property with the same key already exists it will be overwritten. - * @param value property value - * @see customProperty() - * @see removeCustomProperty() - * @see customProperties() - * @note added in QGIS 2.12 - */ void setCustomProperty( const QString &key, const QVariant &value ); +%Docstring + Set a custom property for the composition. + \param key property key. If a property with the same key already exists it will be overwritten. + \param value property value +.. seealso:: customProperty() +.. seealso:: removeCustomProperty() +.. seealso:: customProperties() +.. versionadded:: 2.12 +%End - /** Read a custom property from the composition. - * @param key property key - * @param defaultValue default value to return if property with matching key does not exist - * @returns value of matching property - * @see setCustomProperty() - * @see removeCustomProperty() - * @see customProperties() - * @note added in QGIS 2.12 - */ QVariant customProperty( const QString &key, const QVariant &defaultValue = QVariant() ) const; +%Docstring + Read a custom property from the composition. + \param key property key + \param defaultValue default value to return if property with matching key does not exist + :return: value of matching property +.. seealso:: setCustomProperty() +.. seealso:: removeCustomProperty() +.. seealso:: customProperties() +.. versionadded:: 2.12 + :rtype: QVariant +%End - /** Remove a custom property from the composition. - * @param key property key - * @see setCustomProperty() - * @see customProperty() - * @see customProperties() - * @note added in QGIS 2.12 - */ void removeCustomProperty( const QString &key ); +%Docstring + Remove a custom property from the composition. + \param key property key +.. seealso:: setCustomProperty() +.. seealso:: customProperty() +.. seealso:: customProperties() +.. versionadded:: 2.12 +%End - /** Return list of keys stored in custom properties for composition. - * @see setCustomProperty() - * @see customProperty() - * @see removeCustomProperty() - * @note added in QGIS 2.12 - */ QStringList customProperties() const; +%Docstring + Return list of keys stored in custom properties for composition. +.. seealso:: setCustomProperty() +.. seealso:: customProperty() +.. seealso:: removeCustomProperty() +.. versionadded:: 2.12 + :rtype: list of str +%End - /** Returns the bounding box of the items contained on a specified page. - * @param pageNumber page number, where 0 is the first page - * @param visibleOnly set to true to only include visible items - * @note added in QGIS 2.12 - */ QRectF pageItemBounds( int pageNumber, bool visibleOnly = false ) const; +%Docstring + Returns the bounding box of the items contained on a specified page. + \param pageNumber page number, where 0 is the first page + \param visibleOnly set to true to only include visible items +.. versionadded:: 2.12 + :rtype: QRectF +%End - /** Calculates the bounds of all non-gui items in the composition. Ignores snap lines and mouse handles. - * @param ignorePages set to true to ignore page items - * @param margin optional marginal (in percent, e.g., 0.05 = 5% ) to add around items - */ QRectF compositionBounds( bool ignorePages = false, double margin = 0.0 ) const; +%Docstring + Calculates the bounds of all non-gui items in the composition. Ignores snap lines and mouse handles. + \param ignorePages set to true to ignore page items + \param margin optional marginal (in percent, e.g., 0.05 = 5% ) to add around items + :rtype: QRectF +%End public slots: - /** Casts object to the proper subclass type and calls corresponding itemAdded signal*/ void sendItemAddedSignal( QgsComposerItem *item ); +%Docstring +Casts object to the proper subclass type and calls corresponding itemAdded signal +%End - /** Updates the scene bounds of the composition - @note added in version 2.2*/ void updateBounds(); +%Docstring + Updates the scene bounds of the composition +.. versionadded:: 2.2 +%End - /** Forces items in the composition to refresh. For instance, this causes maps to redraw - * and rebuild cached images, html items to reload their source url, and attribute tables - * to refresh their contents. Calling this also triggers a recalculation of all data defined - * attributes within the composition. - * @note added in version 2.3*/ void refreshItems(); +%Docstring + Forces items in the composition to refresh. For instance, this causes maps to redraw + and rebuild cached images, html items to reload their source url, and attribute tables + to refresh their contents. Calling this also triggers a recalculation of all data defined + attributes within the composition. +.. versionadded:: 2.3 +%End - /** Clears any selected items and sets an item as the current selection. - * @param item item to set as selected - * @note added in version 2.3*/ void setSelectedItem( QgsComposerItem *item ); +%Docstring + Clears any selected items and sets an item as the current selection. + \param item item to set as selected +.. versionadded:: 2.3 +%End - /** Clears any selected items in the composition. Call this method rather than - * QGraphicsScene::clearSelection, as the latter does not correctly emit signals to allow - * the composition's model to update. - * @note added in version 2.5*/ void setAllDeselected(); +%Docstring + Clears any selected items in the composition. Call this method rather than + QGraphicsScene.clearSelection, as the latter does not correctly emit signals to allow + the composition's model to update. +.. versionadded:: 2.5 +%End - /** Refreshes a data defined property for the composition by reevaluating the property's value - * and redrawing the composition with this new value. - * @param property data defined property to refresh. If property is set to - * QgsComposerItem::AllProperties then all data defined properties for the composition will be - * refreshed. - * @param context expression context for evaluating data defined expressions - * @note this method was added in version 2.5 - */ void refreshDataDefinedProperty( const QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties, const QgsExpressionContext *context = 0 ); +%Docstring + Refreshes a data defined property for the composition by reevaluating the property's value + and redrawing the composition with this new value. + \param property data defined property to refresh. If property is set to + QgsComposerItem.AllProperties then all data defined properties for the composition will be + refreshed. + \param context expression context for evaluating data defined expressions +.. versionadded:: 2.5 +%End - /** Creates an expression context relating to the compositions's current state. The context includes - * scopes for global, project, composition and atlas properties. - * @note added in QGIS 2.12 - */ - QgsExpressionContext createExpressionContext() const; + virtual QgsExpressionContext createExpressionContext() const; + +%Docstring + Creates an expression context relating to the compositions's current state. The context includes + scopes for global, project, composition and atlas properties. +.. versionadded:: 2.12 + :rtype: QgsExpressionContext +%End - /** Returns a reference to the composition's property collection, used for data defined overrides. - * @note added in QGIS 3.0 - * @see setDataDefinedProperties() - */ QgsPropertyCollection &dataDefinedProperties(); +%Docstring + Returns a reference to the composition's property collection, used for data defined overrides. +.. versionadded:: 3.0 +.. seealso:: setDataDefinedProperties() + :rtype: QgsPropertyCollection +%End - /** Returns a reference to the composition's property collection, used for data defined overrides. - * @note added in QGIS 3.0 - * @see setDataDefinedProperties() - */ - //const QgsPropertyCollection &dataDefinedProperties() const; - /** Sets the composition's property collection, used for data defined overrides. - * @param collection property collection. Existing properties will be replaced. - * @note added in QGIS 3.0 - * @see dataDefinedProperties() - */ void setDataDefinedProperties( const QgsPropertyCollection &collection ); +%Docstring + Sets the composition's property collection, used for data defined overrides. + \param collection property collection. Existing properties will be replaced. +.. versionadded:: 3.0 +.. seealso:: dataDefinedProperties() +%End protected: void init(); signals: + void nameChanged( const QString &name ); +%Docstring + Emitted when the composition's name is changed. +.. versionadded:: 3.0 +.. seealso:: setName() +%End + void paperSizeChanged(); void nPagesChanged(); + void printResolutionChanged(); +%Docstring +Is emitted when the compositions print resolution changes +%End + void selectedItemChanged( QgsComposerItem *selected ); +%Docstring +Is emitted when selected item changed. If 0, no item is selected +%End + void itemAdded( QgsComposerItem *item ); +%Docstring + Is emitted when a new composer item has been added to the composition. +.. versionadded:: 3.0 +%End + void composerItemGroupAdded( QgsComposerItemGroup *group ); +%Docstring +Is emitted when a new item group has been added to the view +%End + void itemRemoved( QgsComposerItem * ); +%Docstring +Is emitted when a composer item has been removed from the scene +%End + void refreshItemsTriggered(); +%Docstring +Is emitted when item in the composition must be refreshed +%End - /** Is emitted when the composition has an updated status bar message for the composer window*/ - void statusMsgChanged( QString message ); + void statusMsgChanged( const QString &message ); +%Docstring +Is emitted when the composition has an updated status bar message for the composer window +%End - /** Emitted whenever the expression variables stored in the composition have been changed. - * @note added in QGIS 3.0 - */ void variablesChanged(); +%Docstring + Emitted whenever the expression variables stored in the composition have been changed. +.. versionadded:: 3.0 +%End + }; + + + + + + + +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/composer/qgscomposition.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ diff --git a/python/core/composer/qgslayoutmanager.sip b/python/core/composer/qgslayoutmanager.sip index 518b43d1942..120e7b80530 100644 --- a/python/core/composer/qgslayoutmanager.sip +++ b/python/core/composer/qgslayoutmanager.sip @@ -1,34 +1,154 @@ +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/composer/qgslayoutmanager.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ + + + + class QgsLayoutManager : QObject { +%Docstring +.. versionadded:: 3.0 + + Manages storage of a set of compositions. + + QgsLayoutManager handles the storage, serializing and deserializing + of QgsCompositions. Usually this class is not constructed directly, but + rather accessed through a QgsProject via QgsProject.layoutManager(). + + QgsLayoutManager retains ownership of all the compositions contained + in the manager. +%End + %TypeHeaderCode -#include +#include "qgslayoutmanager.h" %End public: explicit QgsLayoutManager( QgsProject *project /TransferThis/ = 0 ); +%Docstring + Constructor for QgsLayoutManager. The project will become the parent object for this + manager. +%End ~QgsLayoutManager(); + bool addComposition( QgsComposition *composition /Transfer/ ); +%Docstring + Adds a composition to the manager. Ownership of the composition is transferred to the manager. + Returns true if the addition was successful, or false if the composition could not be added (eg + as a result of a duplicate composition name). +.. seealso:: removeComposition() +.. seealso:: compositionAdded() + :rtype: bool +%End + bool removeComposition( QgsComposition *composition ); +%Docstring + Removes a composition from the manager. The composition is deleted. + Returns true if the removal was successful, or false if the removal failed (eg as a result + of removing a composition which is not contained in the manager). +.. seealso:: addComposition() +.. seealso:: compositionRemoved() +.. seealso:: compositionAboutToBeRemoved() +.. seealso:: clear() + :rtype: bool +%End void clear(); +%Docstring + Removes and deletes all compositions from the manager. +.. seealso:: removeComposition() +%End + QList< QgsComposition * > compositions() const; +%Docstring + Returns a list of all compositions contained in the manager. + :rtype: list of QgsComposition +%End + QgsComposition *compositionByName( const QString &name ) const; +%Docstring + Returns the composition with a matching name, or None if no matching compositions + were found. + :rtype: QgsComposition +%End + bool readXml( const QDomElement &element, const QDomDocument &doc ); +%Docstring + Reads the manager's state from a DOM element, restoring all compositions + present in the XML document. +.. seealso:: writeXml() + :rtype: bool +%End + QDomElement writeXml( QDomDocument &doc ) const; +%Docstring + Returns a DOM element representing the state of the manager. +.. seealso:: readXml() + :rtype: QDomElement +%End + bool saveAsTemplate( const QString &name, QDomDocument &doc ) const; +%Docstring + Saves the composition with matching ``name`` in template format. + Returns true if save was successful. + :rtype: bool +%End + QgsComposition *duplicateComposition( const QString &name, const QString &newName ); +%Docstring + Duplicates an existing composition from the manager. The new + composition will automatically be stored in the manager. + Returns new composition if duplication was successful. + :rtype: QgsComposition +%End + QString generateUniqueTitle() const; +%Docstring + Generates a unique title for a new composition, which does not + clash with any already contained by the manager. + :rtype: str +%End signals: void compositionAboutToBeAdded( const QString &name ); - void compositionAdded( const QString &name ); - void compositionRemoved( const QString &name ); - void compositionAboutToBeRemoved( const QString &name ); - void compositionRenamed( QgsComposition *composition, const QString &newName ); +%Docstring +Emitted when a composition is about to be added to the manager +%End + void compositionAdded( const QString &name ); +%Docstring +Emitted when a composition has been added to the manager +%End + + void compositionRemoved( const QString &name ); +%Docstring +Emitted when a composition was removed from the manager +%End + + void compositionAboutToBeRemoved( const QString &name ); +%Docstring +Emitted when a composition is about to be removed from the manager +%End + + void compositionRenamed( QgsComposition *composition, const QString &newName ); +%Docstring +Emitted when a composition is renamed +%End }; +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/composer/qgslayoutmanager.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ diff --git a/python/core/composer/qgspaperitem.sip b/python/core/composer/qgspaperitem.sip index c15f6febae4..0444b412edd 100644 --- a/python/core/composer/qgspaperitem.sip +++ b/python/core/composer/qgspaperitem.sip @@ -1,52 +1,87 @@ -/** Item representing a grid. This is drawn separately to the underlying paper item since the grid needs to be - * drawn above all other composer items, while the paper item is drawn below all others.*/ -class QgsPaperGrid : QGraphicsRectItem +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/composer/qgspaperitem.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ + + + + +class QgsPaperGrid: QGraphicsRectItem { +%Docstring + Item representing a grid. This is drawn separately to the underlying paper item since the grid needs to be + drawn above all other composer items, while the paper item is drawn below all others.* +%End + %TypeHeaderCode -#include +#include "qgspaperitem.h" %End public: QgsPaperGrid( double x, double y, double width, double height, QgsComposition *composition ); - ~QgsPaperGrid(); - /** \brief Reimplementation of QCanvasItem::paint*/ - void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ); + virtual void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ); + +%Docstring + Reimplementation of QCanvasItem.paint +%End }; -/** Item representing the paper.*/ class QgsPaperItem : QgsComposerItem { +%Docstring + Item representing the paper.* +%End + %TypeHeaderCode -#include +#include "qgspaperitem.h" %End public: QgsPaperItem( QgsComposition *c /TransferThis/ ); QgsPaperItem( qreal x, qreal y, qreal width, qreal height, QgsComposition *composition /TransferThis/ ); ~QgsPaperItem(); - /** Return correct graphics item type. */ virtual int type() const; +%Docstring +Return correct graphics item type. + :rtype: int +%End - /** \brief Reimplementation of QCanvasItem::paint*/ - void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ); + virtual void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ); - /** Stores state in Dom element - * @param elem is Dom element corresponding to 'Composer' tag - * @param doc Dom document - */ - bool writeXml( QDomElement &elem, QDomDocument &doc ) const; +%Docstring + Reimplementation of QCanvasItem.paint +%End - /** Sets state from Dom document - * @param itemElem is Dom node corresponding to item tag - * @param doc is the Dom document - */ - bool readXml( const QDomElement &itemElem, const QDomDocument &doc ); + virtual bool writeXml( QDomElement &elem, QDomDocument &doc ) const; + +%Docstring + Stores state in Dom element + \param elem is Dom element corresponding to 'Composer' tag + \param doc Dom document + :rtype: bool +%End + + virtual bool readXml( const QDomElement &itemElem, const QDomDocument &doc ); + +%Docstring + Sets state from Dom document + \param itemElem is Dom node corresponding to item tag + \param doc is the Dom document + :rtype: bool +%End virtual void setSceneRect( const QRectF &rectangle ); - private: - QgsPaperItem(); - /** Set flags and z-value*/ - void initialize(); }; + +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/composer/qgspaperitem.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ diff --git a/scripts/sipify.pl b/scripts/sipify.pl index d9be45157a6..2ded5a5520e 100755 --- a/scripts/sipify.pl +++ b/scripts/sipify.pl @@ -448,6 +448,10 @@ while ($LINE_IDX < $LINE_COUNT){ next; } } + # skip friends + if ( $LINE =~ m/^\s*friend class \w+/ ){ + next; + } # Skip Q_OBJECT, Q_PROPERTY, Q_ENUM, Q_GADGET if ($LINE =~ m/^\s*Q_(OBJECT|ENUMS|PROPERTY|GADGET|DECLARE_METATYPE|DECLARE_TYPEINFO|DECL_DEPRECATED).*?$/){ next; diff --git a/src/core/composer/qgscomposition.h b/src/core/composer/qgscomposition.h index 274cef50218..00f4c7b4fe1 100644 --- a/src/core/composer/qgscomposition.h +++ b/src/core/composer/qgscomposition.h @@ -863,7 +863,7 @@ class CORE_EXPORT QgsComposition : public QGraphicsScene, public QgsExpressionCo * \since QGIS 3.0 * \see setDataDefinedProperties() */ - const QgsPropertyCollection &dataDefinedProperties() const { return mDataDefinedProperties; } + const QgsPropertyCollection &dataDefinedProperties() const { return mDataDefinedProperties; } SIP_SKIP /** Sets the composition's property collection, used for data defined overrides. * \param collection property collection. Existing properties will be replaced. @@ -1057,7 +1057,7 @@ class CORE_EXPORT QgsComposition : public QGraphicsScene, public QgsExpressionCo friend class TestQgsComposition; }; -template void QgsComposition::composerItems( QList &itemList ) +template void QgsComposition::composerItems( QList &itemList ) SIP_SKIP { itemList.clear(); QList graphicsItemList = items(); @@ -1072,7 +1072,7 @@ template void QgsComposition::composerItems( QList &itemList ) } } -template void QgsComposition::composerItemsOnPage( QList &itemList, const int pageNumber ) const +template void QgsComposition::composerItemsOnPage( QList &itemList, const int pageNumber ) const SIP_SKIP { itemList.clear(); QList graphicsItemList = items();