Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgsfield.h - Describes a field in a layer or table
3 : : --------------------------------------
4 : : Date : 01-Jan-2004
5 : : Copyright : (C) 2004 by Gary E.Sherman
6 : : email : sherman at mrcc.com
7 : : ***************************************************************************
8 : : * *
9 : : * This program is free software; you can redistribute it and/or modify *
10 : : * it under the terms of the GNU General Public License as published by *
11 : : * the Free Software Foundation; either version 2 of the License, or *
12 : : * (at your option) any later version. *
13 : : * *
14 : : ***************************************************************************/
15 : :
16 : : #ifndef QGSFIELD_H
17 : : #define QGSFIELD_H
18 : :
19 : : #include <QString>
20 : : #include <QVariant>
21 : : #include <QVector>
22 : : #include <QSharedDataPointer>
23 : : #include "qgis_core.h"
24 : : #include "qgis_sip.h"
25 : :
26 : : typedef QList<int> QgsAttributeList SIP_SKIP;
27 : :
28 : : /***************************************************************************
29 : : * This class is considered CRITICAL and any change MUST be accompanied with
30 : : * full unit tests in testqgsfield.cpp.
31 : : * See details in QEP #17
32 : : ****************************************************************************/
33 : :
34 : : #include "qgseditorwidgetsetup.h"
35 : : #include "qgsfieldconstraints.h"
36 : : #include "qgsdefaultvalue.h"
37 : :
38 : : class QgsFieldPrivate;
39 : :
40 : : /**
41 : : * \class QgsField
42 : : * \ingroup core
43 : : * \brief Encapsulate a field in an attribute table or data source.
44 : : *
45 : : * QgsField stores metadata about an attribute field, including name, type
46 : : * length, and if applicable, precision.
47 : : * \note QgsField objects are implicitly shared.
48 : : */
49 : :
50 : : class CORE_EXPORT QgsField
51 : : {
52 : : Q_GADGET
53 : :
54 : : Q_PROPERTY( bool isNumeric READ isNumeric )
55 : : Q_PROPERTY( bool isDateOrTime READ isDateOrTime )
56 : : Q_PROPERTY( int length READ length WRITE setLength )
57 : : Q_PROPERTY( int precision READ precision WRITE setPrecision )
58 : : Q_PROPERTY( QVariant::Type type READ type WRITE setType )
59 : : Q_PROPERTY( QString comment READ comment WRITE setComment )
60 : : Q_PROPERTY( QString name READ name WRITE setName )
61 : : Q_PROPERTY( QString alias READ alias WRITE setAlias )
62 : : Q_PROPERTY( QgsDefaultValue defaultValueDefinition READ defaultValueDefinition WRITE setDefaultValueDefinition )
63 : : Q_PROPERTY( QgsFieldConstraints constraints READ constraints WRITE setConstraints )
64 : : Q_PROPERTY( ConfigurationFlags configurationFlags READ configurationFlags WRITE setConfigurationFlags )
65 : : Q_PROPERTY( bool isReadOnly READ isReadOnly WRITE setReadOnly )
66 : :
67 : :
68 : : public:
69 : :
70 : : #ifndef SIP_RUN
71 : :
72 : : /**
73 : : * Configuration flags for fields
74 : : * These flags are meant to be user-configurable
75 : : * and are not describing any information from the data provider.
76 : : * \note Flags are expressed in the negative forms so that default flags is None.
77 : : * \since QGIS 3.16
78 : : */
79 : : enum class ConfigurationFlag : int
80 : : {
81 : : None = 0, //!< No flag is defined
82 : : NotSearchable = 1 << 1, //!< Defines if the field is searchable (used in the locator search for instance)
83 : : HideFromWms = 1 << 2, //!< Fields is available if layer is served as WMS from QGIS server
84 : : HideFromWfs = 1 << 3, //!< Fields is available if layer is served as WFS from QGIS server
85 : : };
86 : 0 : Q_ENUM( ConfigurationFlag )
87 : : Q_DECLARE_FLAGS( ConfigurationFlags, ConfigurationFlag )
88 : 0 : Q_FLAG( ConfigurationFlags )
89 : : #endif
90 : :
91 : : /**
92 : : * Constructor. Constructs a new QgsField object.
93 : : * \param name Field name
94 : : * \param type Field variant type, currently supported: String / Int / Double
95 : : * \param typeName Field type (e.g., char, varchar, text, int, serial, double).
96 : : * Field types are usually unique to the source and are stored exactly
97 : : * as returned from the data store.
98 : : * \param len Field length
99 : : * \param prec Field precision. Usually decimal places but may also be
100 : : * used in conjunction with other fields types (e.g., variable character fields)
101 : : * \param comment Comment for the field
102 : : * \param subType If the field is a collection, its element's type. When
103 : : * all the elements don't need to have the same type, leave
104 : : * this to QVariant::Invalid.
105 : : */
106 : : QgsField( const QString &name = QString(),
107 : : QVariant::Type type = QVariant::Invalid,
108 : : const QString &typeName = QString(),
109 : : int len = 0,
110 : : int prec = 0,
111 : : const QString &comment = QString(),
112 : : QVariant::Type subType = QVariant::Invalid );
113 : :
114 : : /**
115 : : * Copy constructor
116 : : */
117 : : QgsField( const QgsField &other );
118 : :
119 : : /**
120 : : * Assignment operator
121 : : */
122 : : QgsField &operator =( const QgsField &other ) SIP_SKIP;
123 : :
124 : : virtual ~QgsField();
125 : :
126 : : bool operator==( const QgsField &other ) const;
127 : : bool operator!=( const QgsField &other ) const;
128 : :
129 : : /**
130 : : * Returns the name of the field.
131 : : * \see setName()
132 : : * \see displayName()
133 : : */
134 : : QString name() const;
135 : :
136 : : /**
137 : : * Returns the name to use when displaying this field. This will be the
138 : : * field alias if set, otherwise the field name.
139 : : * \see name()
140 : : * \see alias()
141 : : * \since QGIS 3.0
142 : : */
143 : : QString displayName() const;
144 : :
145 : : /**
146 : : * Returns the name to use when displaying this field and adds the alias in parenthesis if it is defined.
147 : : *
148 : : * This will be used when working close to the data structure (i.e. building expressions and queries),
149 : : * when the real field name must be shown but the alias is also useful to understand what the field
150 : : * represents.
151 : : *
152 : : * \see name()
153 : : * \see alias()
154 : : * \since QGIS 3.12
155 : : */
156 : : QString displayNameWithAlias() const;
157 : :
158 : :
159 : : /**
160 : : * Returns the type to use when displaying this field, including the length and precision of the datatype if applicable.
161 : : *
162 : : * This will be used when the full datatype with details has to displayed to the user.
163 : : *
164 : : * \see type()
165 : : * \since QGIS 3.14
166 : : */
167 : : QString displayType( bool showConstraints = false ) const;
168 : :
169 : : //! Gets variant type of the field as it will be retrieved from data source
170 : : QVariant::Type type() const;
171 : :
172 : : /**
173 : : * If the field is a collection, gets its element's type.
174 : : * When all the elements don't need to have the same type, this returns
175 : : * QVariant::Invalid.
176 : : * \since QGIS 3.0
177 : : */
178 : : QVariant::Type subType() const;
179 : :
180 : : /**
181 : : * Gets the field type. Field types vary depending on the data source. Examples
182 : : * are char, int, double, blob, geometry, etc. The type is stored exactly as
183 : : * the data store reports it, with no attempt to standardize the value.
184 : : * \returns QString containing the field type
185 : : */
186 : : QString typeName() const;
187 : :
188 : : /**
189 : : * Gets the length of the field.
190 : : * \returns int containing the length of the field
191 : : */
192 : : int length() const;
193 : :
194 : : /**
195 : : * Gets the precision of the field. Not all field types have a related precision.
196 : : * \returns int containing the precision or zero if not applicable to the field type.
197 : : */
198 : : int precision() const;
199 : :
200 : : /**
201 : : * Returns the field comment
202 : : */
203 : : QString comment() const;
204 : :
205 : : /**
206 : : * Returns if this field is numeric. Any integer or floating point type
207 : : * will return TRUE for this.
208 : : *
209 : : * \since QGIS 2.18
210 : : */
211 : : bool isNumeric() const;
212 : :
213 : : /**
214 : : * Returns if this field is a date and/or time type.
215 : : *
216 : : * \since QGIS 3.6
217 : : */
218 : : bool isDateOrTime() const;
219 : :
220 : : /**
221 : : * Set the field name.
222 : : * \param name Name of the field
223 : : */
224 : : void setName( const QString &name );
225 : :
226 : : /**
227 : : * Set variant type.
228 : : */
229 : : void setType( QVariant::Type type );
230 : :
231 : : /**
232 : : * If the field is a collection, set its element's type.
233 : : * When all the elements don't need to have the same type, set this to
234 : : * QVariant::Invalid.
235 : : * \since QGIS 3.0
236 : : */
237 : : void setSubType( QVariant::Type subType );
238 : :
239 : : /**
240 : : * Set the field type.
241 : : * \param typeName Field type
242 : : */
243 : : void setTypeName( const QString &typeName );
244 : :
245 : : /**
246 : : * Set the field length.
247 : : * \param len Length of the field
248 : : */
249 : : void setLength( int len );
250 : :
251 : : /**
252 : : * Set the field precision.
253 : : * \param precision Precision of the field
254 : : */
255 : : void setPrecision( int precision );
256 : :
257 : : /**
258 : : * Set the field comment
259 : : */
260 : : void setComment( const QString &comment );
261 : :
262 : : /**
263 : : * Returns the expression used when calculating the default value for the field.
264 : : * \returns expression evaluated when calculating default values for field, or an
265 : : * empty string if no default is set
266 : : * \see setDefaultValueDefinition()
267 : : * \since QGIS 3.0
268 : : */
269 : : QgsDefaultValue defaultValueDefinition() const;
270 : :
271 : : /**
272 : : * Sets an expression to use when calculating the default value for the field.
273 : : * \param defaultValueDefinition expression to evaluate when calculating default values for field. Pass
274 : : * a default constructed QgsDefaultValue() to reset.
275 : : * \see defaultValueDefinition()
276 : : * \since QGIS 3.0
277 : : */
278 : : void setDefaultValueDefinition( const QgsDefaultValue &defaultValueDefinition );
279 : :
280 : : /**
281 : : * Returns constraints which are present for the field.
282 : : * \see setConstraints()
283 : : * \since QGIS 3.0
284 : : */
285 : : const QgsFieldConstraints &constraints() const;
286 : :
287 : : /**
288 : : * Sets constraints which are present for the field.
289 : : * \see constraints()
290 : : * \since QGIS 3.0
291 : : */
292 : : void setConstraints( const QgsFieldConstraints &constraints );
293 : :
294 : : /**
295 : : * Returns the alias for the field (the friendly displayed name of the field ),
296 : : * or an empty string if there is no alias.
297 : : * \see setAlias()
298 : : * \since QGIS 3.0
299 : : */
300 : : QString alias() const;
301 : :
302 : : /**
303 : : * Sets the alias for the field (the friendly displayed name of the field ).
304 : : * \param alias field alias, or empty string to remove an existing alias
305 : : * \see alias()
306 : : * \since QGIS 3.0
307 : : */
308 : : void setAlias( const QString &alias );
309 : :
310 : : /**
311 : : * Returns the Flags for the field (searchable, …)
312 : : * \since QGIS 3.16
313 : : */
314 : : QgsField::ConfigurationFlags configurationFlags() const SIP_SKIP;
315 : :
316 : : /**
317 : : * Sets the Flags for the field (searchable, …)
318 : : * \since QGIS 3.16
319 : : */
320 : : void setConfigurationFlags( QgsField::ConfigurationFlags configurationFlags ) SIP_SKIP;
321 : :
322 : : //! Formats string for display
323 : : QString displayString( const QVariant &v ) const;
324 : :
325 : : /**
326 : : * Returns the reabable and translated value of the configuration flag
327 : : * \since QGIS 3.16
328 : : */
329 : : static QString readableConfigurationFlag( QgsField::ConfigurationFlag flag ) SIP_SKIP;
330 : :
331 : : #ifndef SIP_RUN
332 : :
333 : : /**
334 : : * Converts the provided variant to a compatible format
335 : : *
336 : : * \param v The value to convert
337 : : * \param errorMessage if specified, will be set to a descriptive error when a conversion failure occurs
338 : : *
339 : : * \returns TRUE if the conversion was successful
340 : : */
341 : : bool convertCompatible( QVariant &v, QString *errorMessage = nullptr ) const;
342 : : #else
343 : :
344 : : /**
345 : : * Converts the provided variant to a compatible format
346 : : *
347 : : * \param v The value to convert
348 : : *
349 : : * \returns TRUE if the conversion was successful
350 : : */
351 : : bool convertCompatible( QVariant &v ) const;
352 : : % MethodCode
353 : : PyObject *sipParseErr = NULL;
354 : :
355 : : {
356 : : QVariant *a0;
357 : : int a0State = 0;
358 : : const QgsField *sipCpp;
359 : :
360 : : if ( sipParseArgs( &sipParseErr, sipArgs, "BJ1", &sipSelf, sipType_QgsField, &sipCpp, sipType_QVariant, &a0, &a0State ) )
361 : : {
362 : : bool sipRes;
363 : : QString errorMessage;
364 : :
365 : : Py_BEGIN_ALLOW_THREADS
366 : : try
367 : : {
368 : : sipRes = sipCpp->convertCompatible( *a0, &errorMessage );
369 : : }
370 : : catch ( ... )
371 : : {
372 : : Py_BLOCK_THREADS
373 : :
374 : : sipReleaseType( a0, sipType_QVariant, a0State );
375 : : sipRaiseUnknownException();
376 : : return NULL;
377 : : }
378 : :
379 : : Py_END_ALLOW_THREADS
380 : :
381 : : if ( !sipRes )
382 : : {
383 : : PyErr_SetString( PyExc_ValueError,
384 : : QString( "Value could not be converted to field type %1: %2" ).arg( QMetaType::typeName( sipCpp->type() ), errorMessage ).toUtf8().constData() );
385 : : sipIsErr = 1;
386 : : }
387 : : else
388 : : {
389 : : PyObject *res = sipConvertFromType( a0, sipType_QVariant, NULL );
390 : : sipReleaseType( a0, sipType_QVariant, a0State );
391 : : return res;
392 : : }
393 : : }
394 : : else
395 : : {
396 : : // Raise an exception if the arguments couldn't be parsed.
397 : : sipNoMethod( sipParseErr, sipName_QgsField, sipName_convertCompatible, doc_QgsField_convertCompatible );
398 : :
399 : : return nullptr;
400 : : }
401 : : }
402 : :
403 : : % End
404 : : #endif
405 : :
406 : : //! Allows direct construction of QVariants from fields.
407 : : operator QVariant() const
408 : : {
409 : : return QVariant::fromValue( *this );
410 : : }
411 : :
412 : : /**
413 : : * Set the editor widget setup for the field.
414 : : *
415 : : * \param v The value to set
416 : : */
417 : : void setEditorWidgetSetup( const QgsEditorWidgetSetup &v );
418 : :
419 : : /**
420 : : * Gets the editor widget setup for the field.
421 : : *
422 : : * Defaults may be set by the provider and can be overridden
423 : : * by manual field configuration.
424 : : *
425 : : * \returns the value
426 : : */
427 : : QgsEditorWidgetSetup editorWidgetSetup() const;
428 : :
429 : : /**
430 : : * Make field read-only if \a readOnly is set to true. This is the case for
431 : : * providers which support generated fields for instance.
432 : : * \since QGIS 3.18
433 : : */
434 : : void setReadOnly( bool readOnly );
435 : :
436 : : /**
437 : : * Returns TRUE if this field is a read-only field. This is the case for
438 : : * providers which support generated fields for instance.
439 : : * \since QGIS 3.18
440 : : */
441 : : bool isReadOnly() const;
442 : :
443 : : #ifdef SIP_RUN
444 : : SIP_PYOBJECT __repr__();
445 : : % MethodCode
446 : : QString str = QStringLiteral( "<QgsField: %1 (%2)>" ).arg( sipCpp->name() ).arg( sipCpp->typeName() );
447 : : sipRes = PyUnicode_FromString( str.toUtf8().constData() );
448 : : % End
449 : : #endif
450 : :
451 : : private:
452 : :
453 : : QSharedDataPointer<QgsFieldPrivate> d;
454 : :
455 : :
456 : : }; // class QgsField
457 : :
458 : 0 : Q_DECLARE_METATYPE( QgsField )
459 : :
460 : : Q_DECLARE_OPERATORS_FOR_FLAGS( QgsField::ConfigurationFlags ) SIP_SKIP
461 : :
462 : : //! Writes the field to stream out. QGIS version compatibility is not guaranteed.
463 : : CORE_EXPORT QDataStream &operator<<( QDataStream &out, const QgsField &field );
464 : : //! Reads a field from stream in into field. QGIS version compatibility is not guaranteed.
465 : : CORE_EXPORT QDataStream &operator>>( QDataStream &in, QgsField &field );
466 : :
467 : :
468 : : #endif
|
