Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[composer] Refactor QgsComposerItem:
- New class QgsComposerObject, which both QgsComposerItem and QgsComposerMultiFrame
derive from. This class contains the framework for data defined composition properties.
- New class QgsComposerUtils, containing helpful static functions previously in QgsComposerItem
- Test suites for data defined settings in QgsComposerObject and functions in QgsComposerUtils
  • Loading branch information
nyalldawson committed Jul 14, 2014
1 parent 49bc38c commit 2041fc2
Show file tree
Hide file tree
Showing 35 changed files with 1,792 additions and 652 deletions.
141 changes: 35 additions & 106 deletions python/core/composer/qgscomposeritem.sip
@@ -1,7 +1,7 @@
/** \ingroup MapComposer
* A item that forms part of a map composition.
*/
class QgsComposerItem : QObject, QGraphicsRectItem
class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
{
%TypeHeaderCode
#include <qgscomposeritem.h>
Expand Down Expand Up @@ -133,46 +133,6 @@ class QgsComposerItem : QObject, QGraphicsRectItem
LowerRight
};

/** Data defined properties for different item types
*/
enum DataDefinedProperty
{
NoProperty = 0, /*< no property */
AllProperties, /*< all properties for item */
//composer page properties
PresetPaperSize, /*< preset paper size for composition */
PaperWidth, /*< paper width */
PaperHeight, /*< paper height */
NumPages, /*< number of pages in composition */
PaperOrientation, /*< paper orientation */
//general composer item properties
PageNumber, /*< page number for item placement */
PositionX, /*< x position on page */
PositionY, /*< y position on page */
ItemWidth, /*< width of item */
ItemHeight, /*< height of item */
ItemRotation, /*< rotation of item */
Transparency, /*< item transparency */
BlendMode, /*< item blend mode */
//composer map
MapRotation, /*< map rotation */
MapScale, /*< map scale */
MapXMin, /*< map extent x minimum */
MapYMin, /*< map extent y minimum */
MapXMax, /*< map extent x maximum */
MapYMax /*< map extent y maximum */
};

/** Specifies whether the value returned by a function should be the original, user
* set value, or the current evaluated value for the property. This may differ if
* a property has a data defined expression active.
*/
enum PropertyValueType
{
EvaluatedValue = 0, /*< return the current evaluated value for the property */
OriginalValue /*< return the original, user set value */
};

/**Constructor
@param composition parent composition
@param manageZValue true if the z-Value of this object should be managed by mComposition*/
Expand Down Expand Up @@ -259,21 +219,9 @@ class QgsComposerItem : QObject, QGraphicsRectItem
corresponds to 1 scene size unit*/
virtual void setSceneRect( const QRectF& rectangle );

/** stores state in Dom element
* @param elem is Dom element corresponding to 'Composer' tag
* @param doc is the Dom document
*/
virtual bool writeXML( QDomElement& elem, QDomDocument & doc ) const = 0;

/**Writes parameter that are not subclass specific in document. Usually called from writeXML methods of subclasses*/
bool _writeXML( QDomElement& itemElem, QDomDocument& doc ) const;

/** sets state from Dom document
* @param itemElem is Dom node corresponding to item tag
* @param doc is Dom document
*/
virtual bool readXML( const QDomElement& itemElem, const QDomDocument& doc ) = 0;

/**Reads parameter that are not subclass specific in document. Usually called from readXML methods of subclasses*/
bool _readXML( const QDomElement& itemElem, const QDomDocument& doc );

Expand Down Expand Up @@ -394,8 +342,6 @@ class QgsComposerItem : QObject, QGraphicsRectItem
virtual void addItem( QgsComposerItem* item );
virtual void removeItems();

const QgsComposition* composition() const;

virtual void beginItemCommand( const QString& text );

/**Starts new composer undo command
Expand Down Expand Up @@ -466,7 +412,7 @@ class QgsComposerItem : QObject, QGraphicsRectItem
* settings).
* @note this method was added in version 2.1
*/
double itemRotation( PropertyValueType valueType = EvaluatedValue ) const;
double itemRotation( QgsComposerObject::PropertyValueType valueType = QgsComposerObject::EvaluatedValue ) const;

/**Returns the rotation for the composer item
* @deprecated Use itemRotation()
Expand Down Expand Up @@ -517,22 +463,6 @@ class QgsComposerItem : QObject, QGraphicsRectItem
*/
void setCurrentExportLayer( int layerIdx = -1 );

/**Returns a reference to the data defined settings for one of the item's data defined properties.
* @param property data defined property to return
* @note this method was added in version 2.5
*/
QgsDataDefined* dataDefinedProperty( DataDefinedProperty property );

