Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# QSqlField Class Reference

The QSqlField class manipulates the fields in SQL database tables and views. More...

    #include <QSqlField>

- List of all members, including inherited members
- Compatibility members

### Public Types

- enum State { Unknown, No, Yes }

### Public Functions

- QSqlField ( const QString & fieldName = QString(), QCoreVariant::Type type = QCoreVariant::Invalid )
- QSqlField ( const QSqlField & other )
- ~QSqlField ()
- void clear ()
- QCoreVariant defaultValue () const
- State isAutoGenerated () const
- bool isNull () const
- bool isReadOnly () const
- State isRequired () const
- bool isValid () const
- int length () const
- QString name () const
- int precision () const
- void setAutoGenerated ( State autogen )
- void setAutoGenerated ( bool autogen )
- void setDefaultValue ( const QCoreVariant & value )
- void setLength ( int fieldLength )
- void setName ( const QString & name )
- void setPrecision ( int precision )
- void setReadOnly ( bool readOnly )
- void setRequired ( State required )
- void setRequired ( bool required )
- void setType ( QCoreVariant::Type type )
- void setValue ( const QCoreVariant & value )
- QCoreVariant::Type type () const
- QCoreVariant value () const
- QSqlField & operator= ( const QSqlField & other )
- bool operator== ( const QSqlField & other ) const

## Detailed Description

The QSqlField class manipulates the fields in SQL database tables and views.

QSqlField represents the characteristics of a single column in a database table or view, such as the data type and column name. A field also contains the value of the database column, which can be viewed or changed.

Field data values are stored as QCoreVariants. Using an incompatible type is not permitted. For example:

        QSqlField field("myfield", QCoreVariant::Int);
        field.setValue(QPixmap());  // will not work

However, the field will attempt to cast certain data types to the field data type where possible:

        QSqlField field("myfield", QCoreVariant::Int);
        field.setValue(QString("123")); // casts QString to int

QSqlField objects are rarely created explicitly in application code. They are usually accessed indirectly through QSqlRecord or QSqlCursor which already contain a list of fields. For example:

        QSqlCursor cur("EMPLOYEE");           // create a cursor for the 'EMPLOYEE' table
        QSqlField *field = cur.field("NAME"); // use the 'NAME' field
        field->setValue("Dave");              // set the field's value
        ...

In practice we rarely need to extract a pointer to a field at all. The previous example would normally be written:

        QSqlCursor cur("EMPLOYEE");
        cur.setValue("NAME", "Dave");
        ...

A QSqlField object can provide some meta-data about the field, for example, its name(), variant type(), length(), precision(), defaultValue(), typeID(), and whether it isRequired(), isAutoGenerated() and isReadOnly(). The field's data can be checked to see if it isNull(), and its value() retrieved. When editing the data can be set with setValue() or set to NULL with clear().

## Member Type Documentation

### enum QSqlField::State

Used to specify the auto-generated state and the required state.

`QSqlField::Unknown` |
`QSqlField::No` |
`QSqlField::Yes` |

## Member Function Documentation

### QSqlField::QSqlField ( const QString & fieldName = QString(), QCoreVariant::Type type = QCoreVariant::Invalid )

Constructs an empty field called fieldName of variant type type.

See also setRequired(), setLength(), setPrecision(), setDefaultValue(), setAutoGenerated(), and setReadOnly().

### QSqlField::QSqlField ( const QSqlField & other )

Constructs a copy of other.

### QSqlField::~QSqlField ()

Destroys the object and frees any allocated resources.

### void QSqlField::clear ()

Clears the value of the field and sets it to NULL. If the field is read-only, nothing happens.

See also setValue(), isReadOnly(), and isRequired().

### QCoreVariant QSqlField::defaultValue () const

Returns the field's default value (which may be NULL).

See also setDefaultValue(), type(), isRequired(), length(), precision(), and isAutoGenerated().

### State QSqlField::isAutoGenerated () const

Returns true if the field is auto-generated; otherwise returns false.

See also setAutoGenerated(), type(), isRequired(), length(), precision(), and defaultValue().

### bool QSqlField::isNull () const

Returns true if the field's value is NULL; otherwise returns false.

See also value().

### bool QSqlField::isReadOnly () const

