source: trunk/doc/src/q3sqlfieldinfo.qdoc@ 432

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at qt-sales@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \class Q3SqlFieldInfo
    \brief The Q3SqlFieldInfo class stores meta data associated with a SQL field.

    \compat

    Q3SqlFieldInfo objects only store meta data; field values are
    stored in QSqlField objects.

    All values must be set in the constructor, and may be retrieved
    using isRequired(), type(), length(), precision(), defaultValue(),
    name(), isGenerated() and typeID().

    \sa Q3SqlRecordInfo
*/

/*!
    \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QString& name,
                                       QVariant::Type typ,
                                       int required,
                                       int len,
                                       int prec,
                                       const QVariant& defValue,
                                       int typeID,
                                       bool generated,
                                       bool trim,
                                       bool calculated)

    Constructs a Q3SqlFieldInfo with the following parameters:
    \table
    \row \i \a name  \i the name of the field.
    \row \i \a typ   \i the field's type in a QVariant.
    \row \i \a required  \i greater than 0 if the field is required, 0
    if its value can be NULL and less than 0 if it cannot be
    determined whether the field is required or not.
    \row \i \a len  \i the length of the field. Note that for
    non-character types some databases return either the length in
    bytes or the number of digits. -1 signifies that the length cannot
    be determined.
    \row \i \a prec  \i the precision of the field, or -1 if the field
    has no precision or it cannot be determined.
    \row \i \a defValue  \i the default value that is inserted into
    the table if none is specified by the user. QVariant() if there is
    no default value or it cannot be determined.
    \row \i \a typeID  \i the internal typeID of the database system
    (only useful for low-level programming). 0 if unknown.
    \row \i \a generated  \i TRUE indicates that this field should be
    included in auto-generated SQL statments, e.g. in Q3SqlCursor.
    \row \i \a trim  \i TRUE indicates that widgets should remove
    trailing whitespace from character fields. This does not affect
    the field value but only its representation inside widgets.
    \row \i \a calculated  \i TRUE indicates that the value of this
    field is calculated. The value of calculated fields can by
    modified by subclassing Q3SqlCursor and overriding
    Q3SqlCursor::calculateField().
    \endtable
*/

/*!
    \fn Q3SqlFieldInfo::~Q3SqlFieldInfo()

    Destroys the object and frees any allocated resources.
*/

/*!
    \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QSqlField & other)

    Creates a Q3SqlFieldInfo object with the type and the name of the
    QSqlField \a other.
*/

/*!
    \fn bool Q3SqlFieldInfo::operator==(const Q3SqlFieldInfo& other) const

    Assigns \a other to this field info and returns a reference to it.
*/

/*!
    \fn QSqlField Q3SqlFieldInfo::toField() const

    Returns an empty QSqlField based on the information in this
    Q3SqlFieldInfo.
*/

/*!
    \fn int Q3SqlFieldInfo::isRequired() const

    Returns a value greater than 0 if the field is required (NULL
    values are not allowed), 0 if it isn't required (NULL values are
    allowed) or less than 0 if it cannot be determined whether the
    field is required or not.
*/

/*!
    \fn QVariant::Type Q3SqlFieldInfo::type() const

    Returns the field's type or QVariant::Invalid if the type is
    unknown.
*/

/*!
    \fn int Q3SqlFieldInfo::length() const

    Returns the field's length. For fields storing text the return
    value is the maximum number of characters the field can hold. For
    non-character fields some database systems return the number of
    bytes needed or the number of digits allowed. If the length cannot
    be determined -1 is returned.
*/

/*!
    \fn int Q3SqlFieldInfo::precision() const

    Returns the field's precision or -1 if the field has no precision
    or it cannot be determined.
*/

/*!
    \fn QVariant Q3SqlFieldInfo::defaultValue() const

    Returns the field's default value or an empty QVariant if the
    field has no default value or the value couldn't be determined.
    The default value is the value inserted in the database when it
    is not explicitly specified by the user.
*/

/*!
    \fn QString Q3SqlFieldInfo::name() const

    Returns the name of the field in the SQL table.
*/

/*!
    \fn int Q3SqlFieldInfo::typeID() const

    Returns the internal type identifier as returned from the database
    system. The return value is 0 if the type is unknown.
*/

/*!
    \fn bool Q3SqlFieldInfo::isGenerated() const

    Returns TRUE if the field should be included in auto-generated
    SQL statments, e.g. in Q3SqlCursor; otherwise returns FALSE.

    \sa setGenerated()
*/

/*!
    \fn bool Q3SqlFieldInfo::isTrim() const

    Returns TRUE if trailing whitespace should be removed from
    character fields; otherwise returns FALSE.

    \sa setTrim()
*/

/*!
    \fn bool Q3SqlFieldInfo::isCalculated() const

    Returns TRUE if the field is calculated; otherwise returns FALSE.

    \sa setCalculated()
*/

/*!
    \fn void Q3SqlFieldInfo::setTrim(bool trim)

    If \a trim is TRUE widgets should remove trailing whitespace from
    character fields. This does not affect the field value but only
    its representation inside widgets.

    \sa isTrim()
*/

/*!
    \fn void Q3SqlFieldInfo::setGenerated(bool generated)

    \a generated set to FALSE indicates that this field should not appear
    in auto-generated SQL statements (for example in Q3SqlCursor).

    \sa isGenerated()
*/

/*!
    \fn void Q3SqlFieldInfo::setCalculated(bool calculated)

    \a calculated set to TRUE indicates that this field is a calculated
    field. The value of calculated fields can by modified by subclassing
    Q3SqlCursor and overriding Q3SqlCursor::calculateField().

    \sa isCalculated()
*/