/**Sets parameters for a data defined property for the item
* @param property data defined property to set
* @param active true if data defined property is active, false if it is disabled
* @param useExpression true if the expression should be used
* @param expression expression for data defined property
* @field field name if the data defined property should take its value from a field
* @note this method was added in version 2.5
*/
void setDataDefinedProperty( DataDefinedProperty property, bool active, bool useExpression, const QString &expression, const QString &field );

public slots:
/**Sets the item rotation
* @deprecated Use setItemRotation( double rotation ) instead
Expand All @@ -556,7 +486,7 @@ class QgsComposerItem : QObject, QGraphicsRectItem
* refreshed.
* @note this method was added in version 2.5
*/
virtual void refreshDataDefinedProperty( DataDefinedProperty property = AllProperties );
virtual void refreshDataDefinedProperty( QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties );

protected:

Expand Down Expand Up @@ -597,43 +527,52 @@ class QgsComposerItem : QObject, QGraphicsRectItem

//some utility functions

/**Calculates width and hight of the picture (in mm) such that it fits into the item frame with the given rotation*/
bool imageSizeConsideringRotation( double& width, double& height, double rotation ) const;
/**Calculates width and hight of the picture (in mm) such that it fits into the item frame with the given rotation.
* @deprecated will be removed in QGIS 3.0
*/
bool imageSizeConsideringRotation( double& width, double& height, double rotation ) const /Deprecated/;

/**Calculates width and hight of the picture (in mm) such that it fits into the item frame with the given rotation
* @deprecated Use bool imageSizeConsideringRotation( double& width, double& height, double rotation )
* instead
* @deprecated will be removed in QGIS 3.0
*/
bool imageSizeConsideringRotation( double& width, double& height ) const /Deprecated/;

/**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
*/
QRectF largestRotatedRectWithinBounds( QRectF originalRect, QRectF boundsRect, double rotation ) const;
* 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
* @deprecated use QgsComposerUtils::largestRotatedRectWithinBounds instead
*/
QRectF largestRotatedRectWithinBounds( QRectF originalRect, QRectF boundsRect, double rotation ) const /Deprecated/;

/**Calculates corner point after rotation and scaling*/
bool cornerPointOnRotatedAndScaledRect( double& x, double& y, double width, double height, double rotation ) const;
/**Calculates corner point after rotation and scaling
* @deprecated Use bool cornerPointOnRotatedAndScaledRect( double& x, double& y, double width, double height, double rotation )
* instead
* @deprecated will be removed in QGIS 3.0
*/
bool cornerPointOnRotatedAndScaledRect( double& x, double& y, double width, double height, double rotation ) const /Deprecated/;

/**Calculates corner point after rotation and scaling
* @deprecated will be removed in QGIS 3.0
*/
bool cornerPointOnRotatedAndScaledRect( double& x, double& y, double width, double height ) const /Deprecated/;

/**Calculates width / height of the bounding box of a rotated rectangle*/
void sizeChangedByRotation( double& width, double& height, double rotation );
/**Calculates corner point after rotation and scaling
* @deprecated will be removed in QGIS 3.0
*/
void sizeChangedByRotation( double& width, double& height, double rotation ) /Deprecated/;

/**Calculates width / height of the bounding box of a rotated rectangle
* @deprecated Use void sizeChangedByRotation( double& width, double& height, double rotation )
* instead
* @deprecated will be removed in QGIS 3.0
*/
void sizeChangedByRotation( double& width, double& height ) /Deprecated/;

/**Rotates a point / vector
@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*/
void rotate( double angle, double& x, double& y ) const;
* @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
* @deprecated use QgsComposerUtils:rotate instead
*/
void rotate( double angle, double& x, double& y ) const /Deprecated/;

/**Return horizontal align snap item. Creates a new graphics line if 0*/
QGraphicsLineItem* hAlignSnapItem();
Expand All @@ -643,22 +582,12 @@ class QgsComposerItem : QObject, QGraphicsRectItem
void deleteVAlignSnapItem();
void deleteAlignItems();

/**Evaluate a data defined property and return the calculated value
* @returns true if data defined property could be successfully evaluated
* @param property data defined property to evaluate
* @param expressionValue QVariant for storing the evaluated value
* @note this method was added in version 2.5
*/
bool dataDefinedEvaluate( QgsComposerItem::DataDefinedProperty property, QVariant &expressionValue );

/**Update an item rect to consider data defined position and size of item*/
QRectF evalItemRect( const QRectF &newRect );

