Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :   qgsfieldformatter.h - QgsFieldFormatter
       3                 :            : 
       4                 :            :  ---------------------
       5                 :            :  begin                : 2.12.2016
       6                 :            :  copyright            : (C) 2016 by Matthias Kuhn
       7                 :            :  email                : matthias@opengis.ch
       8                 :            :  ***************************************************************************
       9                 :            :  *                                                                         *
      10                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      11                 :            :  *   it under the terms of the GNU General Public License as published by  *
      12                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      13                 :            :  *   (at your option) any later version.                                   *
      14                 :            :  *                                                                         *
      15                 :            :  ***************************************************************************/
      16                 :            : #ifndef QGSFIELDKIT_H
      17                 :            : #define QGSFIELDKIT_H
      18                 :            : 
      19                 :            : #include <QString>
      20                 :            : #include <QVariant>
      21                 :            : 
      22                 :            : #include "qgis_core.h"
      23                 :            : #include "qgsvectorlayerref.h"
      24                 :            : 
      25                 :            : class QgsVectorLayer;
      26                 :            : 
      27                 :            : /**
      28                 :            :  * \ingroup core
      29                 :            :  * \brief A context for field formatter containing information like the project
      30                 :            :  *
      31                 :            :  * \since QGIS 3.12
      32                 :            :  */
      33                 :            : class CORE_EXPORT QgsFieldFormatterContext
      34                 :            : {
      35                 :            :   public:
      36                 :            : 
      37                 :            :     /**
      38                 :            :      * Constructor
      39                 :            :      */
      40                 :            :     QgsFieldFormatterContext() = default;
      41                 :            : 
      42                 :            :     /**
      43                 :            :      * Returns the project used in field formatter
      44                 :            :      * \see setProject()
      45                 :            :      */
      46                 :          0 :     QgsProject *project() const { return mProject; }
      47                 :            : 
      48                 :            :     /**
      49                 :            :      * Sets the \a project used in field formatter
      50                 :            :      * \see project()
      51                 :            :      */
      52                 :            :     void setProject( QgsProject *project ) { mProject = project; }
      53                 :            : 
      54                 :            :   private:
      55                 :            :     QgsProject *mProject = nullptr;
      56                 :            : };
      57                 :            : 
      58                 :            : /**
      59                 :            :  * \ingroup core
      60                 :            :  * \brief A field formatter helps to handle and display values for a field.
      61                 :            :  *
      62                 :            :  * It allows for using a shared configuration with the editor widgets
      63                 :            :  * for representation of attribute values.
      64                 :            :  * Field kits normally have one single instance which is managed by the
      65                 :            :  * QgsFieldFormatterRegistry. Custom field formatters should be registered there and
      66                 :            :  * field formatters for use within code should normally be obtained from there.
      67                 :            :  *
      68                 :            :  * This is an abstract base class and will always need to be subclassed.
      69                 :            :  *
      70                 :            :  * \since QGIS 3.0
      71                 :            :  */
      72                 :            : class CORE_EXPORT QgsFieldFormatter
      73                 :            : {
      74                 :            :   public:
      75                 :            : 
      76                 :            :     /**
      77                 :            :       * Default constructor
      78                 :            :       */
      79                 :         45 :     QgsFieldFormatter() = default;
      80                 :            : 
      81                 :         45 :     virtual ~QgsFieldFormatter() = default;
      82                 :            : 
      83                 :            :     /**
      84                 :            :      * Flags for the abilities of the formatter
      85                 :            :      *
      86                 :            :      * \since QGIS 3.12
      87                 :            :      */
      88                 :            :     enum Flag
      89                 :            :     {
      90                 :            :       CanProvideAvailableValues =  1   //!< Can provide possible values
      91                 :            :     };
      92                 :            :     Q_DECLARE_FLAGS( Flags, Flag )
      93                 :            : 
      94                 :            :     /**
      95                 :            :      * Returns a unique id for this field formatter.
      96                 :            :      * This id will later be used to identify this field formatter in the registry with QgsFieldFormatterRegistry::fieldFormatter().
      97                 :            :      *
      98                 :            :      * This id matches the id of a QgsEditorWidgetFactory.
      99                 :            :      */
     100                 :            :     virtual QString id() const = 0;
     101                 :            : 
     102                 :            :     /**
     103                 :            :      * Create a pretty String representation of the value.
     104                 :            :      *
     105                 :            :      * \returns By default the string representation of the provided value as implied by the field definition is returned.
     106                 :            :      *
     107                 :            :      * \since QGIS 3.0
     108                 :            :      */
     109                 :            :     virtual QString representValue( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config, const QVariant &cache, const QVariant &value ) const;
     110                 :            : 
     111                 :            :     /**
     112                 :            :      * If the default sort order should be overwritten for this widget, you can transform the value in here.
     113                 :            :      *
     114                 :            :      * \returns an unmodified value by default.
     115                 :            :      *
     116                 :            :      * \since QGIS 3.0
     117                 :            :      */
     118                 :            :     virtual QVariant sortValue( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config, const QVariant &cache, const QVariant &value ) const;
     119                 :            : 
     120                 :            :     /**
     121                 :            :      * Returns the alignment for a particular field. By default this will consider the field type but can be overwritten if mapped
     122                 :            :      * values are represented.
     123                 :            :      *
     124                 :            :      * \since QGIS 3.0
     125                 :            :      */
     126                 :            :     virtual Qt::AlignmentFlag alignmentFlag( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config ) const;
     127                 :            : 
     128                 :            :     /**
     129                 :            :      * Create a cache for a given field.
     130                 :            :      *
     131                 :            :      * This will be used in situations where a field is being represented various times in a loop. And will be passed
     132                 :            :      * to other methods on QgsFieldKit and QgsEditorWidgetWrapper.
     133                 :            :      *
     134                 :            :      * For example, the attribute table will create a cache once for each field and then use this
     135                 :            :      * cache for representation. The QgsValueRelationFieldFormatter and QgsValueRelationEditorWidget
     136                 :            :      * implement this functionality to create a lookuptable once (a QVariantMap / dict) and are
     137                 :            :      * make use of a cache if present.
     138                 :            :      *
     139                 :            :      * \since QGIS 3.0
     140                 :            :      */
     141                 :            :     virtual QVariant createCache( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config ) const;
     142                 :            : 
     143                 :            :     /**
     144                 :            :      * Returns a list of weak layer references to other layers required by this formatter
     145                 :            :      * for the given \a config.
     146                 :            :      * The default implementation returns an empty list.
     147                 :            :      *
     148                 :            :      * This method should be reimplemented by formatters that handle relations with other layers,
     149                 :            :      * (e.g. ValueRelation) and can be used by client code to warn the user about
     150                 :            :      * missing required dependencies or to add some resolution logic in order
     151                 :            :      * to load the missing dependency.
     152                 :            :      * \note not available in Python bindings
     153                 :            :      * \since QGIS 3.12
     154                 :            :      */
     155                 :            :     virtual QList< QgsVectorLayerRef > layerDependencies( const QVariantMap &config ) const SIP_SKIP;
     156                 :            : 
     157                 :            :     /**
     158                 :            :      * Returns a list of the values that would be possible to select with this widget type
     159                 :            :      * On a RelationReference that would be the parents ids or on ValueMap all the configured keys
     160                 :            :      * according to the settings in the \a config
     161                 :            :      * \since QGIS 3.12
     162                 :            :      */
     163                 :            :     virtual QVariantList availableValues( const QVariantMap &config, int countLimit, const QgsFieldFormatterContext &context ) const;
     164                 :            : 
     165                 :            :     /**
     166                 :            :      * Returns the flags
     167                 :            :      *
     168                 :            :      * \since QGIS 3.12
     169                 :            :      */
     170                 :         15 :     Flags flags() const { return mFlags; }
     171                 :            : 
     172                 :            :     /**
     173                 :            :      * Sets the \a flags
     174                 :            :      *
     175                 :            :      * \since QGIS 3.12
     176                 :            :      */
     177                 :            :     void setFlags( const Flags &flags );
     178                 :            : 
     179                 :            :   private:
     180                 :            :     Flags mFlags;
     181                 :            : };
     182                 :            : 
     183                 :            : #endif // QGSFIELDKIT_H