Skip to content

Commit

Permalink
[api] Add registry and interface for QgsNumericFormats
Browse files Browse the repository at this point in the history
QgsNumericFormat subclasses provide a means to format a numeric value
as a string, applying various formatting options. E.g. a default
string to value formatter (included here) includes settings for
controlling the number of decimal places, whether a thousands separator
should be shown, whether a leading + sign should be shown, whether
trailing zeros should be shown.

This PR also includes a formatter for bearings, allowing various
formats of numeric bearings to be applied (e.g. control over decimal
places, etc + control over whether direction E/W suffixes are shown,
or whether values should be limited to either the +/- 180 range or
0-360 degree range)

When formatting values, a QgsNumericFormatContext class is used
to provide context. Currently, this includes the thousands and
decimal separators to apply when formatting (which are taken by
default from the user's locale).

A registry of formatters is included to allow easy addition of
other formats in future (e.g. currencies, percentages, scientific
notation, etc...) and to allow plugin based formats.

The intention is to follow this up with gui configuration widgets
for the formats, and then expose them in various places through
the qgis ui (e.g. in the range editor widget for fields, in scalebar
numbers, as an option for formatting numeric labels, etc)
  • Loading branch information
nyalldawson committed Jan 8, 2020
1 parent 400e3da commit d0b5a01
Show file tree
Hide file tree
Showing 26 changed files with 1,734 additions and 2 deletions.
1 change: 1 addition & 0 deletions doc/CMakeLists.txt
Expand Up @@ -90,6 +90,7 @@ IF(WITH_APIDOC)
${CMAKE_SOURCE_DIR}/src/core/locator
${CMAKE_SOURCE_DIR}/src/core/metadata
${CMAKE_SOURCE_DIR}/src/core/mesh
${CMAKE_SOURCE_DIR}/src/core/numericformats
${CMAKE_SOURCE_DIR}/src/core/pal
${CMAKE_SOURCE_DIR}/src/core/processing
${CMAKE_SOURCE_DIR}/src/core/providers
Expand Down
1 change: 1 addition & 0 deletions python/CMakeLists.txt
Expand Up @@ -113,6 +113,7 @@ INCLUDE_DIRECTORIES(
${CMAKE_SOURCE_DIR}/src/core/locator
${CMAKE_SOURCE_DIR}/src/core/metadata
${CMAKE_SOURCE_DIR}/src/core/mesh
${CMAKE_SOURCE_DIR}/src/core/numericformats
${CMAKE_SOURCE_DIR}/src/core/processing
${CMAKE_SOURCE_DIR}/src/core/processing/models
${CMAKE_SOURCE_DIR}/src/core/providers
Expand Down
121 changes: 121 additions & 0 deletions python/core/auto_generated/numericformats/qgsbasicnumericformat.sip.in
@@ -0,0 +1,121 @@
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/numericformats/qgsbasicnumericformat.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/


class QgsBasicNumericFormat : QgsNumericFormat
{
%Docstring
A numeric formatter which returns a simple text representation of a value.

.. versionadded:: 3.12
%End

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

QgsBasicNumericFormat();
%Docstring
Default constructor
%End


virtual QString id() const;

virtual QString formatDouble( double value, const QgsNumericFormatContext &context ) const;

virtual QgsNumericFormat *clone() const /Factory/;

virtual QgsNumericFormat *create( const QVariantMap &configuration ) const /Factory/;

virtual QVariantMap configuration() const;


void setConfiguration( const QVariantMap &configuration );
%Docstring
Sets the format's ``configuration``.
%End

int numberDecimalPlaces() const;
%Docstring
Returns the maximum number of decimal places to show.

.. seealso:: :py:func:`setNumberDecimalPlaces`

.. seealso:: :py:func:`showTrailingZeros`
%End

void setNumberDecimalPlaces( int numberDecimalPlaces );
%Docstring
Sets the maximum number of decimal places to show.

.. seealso:: :py:func:`numberDecimalPlaces`

.. seealso:: :py:func:`setShowTrailingZeros`
%End

bool showThousandsSeparator() const;
%Docstring
Returns ``True`` if the thousands grouping separator will be shown.

.. seealso:: :py:func:`setShowThousandsSeparator`
%End

void setShowThousandsSeparator( bool showThousandsSeparator );
%Docstring
Sets whether the thousands grouping separator will be shown.

.. seealso:: :py:func:`showThousandsSeparator`
%End

bool showPlusSign() const;
%Docstring
Returns ``True`` if a leading plus sign will be shown for positive values.

.. seealso:: :py:func:`setShowPlusSign`
%End

void setShowPlusSign( bool showPlusSign );
%Docstring
Sets whether a leading plus sign will be shown for positive values.

.. seealso:: :py:func:`showPlusSign`
%End

bool showTrailingZeros() const;
%Docstring
Returns ``True`` if trailing zeros will be shown (up to the specified
numberDecimalPlaces()).

.. seealso:: :py:func:`setShowTrailingZeros`

.. seealso:: :py:func:`numberDecimalPlaces`
%End

void setShowTrailingZeros( bool showTrailingZeros );
%Docstring
Sets whether trailing zeros will be shown (up to the specified
numberDecimalPlaces()).

.. seealso:: :py:func:`showTrailingZeros`

.. seealso:: :py:func:`setNumberDecimalPlaces`
%End

private:
QgsBasicNumericFormat( const QgsBasicNumericFormat &other );
};

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


class QgsBearingNumericFormat : QgsBasicNumericFormat
{
%Docstring
A numeric formatter which returns a text representation of a direction/bearing.

.. versionadded:: 3.12
%End

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

enum FormatDirectionOption
{
UseRange0To180WithEWDirectionalSuffix,
UseRangeNegative180ToPositive180,
UseRange0To360,
};

QgsBearingNumericFormat();
%Docstring
Default constructor
%End


virtual QString id() const;

virtual QString formatDouble( double value, const QgsNumericFormatContext &context ) const;

virtual QgsNumericFormat *clone() const /Factory/;

virtual QgsNumericFormat *create( const QVariantMap &configuration ) const /Factory/;

virtual QVariantMap configuration() const;


FormatDirectionOption directionFormat() const;
%Docstring
Returns the directional formatting option, which controls how bearing direction is
described in the returned strings.

.. seealso:: :py:func:`setDirectionFormat`
%End

void setDirectionFormat( const FormatDirectionOption &format );
%Docstring
Sets the directional formatting option, which controls how bearing direction is
described in the returned strings.

.. seealso:: :py:func:`directionFormat`
%End

private:
QgsBearingNumericFormat( const QgsBearingNumericFormat &other );
};

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


class QgsFallbackNumericFormat : QgsNumericFormat
{
%Docstring
A basic numeric formatter which returns a simple text representation of a value.

.. versionadded:: 3.12
%End

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

QgsFallbackNumericFormat();
%Docstring
Default constructor
%End
virtual QString id() const;

virtual QString formatDouble( double value, const QgsNumericFormatContext &context ) const;

virtual QgsNumericFormat *clone() const /Factory/;

virtual QgsNumericFormat *create( const QVariantMap &configuration ) const /Factory/;

virtual QVariantMap configuration() const;

};

/************************************************************************
* This file has been generated automatically from *
* *
* src/core/numericformats/qgsfallbacknumericformat.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/
141 changes: 141 additions & 0 deletions python/core/auto_generated/numericformats/qgsnumericformat.sip.in
@@ -0,0 +1,141 @@
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/numericformats/qgsnumericformat.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/



class QgsNumericFormatContext
{
%Docstring
A context for numeric formats

.. versionadded:: 3.12
%End

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

QgsNumericFormatContext();
%Docstring
Constructor for QgsNumericFormatContext.

The context will be populated based on the user's current locale settings.
%End


QChar thousandsSeparator() const;
%Docstring
Returns the thousands separator character.

.. seealso:: :py:func:`setThousandsSeparator`
%End

void setThousandsSeparator( const QChar &separator );
%Docstring
Sets the thousands ``separator`` character.

.. seealso:: :py:func:`thousandsSeparator`
%End

QChar decimalSeparator() const;
%Docstring
Returns the decimal separator character.

.. seealso:: :py:func:`setDecimalSeparator`
%End

void setDecimalSeparator( const QChar &separator );
%Docstring
Returns the decimal separator character.

.. seealso:: :py:func:`setDecimalSeparator`
%End

};

%ModuleHeaderCode
#include <qgsbasicnumericformat.h>
#include <qgsbearingnumericformat.h>
#include <qgsfallbacknumericformat.h>
%End

class QgsNumericFormat
{
%Docstring
A numeric formatter allows for formatting a numeric value for display, using
a variety of different formatting techniques (e.g. as scientific notation, currency values,
percentage values, etc)

This is an abstract base class and will always need to be subclassed.

.. versionadded:: 3.12
%End

%TypeHeaderCode
#include "qgsnumericformat.h"
%End
%ConvertToSubClassCode
if ( dynamic_cast< QgsBasicNumericFormat * >( sipCpp ) )
sipType = sipType_QgsBasicNumericFormat;
else if ( dynamic_cast< QgsBearingNumericFormat * >( sipCpp ) )
sipType = sipType_QgsBearingNumericFormat;
else if ( dynamic_cast< QgsFallbackNumericFormat * >( sipCpp ) )
sipType = sipType_QgsFallbackNumericFormat;
else
sipType = NULL;
%End
public:

QgsNumericFormat();
%Docstring
Default constructor
%End

virtual ~QgsNumericFormat();

virtual QString id() const = 0;
%Docstring
Returns a unique id for this numeric format.

This id is used to identify this numeric format in the registry with :py:func:`QgsNumericFormatRegistry.format()`
%End

virtual QString formatDouble( double value, const QgsNumericFormatContext &context ) const = 0;
%Docstring
Returns a formatted string representation of a numeric double value.
%End

virtual QgsNumericFormat *clone() const = 0 /Factory/;
%Docstring
Clones the format, returning a new object.

The caller takes ownership of the returned object.
%End

virtual QgsNumericFormat *create( const QVariantMap &configuration ) const = 0 /Factory/;
%Docstring
Creates a new copy of the format, using the supplied ``configuration``.

The caller takes ownership of the returned object.
%End

virtual QVariantMap configuration() const = 0;
%Docstring
Returns the current configuration of the formatter. This value can be used in a call to create()
in order to recreate this formatter in its current state.
%End
};

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

0 comments on commit d0b5a01

Please sign in to comment.