signals:
/**Is emitted on item rotation change*/
void itemRotationChanged( double newRotation );
/**Used e.g. by the item widgets to update the gui elements*/
void itemChanged();
/**Emitted if the rectangle changes*/
void sizeChanged();
/**Emitted if the item's frame style changes
Expand Down
4 changes: 2 additions & 2 deletions python/core/composer/qgscomposermap.sip
Expand Up @@ -348,7 +348,7 @@ class QgsComposerMap : QgsComposerItem
* or the current evaluated rotation (which may be affected by data driven rotation
* settings).
*/
double mapRotation( PropertyValueType valueType = EvaluatedValue ) const;
// double mapRotation( QgsComposerBaseItem::PropertyValueType valueType = QgsComposerBaseItem::EvaluatedValue ) const;

void updateItem();

Expand Down Expand Up @@ -513,5 +513,5 @@ class QgsComposerMap : QgsComposerItem

void overviewExtentChanged();

virtual void refreshDataDefinedProperty( DataDefinedProperty property = AllProperties );
virtual void refreshDataDefinedProperty( QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties );
};
2 changes: 1 addition & 1 deletion python/core/composer/qgscomposermultiframe.sip
@@ -1,6 +1,6 @@

/**Abstract base class for composer entries with the ability to distribute the content to several frames (items)*/
class QgsComposerMultiFrame: QObject
class QgsComposerMultiFrame: QgsComposerObject
{
%TypeHeaderCode
#include "qgscomposermultiframe.h"
Expand Down
112 changes: 112 additions & 0 deletions python/core/composer/qgscomposerobject.sip
@@ -0,0 +1,112 @@
/** \ingroup MapComposer
* A item that forms part of a map composition.
*/
class QgsComposerObject : QObject
{
%TypeHeaderCode
#include <qgscomposerobject.h>
%End

public:

/** Data defined properties for different item types
*/
enum DataDefinedProperty
{
NoProperty = 0, /*< no property */
AllProperties, /*< all properties for item */
//composer page properties
PresetPaperSize, /*< preset paper size for composition */
PaperWidth, /*< paper width */
PaperHeight, /*< paper height */
NumPages, /*< number of pages in composition */
PaperOrientation, /*< paper orientation */
//general composer item properties
PageNumber, /*< page number for item placement */
PositionX, /*< x position on page */
PositionY, /*< y position on page */
ItemWidth, /*< width of item */
ItemHeight, /*< height of item */
ItemRotation, /*< rotation of item */
Transparency, /*< item transparency */
BlendMode, /*< item blend mode */
//composer map
MapRotation, /*< map rotation */
MapScale, /*< map scale */
MapXMin, /*< map extent x minimum */
MapYMin, /*< map extent y minimum */
MapXMax, /*< map extent x maximum */
MapYMax /*< map extent y maximum */
};

/** Specifies whether the value returned by a function should be the original, user
* set value, or the current evaluated value for the property. This may differ if
* a property has a data defined expression active.
*/
enum PropertyValueType
{
EvaluatedValue = 0, /*< return the current evaluated value for the property */
OriginalValue /*< return the original, user set value */
};

/**Constructor
* @param composition parent composition
*/
QgsComposerObject( QgsComposition* composition );
virtual ~QgsComposerObject();

/**Returns the composition the item is attached to.
* @returns QgsComposition for item.
*/
const QgsComposition* composition() const;

/**Stores item state in DOM element
* @param elem is DOM element corresponding to 'Composer' tag
* @param doc is the DOM document
*/
virtual bool writeXML( QDomElement& elem, QDomDocument & doc ) const;

/**Sets item state from DOM element
* @param itemElem is DOM node corresponding to item tag
* @param doc is DOM document
*/
virtual bool readXML( const QDomElement& itemElem, const QDomDocument& doc );

/**Returns a reference to the data defined settings for one of the item's data defined properties.
* @param property data defined property to return
* @note this method was added in version 2.5
*/
QgsDataDefined* dataDefinedProperty( const DataDefinedProperty property );

/**Sets parameters for a data defined property for the item
* @param property data defined property to set
* @param active true if data defined property is active, false if it is disabled
* @param useExpression true if the expression should be used
* @param expression expression for data defined property
* @field field name if the data defined property should take its value from a field
* @note this method was added in version 2.5
*/
void setDataDefinedProperty( const DataDefinedProperty property, const bool active, const bool useExpression, const QString &expression, const QString &field );

public slots:

/**Triggers a redraw for the item*/
virtual void repaint();

protected:

/**Evaluate a data defined property and return the calculated value
* @returns true if data defined property could be successfully evaluated
* @param property data defined property to evaluate
* @param expressionValue QVariant for storing the evaluated value
* @note this method was added in version 2.5
*/
bool dataDefinedEvaluate( QgsComposerObject::DataDefinedProperty property, QVariant &expressionValue );

signals:
/**Emitted when the item changes. Signifies that the item widgets must update the
* gui elements.
*/
void itemChanged();

};

0 comments on commit 2041fc2

Please sign in to comment.