Returns true if the field's value is read-only; otherwise returns false.

See also setReadOnly(), type(), isRequired(), length(), precision(), defaultValue(), and isAutoGenerated().

### State QSqlField::isRequired () const

Returns true if this is a required field; otherwise returns false. An `INSERT` will fail if a required field does not have a value.

See also setRequired(), type(), length(), precision(), defaultValue(), and isAutoGenerated().

### bool QSqlField::isValid () const

Returns true if the field's variant type is valid; otherwise returns false.

### int QSqlField::length () const

Returns the field's length.

See also setLength(), type(), isRequired(), precision(), defaultValue(), and isAutoGenerated().

### QString QSqlField::name () const

Returns the name of the field.

See also setName().

### int QSqlField::precision () const

Returns the field's precision; this is only meaningful for numeric types.

See also setPrecision(), type(), isRequired(), length(), defaultValue(), and isAutoGenerated().

### void QSqlField::setAutoGenerated ( State autogen )

Sets the auto-generated state. If autogen is `Yes` then SQL for this field will be generated for SQL queries; otherwise no SQL will be generated for this field.

See also isAutoGenerated(), setType(), setRequired(), setLength(), setPrecision(), setDefaultValue(), and setReadOnly().

### void QSqlField::setAutoGenerated ( bool autogen )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

If autogen is true the auto-generated state is set to `Yes`; otherwise it is set to `No`.

### void QSqlField::setDefaultValue ( const QCoreVariant & value )

Sets the default value used for this field to value.

See also defaultValue(), value(), setType(), setRequired(), setLength(), setPrecision(), setAutoGenerated(), and setReadOnly().

### void QSqlField::setLength ( int fieldLength )

Sets the field's length to fieldLength. For strings this is the maximum number of characters the string can hold; the meaning varies for other types.

See also length(), setType(), setRequired(), setPrecision(), setDefaultValue(), setAutoGenerated(), and setReadOnly().

### void QSqlField::setName ( const QString & name )

Sets the name of the field to name.

See also name().

### void QSqlField::setPrecision ( int precision )

Sets the field's precision. This only affects numeric fields.

See also precision(), setType(), setRequired(), setLength(), setDefaultValue(), setAutoGenerated(), and setReadOnly().

### void QSqlField::setReadOnly ( bool readOnly )

Sets the read only flag of the field's value to readOnly. A read-only field cannot have its value set with setValue() and cannot be cleared to NULL with clear().

### void QSqlField::setRequired ( State required )

If required is `Yes`, this is a required field that must be given a non-NULL value; otherwise the field can have any value, including NULL.

See also isRequired(), setType(), setLength(), setPrecision(), setDefaultValue(), setAutoGenerated(), and setReadOnly().

### void QSqlField::setRequired ( bool required )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

If required is true the required state is set to `Yes`; otherwise it is set to `No`.

### void QSqlField::setType ( QCoreVariant::Type type )

Set's the field's variant type to type.

See also type(), setRequired(), setLength(), setPrecision(), setDefaultValue(), setAutoGenerated(), and setReadOnly().

### void QSqlField::setValue ( const QCoreVariant & value )

Sets the value of the field to value. If the field is read-only (isReadOnly() returns true), nothing happens. If the data type of value differs from the field's current data type, an attempt is made to cast it to the proper type. This preserves the data type of the field in the case of assignment, e.g. a QString to an integer data type. For example:

        QSqlCursor cur("EMPLOYEE");                    // 'EMPLOYEE' table
        QSqlField *field = cur.field("STUDENT_COUNT"); // an integer field
        ...
        field->setValue(myLineEdit->text());           // cast the line edit text to an integer

To set the value to NULL use clear().

See also value(), isReadOnly(), and defaultValue().

### QCoreVariant::Type QSqlField::type () const

Returns the field's variant type.

See also setType().

### QCoreVariant QSqlField::value () const

Returns the value of the field as a QCoreVariant.

Use isNull() to check if the field's value is NULL.

### QSqlField & QSqlField::operator= ( const QSqlField & other )

Sets the field equal to other.

### bool QSqlField::operator== ( const QSqlField & other ) const

Returns true if the field is equal to other; otherwise returns false.