Add doxymentation for field formatters

qgis · Jan 8, 2017 · 552e1b2 · 552e1b2
1 parent f7ae653
commit 552e1b2
Show file tree

Hide file tree

Showing 10 changed files with 82 additions and 9 deletions.
diff --git a/src/core/fieldformatter/qgsdatetimefieldformatter.cpp b/src/core/fieldformatter/qgsdatetimefieldformatter.cpp
@@ -60,7 +60,7 @@ QString QgsDateTimeFieldFormatter::representValue( QgsVectorLayer* layer, int fi
   return result;
 }
 
-QString QgsDateTimeFieldFormatter::defaultFormat( const QVariant::Type type )
+QString QgsDateTimeFieldFormatter::defaultFormat( QVariant::Type type )
 {
   switch ( type )
   {

diff --git a/src/core/fieldformatter/qgsdatetimefieldformatter.h b/src/core/fieldformatter/qgsdatetimefieldformatter.h
@@ -19,6 +19,14 @@
 #include "qgis_core.h"
 #include "qgsfieldformatter.h"
 
+/**
+ * \ingroup core
+ * Field formatter for a date time field.
+ * This represents a date, time or datetime value based on
+ * the field configuration.
+ *
+ * \note Added in QGIS 3.0
+ */
 class CORE_EXPORT QgsDateTimeFieldFormatter : public QgsFieldFormatter
 {
   public:
@@ -38,7 +46,7 @@ class CORE_EXPORT QgsDateTimeFieldFormatter : public QgsFieldFormatter
      * - QVariant::Date
      * - QVariant::Time
      */
-    static QString defaultFormat( const QVariant::Type type );
+    static QString defaultFormat( QVariant::Type type );
 };
 
 #endif // QGSDATETIMEFIELDKIT_H
diff --git a/src/core/fieldformatter/qgsfallbackfieldformatter.h b/src/core/fieldformatter/qgsfallbackfieldformatter.h
@@ -19,6 +19,13 @@
 #include "qgis_core.h"
 #include "qgsfieldformatter.h"
 
+/**
+ * \ingroup core
+ * A default fallback field formatter in case no specialized field formatter is defined.
+ * The values will be returned unmodified.
+ *
+ * \note Added in QGIS 3.0
+ */
 class CORE_EXPORT QgsFallbackFieldFormatter : public QgsFieldFormatter
 {
   public:

diff --git a/src/core/fieldformatter/qgskeyvaluefieldformatter.cpp b/src/core/fieldformatter/qgskeyvaluefieldformatter.cpp
@@ -32,15 +32,15 @@ QString QgsKeyValueFieldFormatter::representValue( QgsVectorLayer* layer, int fi
 
   if ( value.isNull() )
   {
-    QSettings settings;
     return QgsApplication::nullRepresentation();
   }
 
   QString result;
   const QVariantMap map = value.toMap();
   for ( QVariantMap::const_iterator i = map.constBegin(); i != map.constEnd(); ++i )
   {
-    if ( !result.isEmpty() ) result.append( ", " );
+    if ( !result.isEmpty() )
+      result.append( ", " );
     result.append( i.key() ).append( ": " ).append( i.value().toString() );
   }
   return result;

diff --git a/src/core/fieldformatter/qgskeyvaluefieldformatter.h b/src/core/fieldformatter/qgskeyvaluefieldformatter.h
@@ -19,6 +19,17 @@
 #include "qgis_core.h"
 #include "qgsfieldformatter.h"
 
+/**
+ * \ingroup core
+ * Field formatter for a key value field.
+ * This represents a list type value.
+ * Values will be represented as a colon-delimited and
+ * comma-separated list.
+ *
+ * E.g. "color: yellow, amount: 5"
+ *
+ * \note Added in QGIS 3.0
+ */
 class CORE_EXPORT QgsKeyValueFieldFormatter : public QgsFieldFormatter
 {
   public:

diff --git a/src/core/fieldformatter/qgslistfieldformatter.cpp b/src/core/fieldformatter/qgslistfieldformatter.cpp
@@ -31,16 +31,15 @@ QString QgsListFieldFormatter::representValue( QgsVectorLayer* layer, int fieldI
 
   if ( value.isNull() )
   {
-    QSettings settings;
     return QgsApplication::nullRepresentation();
   }
 
   QString result;
-  const QVariantList list = value.toList();
-  for ( QVariantList::const_iterator i = list.constBegin(); i != list.constEnd(); ++i )
+  Q_FOREACH ( const QVariant& val, value.toList() )
   {
-    if ( !result.isEmpty() ) result.append( ", " );
-    result.append( i->toString() );
+    if ( !result.isEmpty() )
+      result.append( ", " );
+    result.append( val.toString() );
   }
   return result;
 }
diff --git a/src/core/fieldformatter/qgslistfieldformatter.h b/src/core/fieldformatter/qgslistfieldformatter.h
@@ -19,6 +19,14 @@
 #include "qgis_core.h"
 #include "qgsfieldformatter.h"
 
+/**
+ * \ingroup core
+ * Field formatter for a list field.
+ * This represents a list type value.
+ * Values will be represented as a comma-separated list.
+ *
+ * \note Added in QGIS 3.0
+ */
 class CORE_EXPORT QgsListFieldFormatter : public QgsFieldFormatter
 {
   public:

diff --git a/src/core/fieldformatter/qgsrelationreferencefieldformatter.h b/src/core/fieldformatter/qgsrelationreferencefieldformatter.h
@@ -19,6 +19,14 @@
 #include "qgis_core.h"
 #include "qgsfieldformatter.h"
 
+/**
+ * \ingroup core
+ * Field formatter for a relation reference field.
+ * A value relation field formatter looks up the values from
+ * features on another layer.
+ *
+ * \note Added in QGIS 3.0
+ */
 class CORE_EXPORT QgsRelationReferenceFieldFormatter : public QgsFieldFormatter
 {
   public:

diff --git a/src/core/fieldformatter/qgsvaluemapfieldformatter.h b/src/core/fieldformatter/qgsvaluemapfieldformatter.h
@@ -19,6 +19,23 @@
 #include "qgis_core.h"
 #include "qgsfieldformatter.h"
 
+/**
+ * \ingroup core
+ * Field formatter for a ValueMap field.
+ * A value relation field formatter looks up the values a map.
+ *
+ * The map is defined in the configuration as dictionary under the key "map".
+ *
+ * { "map": { 1: "one", 2: "two", 3: "three" } }
+ *
+ * Values that are not on the map will be wrapped in parantheses. So with the above
+ * configuration:
+ *
+ * - 3 => "three"
+ * - 5 => "(5)"
+ *
+ * \note Added in QGIS 3.0
+ */
 class CORE_EXPORT QgsValueMapFieldFormatter : public QgsFieldFormatter
 {
   public:

diff --git a/src/core/fieldformatter/qgsvaluerelationfieldformatter.h b/src/core/fieldformatter/qgsvaluerelationfieldformatter.h
@@ -22,6 +22,14 @@
 #include <QVector>
 #include <QVariant>
 
+/**
+ * \ingroup core
+ * Field formatter for a value relation field.
+ * A value relation field formatter looks up the values from
+ * features on another layer.
+ *
+ * \note Added in QGIS 3.0
+ */
 class CORE_EXPORT QgsValueRelationFieldFormatter : public QgsFieldFormatter
 {
   public:
@@ -50,6 +58,13 @@ class CORE_EXPORT QgsValueRelationFieldFormatter : public QgsFieldFormatter
 
     QVariant createCache( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config ) const override;
 
+    /**
+     * Create a cache for a value relation field.
+     * This can be used to keep the value map in the local memory
+     * if doing multiple lookups in a loop.
+     *
+     * \note Added in QGIS 3.0
+     */
     static ValueRelationCache createCache( const QVariantMap& config );
 };