Skip to content
Permalink
Browse files

[layout] Add layout measurement and size classes

These classes are used for storing measurements for a layout
(QgsLayoutMeasurement), sizes for a layout (QgsLayoutSize)
and points in a layout (QgsLayoutPoint)

They support storing a measurement unit alongside a measurement
length/size. A new class QgsLayoutMeasurementConverter handles
conversion between different units, including converting to and
from pixels via a specified DPI property.
  • Loading branch information
nyalldawson committed Jun 23, 2017
1 parent 81855a7 commit 6a54130f0b56cf1db86511ca54b99c3eceecf44d
@@ -63,6 +63,7 @@ IF(WITH_APIDOC)
${CMAKE_SOURCE_DIR}/src/core/geometry
${CMAKE_SOURCE_DIR}/src/core/gps
${CMAKE_SOURCE_DIR}/src/core/layertree
${CMAKE_SOURCE_DIR}/src/core/layout
${CMAKE_SOURCE_DIR}/src/core/metadata
${CMAKE_SOURCE_DIR}/src/core/pal
${CMAKE_SOURCE_DIR}/src/core/processing
@@ -106,6 +106,7 @@ INCLUDE_DIRECTORIES(
${CMAKE_SOURCE_DIR}/src/core/geometry
${CMAKE_SOURCE_DIR}/src/core/gps
${CMAKE_SOURCE_DIR}/src/core/layertree
${CMAKE_SOURCE_DIR}/src/core/layout
${CMAKE_SOURCE_DIR}/src/core/metadata
${CMAKE_SOURCE_DIR}/src/core/processing
${CMAKE_SOURCE_DIR}/src/core/providers
@@ -369,6 +369,11 @@ done:
%Include layertree/qgslayertreeregistrybridge.sip
%Include layertree/qgslayertreeutils.sip

%Include layout/qgslayoutmeasurement.sip
%Include layout/qgslayoutmeasurementconverter.sip
%Include layout/qgslayoutpoint.sip
%Include layout/qgslayoutsize.sip

%Include metadata/qgslayermetadata.sip
%Include metadata/qgslayermetadatavalidator.sip

@@ -0,0 +1,123 @@
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/layout/qgslayoutmeasurement.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/





class QgsLayoutMeasurement
{
%Docstring
This class provides a method of storing measurements for use in QGIS layouts
using a variety of different measurement units.
.. seealso:: QgsLayoutMeasurementConverter
.. versionadded:: 3.0
%End

%TypeHeaderCode
#include "qgslayoutmeasurement.h"
%End
public:

explicit QgsLayoutMeasurement( const double length, const QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );
%Docstring
Constructor for QgsLayoutMeasurement.
\param length measurement length
\param units measurement units
%End

~QgsLayoutMeasurement();

double length() const;
%Docstring
Returns the length of the measurement.
.. seealso:: setLength()
:rtype: float
%End

void setLength( const double length );
%Docstring
Sets the ``length`` of the measurement.
.. seealso:: length()
%End

QgsUnitTypes::LayoutUnit units() const;
%Docstring
Returns the units for the measurement.
.. seealso:: setUnits()
:rtype: QgsUnitTypes.LayoutUnit
%End

void setUnits( const QgsUnitTypes::LayoutUnit units );
%Docstring
Sets the ``units`` for the measurement. Does not alter the stored length,
ie. no length conversion is done.
.. seealso:: units()
%End

QString encodeMeasurement() const;
%Docstring
Encodes the layout measurement to a string
.. seealso:: decodeMeasurement()
:rtype: str
%End

static QgsLayoutMeasurement decodeMeasurement( const QString &string );
%Docstring
Decodes a measurement from a ``string``.
.. seealso:: encodeMeasurement()
:rtype: QgsLayoutMeasurement
%End

bool operator==( const QgsLayoutMeasurement &other ) const;
bool operator!=( const QgsLayoutMeasurement &other ) const;
%Docstring
:rtype: bool
%End
QgsLayoutMeasurement operator+( const double v ) const;
%Docstring
:rtype: QgsLayoutMeasurement
%End
QgsLayoutMeasurement operator+=( const double v );
%Docstring
:rtype: QgsLayoutMeasurement
%End
QgsLayoutMeasurement operator-( const double v ) const;
%Docstring
:rtype: QgsLayoutMeasurement
%End
QgsLayoutMeasurement operator-=( const double v );
%Docstring
:rtype: QgsLayoutMeasurement
%End
QgsLayoutMeasurement operator*( const double v ) const;
%Docstring
:rtype: QgsLayoutMeasurement
%End
QgsLayoutMeasurement operator*=( const double v );
%Docstring
:rtype: QgsLayoutMeasurement
%End
QgsLayoutMeasurement operator/( const double v ) const;
%Docstring
:rtype: QgsLayoutMeasurement
%End
QgsLayoutMeasurement operator/=( const double v );
%Docstring
:rtype: QgsLayoutMeasurement
%End

};

/************************************************************************
* This file has been generated automatically from *
* *
* src/core/layout/qgslayoutmeasurement.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/
@@ -0,0 +1,83 @@
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/layout/qgslayoutmeasurementconverter.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/





class QgsLayoutMeasurementConverter
{
%Docstring
This class provides a method of converting QgsLayoutMeasurements from
one unit to another. Conversion to or from pixel units utilizes a specified
dots per inch (DPI) property for the converter. Converters default to using
300 DPI.
.. seealso:: QgsLayoutMeasurement
.. versionadded:: 3.0
%End

%TypeHeaderCode
#include "qgslayoutmeasurementconverter.h"
%End
public:

QgsLayoutMeasurementConverter();

~QgsLayoutMeasurementConverter();

void setDpi( const double dpi );
%Docstring
Sets the dots per inch (``dpi``) for the measurement converter. This is used
when converting measurements to and from pixels.
.. seealso:: dpi()
%End

double dpi() const;
%Docstring
Returns the Dots per inch (DPI) of the measurement converter. This is used
when converting measurements to and from pixels.
.. seealso:: setDpi()
:rtype: float
%End

QgsLayoutMeasurement convert( const QgsLayoutMeasurement &measurement, const QgsUnitTypes::LayoutUnit targetUnits ) const;
%Docstring
Converts a measurement from one unit to another.
\param measurement measurement to convert
\param targetUnits units to convert measurement into
:return: measurement converted to target units
:rtype: QgsLayoutMeasurement
%End

QgsLayoutSize convert( const QgsLayoutSize &size, const QgsUnitTypes::LayoutUnit targetUnits ) const;
%Docstring
Converts a layout size from one unit to another.
\param size layout size to convert
\param targetUnits units to convert size into
:return: size converted to target units
:rtype: QgsLayoutSize
%End

QgsLayoutPoint convert( const QgsLayoutPoint &point, const QgsUnitTypes::LayoutUnit targetUnits ) const;
%Docstring
Converts a layout point from one unit to another.
\param point layout point to convert
\param targetUnits units to convert point into
:return: point converted to target units
:rtype: QgsLayoutPoint
%End

};

/************************************************************************
* This file has been generated automatically from *
* *
* src/core/layout/qgslayoutmeasurementconverter.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/
@@ -0,0 +1,162 @@
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/layout/qgslayoutpoint.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/




class QgsLayoutPoint
{
%Docstring
This class provides a method of storing points, consisting of an x and y coordinate,
for use in QGIS layouts. Measurement units are stored alongside the position.

.. seealso:: QgsLayoutMeasurementConverter
.. versionadded:: 3.0
.. note::

This class does not inherit from QPointF since QPointF includes methods which should not apply
to positions with with units. For instance, the + and - operators would mislead users of this class
to believe that addition of two QgsLayoutPoints with different unit types would automatically convert
units. Instead, all unit conversion must be handled by a QgsLayoutMeasurementConverter so that
conversion between paper and screen units can be correctly performed.
%End

%TypeHeaderCode
#include "qgslayoutpoint.h"
%End
public:

QgsLayoutPoint( const double x, const double y, const QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );
%Docstring
Constructor for QgsLayoutPoint.
\param x x coordinate
\param x y coordinate
\param units units for x and y
%End

explicit QgsLayoutPoint( const QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );
%Docstring
Constructor for an empty point, where both x and y are set to 0.
\param units units for measurement
%End

~QgsLayoutPoint();

void setPoint( const double x, const double y );
%Docstring
Sets new x and y coordinates for the point.
.. seealso:: setX()
.. seealso:: setY()
.. seealso:: setUnits()
%End

double x() const;
%Docstring
Returns x coordinate of point.
.. seealso:: setX()
.. seealso:: y()
:rtype: float
%End

void setX( const double x );
%Docstring
Sets the x coordinate of point.
.. seealso:: x()
.. seealso:: setY()
%End

double y() const;
%Docstring
Returns y coordinate of point.
.. seealso:: setY()
.. seealso:: x()
:rtype: float
%End

void setY( const double y );
%Docstring
Sets y coordinate of point.
.. seealso:: y()
.. seealso:: setX()
%End

QgsUnitTypes::LayoutUnit units() const;
%Docstring
Returns the units for the point.
.. seealso:: setUnits()
:rtype: QgsUnitTypes.LayoutUnit
%End

void setUnits( const QgsUnitTypes::LayoutUnit units );
%Docstring
Sets the ``units`` for the point. Does not alter the stored coordinates,
ie. no conversion is done.
.. seealso:: units()
%End

bool isNull() const;
%Docstring
Tests whether the position is null, ie both its x and y coordinates
are zero.
:return: true if point is null
:rtype: bool
%End

QPointF toQPointF() const;
%Docstring
Converts the layout point to a QPointF. The unit information is discarded
during this operation.
:return: QPointF with same x and y coordinates as layout point
:rtype: QPointF
%End

QString encodePoint() const;
%Docstring
Encodes the layout point to a string
.. seealso:: decodePoint()
:rtype: str
%End

static QgsLayoutPoint decodePoint( const QString &string );
%Docstring
Decodes a point from a ``string``.
.. seealso:: encodePoint()
:rtype: QgsLayoutPoint
%End

bool operator==( const QgsLayoutPoint &other ) const;
bool operator!=( const QgsLayoutPoint &other ) const;
%Docstring
:rtype: bool
%End
QgsLayoutPoint operator*( const double v ) const;
%Docstring
:rtype: QgsLayoutPoint
%End
QgsLayoutPoint operator*=( const double v );
%Docstring
:rtype: QgsLayoutPoint
%End
QgsLayoutPoint operator/( const double v ) const;
%Docstring
:rtype: QgsLayoutPoint
%End
QgsLayoutPoint operator/=( const double v );
%Docstring
:rtype: QgsLayoutPoint
%End

};

/************************************************************************
* This file has been generated automatically from *
* *
* src/core/layout/qgslayoutpoint.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/

0 comments on commit 6a54130

Please sign in to comment.
You can’t perform that action at this time.