Sipifi QgsFieldFormatter

arnaud-morvan · 3nids · commit 1fb7855e17c2 · 2017-05-01T17:41:14.000+02:00
diff --git a/python/auto_sip.blacklist b/python/auto_sip.blacklist
@@ -14,7 +14,6 @@ core/qgsfeaturefilterprovider.sip
 core/qgsfeatureiterator.sip
 core/qgsfeaturerequest.sip
 core/qgsfieldformatterregistry.sip
-core/qgsfieldformatter.sip
 core/qgsgeometrysimplifier.sip
 core/qgsgeometryvalidator.sip
 core/qgsgml.sip
diff --git a/python/core/qgsfieldformatter.sip b/python/core/qgsfieldformatter.sip
@@ -1,20 +1,30 @@
-/***************************************************************************
-  qgsfieldformatter.sip - QgsFieldFormatter
-
- ---------------------
- begin                : 2.12.2016
- copyright            : (C) 2016 by Matthias Kuhn
- email                : matthias@opengis.ch
- ***************************************************************************
- *                                                                         *
- *   This program is free software; you can redistribute it and/or modify  *
- *   it under the terms of the GNU General Public License as published by  *
- *   the Free Software Foundation; either version 2 of the License, or     *
- *   (at your option) any later version.                                   *
- *                                                                         *
- ***************************************************************************/
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/qgsfieldformatter.h                                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+
 class QgsFieldFormatter
 {
+%Docstring
+ A field formatter helps to handle and display values for a field.
+
+ It allows for using a shared configuration with the editor widgets
+ for representation of attribute values.
+ Field kits normally have one single instance which is managed by the
+ QgsFieldFormatterRegistry. Custom field formatters should be registered there and
+ field formatters for use within code should normally be obtained from there.
+
+ This is an abstract base class and will always need to be subclassed.
+
+.. versionadded:: 3.0
+%End
+
 %TypeHeaderCode
 #include "qgsfieldformatter.h"
 %End
@@ -24,12 +34,64 @@ class QgsFieldFormatter
     virtual ~QgsFieldFormatter();
 
     virtual QString id() const = 0;
+%Docstring
+ Return a unique id for this field formatter.
+ This id will later be used to identify this field formatter in the registry with QgsFieldFormatterRegistry.fieldFormatter().
+
+ This id matches the id of a QgsEditorWidgetFactory.
+ :rtype: str
+%End
+
+    virtual QString representValue( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config, const QVariant &cache, const QVariant &value ) const;
+%Docstring
+ Create a pretty String representation of the value.
 
-    virtual QString representValue( QgsVectorLayer* layer, int fieldIdx, const QVariantMap& config, const QVariant& cache, const QVariant& value ) const;
+ :return: By default the string representation of the provided value as implied by the field definition is returned.
 
-    virtual QVariant sortValue( QgsVectorLayer* vl, int fieldIdx, const QVariantMap& config, const QVariant& cache, const QVariant& value ) const;
+.. versionadded:: 3.0
+ :rtype: str
+%End
+
+    virtual QVariant sortValue( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config, const QVariant &cache, const QVariant &value ) const;
+%Docstring
+ If the default sort order should be overwritten for this widget, you can transform the value in here.
+
+ :return: an unmodified value by default.
+
+.. versionadded:: 3.0
+ :rtype: QVariant
+%End
+
+    virtual Qt::AlignmentFlag alignmentFlag( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config ) const;
+%Docstring
+ Return the alignment for a particular field. By default this will consider the field type but can be overwritten if mapped
+ values are represented.
 
-    virtual Qt::AlignmentFlag alignmentFlag( QgsVectorLayer* vl, int fieldIdx, const QVariantMap& config ) const;
+.. versionadded:: 3.0
+ :rtype: Qt.AlignmentFlag
+%End
+
+    virtual QVariant createCache( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config ) const;
+%Docstring
+ Create a cache for a given field.
+
+ This will be used in situations where a field is being represented various times in a loop. And will be passed
+ to other methods on QgsFieldKit and QgsEditorWidgetWrapper.
 
-    virtual QVariant createCache( QgsVectorLayer* vl, int fieldIdx, const QVariantMap& config ) const;
+ For example, the attribute table will create a cache once for each field and then use this
+ cache for representation. The QgsValueRelationFieldFormatter and QgsValueRelationEditorWidget
+ implement this functionality to create a lookuptable once (a QVariantMap / dict) and are
+ make use of a cache if present.
+
+.. versionadded:: 3.0
+ :rtype: QVariant
+%End
 };
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/qgsfieldformatter.h                                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
