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