1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qabstractitemdelegate.h"

    43 

    44 #ifndef QT_NO_ITEMVIEWS

    45 #include <qabstractitemmodel.h>

    46 #include <qabstractitemview.h>

    47 #include <qfontmetrics.h>

    48 #include <qwhatsthis.h>

    49 #include <qtooltip.h>

    50 #include <qevent.h>

    51 #include <qstring.h>

    52 #include <qdebug.h>

    53 #include <private/qtextengine_p.h>

    54 

    55 QT_BEGIN_NAMESPACE

    56 

    57 /*!

    58     \class QAbstractItemDelegate

    59 

    60     \brief The QAbstractItemDelegate class is used to display and edit

    61     data items from a model.

    62 

    63     \ingroup model-view

    64 

    65 

    66     A QAbstractItemDelegate provides the interface and common functionality

    67     for delegates in the model/view architecture. Delegates display

    68     individual items in views, and handle the editing of model data.

    69 

    70     The QAbstractItemDelegate class is one of the \l{Model/View Classes}

    71     and is part of Qt's \l{Model/View Programming}{model/view framework}.

    72 

    73     To render an item in a custom way, you must implement paint() and

    74     sizeHint(). The QItemDelegate class provides default implementations for

    75     these functions; if you do not need custom rendering, subclass that

    76     class instead.

    77 

    78     We give an example of drawing a progress bar in items; in our case

    79     for a package management program.

    80 

    81     \image widgetdelegate.png

    82 

    83     We create the \c WidgetDelegate class, which inherits from

    84     QStyledItemDelegate. We do the drawing in the paint() function:

    85 

    86     \snippet doc/src/snippets/widgetdelegate.cpp 0

    87 

    88     Notice that we use a QStyleOptionProgressBar and initialize its

    89     members. We can then use the current QStyle to draw it.

    90 

    91     To provide custom editing, there are two approaches that can be

    92     used. The first approach is to create an editor widget and display

    93     it directly on top of the item. To do this you must reimplement

    94     createEditor() to provide an editor widget, setEditorData() to populate

    95     the editor with the data from the model, and setModelData() so that the

    96     delegate can update the model with data from the editor.

    97 

    98     The second approach is to handle user events directly by reimplementing

    99     editorEvent().

   100 

   101     \sa {model-view-programming}{Model/View Programming}, QItemDelegate,

   102         {Pixelator Example}, QStyledItemDelegate, QStyle

   103 */

   104 

   105 /*!

   106     \enum QAbstractItemDelegate::EndEditHint

   107 

   108     This enum describes the different hints that the delegate can give to the

   109     model and view components to make editing data in a model a comfortable

   110     experience for the user.

   111 

   112     \value NoHint           There is no recommended action to be performed.

   113 

   114     These hints let the delegate influence the behavior of the view:

   115 

   116     \value EditNextItem     The view should use the delegate to open an

   117                             editor on the next item in the view.

   118     \value EditPreviousItem The view should use the delegate to open an

   119                             editor on the previous item in the view.

   120 

   121     Note that custom views may interpret the concepts of next and previous

   122     differently.

   123 

   124     The following hints are most useful when models are used that cache

   125     data, such as those that manipulate data locally in order to increase

   126     performance or conserve network bandwidth.

   127 

   128     \value SubmitModelCache If the model caches data, it should write out

   129                             cached data to the underlying data store.

   130     \value RevertModelCache If the model caches data, it should discard

   131                             cached data and replace it with data from the

   132                             underlying data store.

   133 

   134     Although models and views should respond to these hints in appropriate

   135     ways, custom components may ignore any or all of them if they are not

   136     relevant.

   137 */

   138 

   139 /*!

   140   \fn void QAbstractItemDelegate::commitData(QWidget *editor)

   141 

   142   This signal must be emitted when the \a editor widget has completed

   143   editing the data, and wants to write it back into the model.

   144 */

   145 

   146 /*!

   147     \fn void QAbstractItemDelegate::closeEditor(QWidget *editor, QAbstractItemDelegate::EndEditHint hint)

   148 

   149     This signal is emitted when the user has finished editing an item using

   150     the specified \a editor.

   151 

   152     The \a hint provides a way for the delegate to influence how the model and

   153     view behave after editing is completed. It indicates to these components

   154     what action should be performed next to provide a comfortable editing

   155     experience for the user. For example, if \c EditNextItem is specified,

   156     the view should use a delegate to open an editor on the next item in the

   157     model.

   158 

   159     \sa EndEditHint

   160 */

   161 

   162 /*!

   163     \fn void QAbstractItemDelegate::sizeHintChanged(const QModelIndex &index)

   164     \since 4.4

   165 

   166     This signal must be emitted when the sizeHint() of \a index changed.

   167 

   168     Views automatically connect to this signal and relayout items as necessary.

   169 */

   170 

   171 

   172 /*!

   173     Creates a new abstract item delegate with the given \a parent.

   174 */

   175 QAbstractItemDelegate::QAbstractItemDelegate(QObject *parent)

   176     : QObject(parent)

   177 {

   178 

   179 }

   180 

   181 /*!

   182     \internal

   183 

   184     Creates a new abstract item delegate with the given \a parent.

   185 */

   186 QAbstractItemDelegate::QAbstractItemDelegate(QObjectPrivate &dd, QObject *parent)

   187     : QObject(dd, parent)

   188 {

   189 

   190 }

   191 

   192 /*!

   193     Destroys the abstract item delegate.

   194 */

   195 QAbstractItemDelegate::~QAbstractItemDelegate()

   196 {

   197 

   198 }

   199 

   200 /*!

   201     \fn void QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const = 0;

   202 

   203     This pure abstract function must be reimplemented if you want to

   204     provide custom rendering. Use the \a painter and style \a option to

   205     render the item specified by the item \a index.

   206 

   207     If you reimplement this you must also reimplement sizeHint().

   208 */

   209 

   210 /*!

   211     \fn QSize QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const = 0

   212 

   213     This pure abstract function must be reimplemented if you want to

   214     provide custom rendering. The options are specified by \a option

   215     and the model item by \a index.

   216 

   217     If you reimplement this you must also reimplement paint().

   218 */

   219 

   220 /*!

   221     Returns the editor to be used for editing the data item with the

   222     given \a index. Note that the index contains information about the

   223     model being used. The editor's parent widget is specified by \a parent,

   224     and the item options by \a option.

   225 

   226     The base implementation returns 0. If you want custom editing you

   227     will need to reimplement this function.

   228 

   229     The returned editor widget should have Qt::StrongFocus;

   230     otherwise, \l{QMouseEvent}s received by the widget will propagate

   231     to the view. The view's background will shine through unless the

   232     editor paints its own background (e.g., with

   233     \l{QWidget::}{setAutoFillBackground()}).

   234 

   235     \sa setModelData() setEditorData()

   236 */

   237 QWidget *QAbstractItemDelegate::createEditor(QWidget *,

   238                                              const QStyleOptionViewItem &,

   239                                              const QModelIndex &) const

   240 {

   241     return 0;

   242 }

   243 

   244 /*!

   245     Sets the contents of the given \a editor to the data for the item

   246     at the given \a index. Note that the index contains information

   247     about the model being used.

   248 

   249     The base implementation does nothing. If you want custom editing

   250     you will need to reimplement this function.

   251 

   252     \sa setModelData()

   253 */

   254 void QAbstractItemDelegate::setEditorData(QWidget *,

   255                                           const QModelIndex &) const

   256 {

   257     // do nothing

   258 }

   259 

   260 /*!

   261     Sets the data for the item at the given \a index in the \a model

   262     to the contents of the given \a editor.

   263 

   264     The base implementation does nothing. If you want custom editing

   265     you will need to reimplement this function.

   266 

   267     \sa setEditorData()

   268 */

   269 void QAbstractItemDelegate::setModelData(QWidget *,

   270                                          QAbstractItemModel *,

   271                                          const QModelIndex &) const

   272 {

   273     // do nothing

   274 }

   275 

   276 /*!

   277     Updates the geometry of the \a editor for the item with the given

   278     \a index, according to the rectangle specified in the \a option.

   279     If the item has an internal layout, the editor will be laid out

   280     accordingly. Note that the index contains information about the

   281     model being used.

   282 

   283     The base implementation does nothing. If you want custom editing

   284     you must reimplement this function.

   285 */

   286 void QAbstractItemDelegate::updateEditorGeometry(QWidget *,

   287                                                  const QStyleOptionViewItem &,

   288                                                  const QModelIndex &) const

   289 {

   290     // do nothing

   291 }

   292 

   293 /*!

   294     Whenever an event occurs, this function is called with the \a event

   295     \a model \a option and the \a index that corresponds to the item being edited.

   296 

   297     The base implementation returns false (indicating that it has not

   298     handled the event).

   299 */

   300 bool QAbstractItemDelegate::editorEvent(QEvent *,

   301                                         QAbstractItemModel *,

   302                                         const QStyleOptionViewItem &,

   303                                         const QModelIndex &)

   304 {

   305     // do nothing

   306     return false;

   307 }

   308 

   309 /*!

   310     \obsolete

   311 

   312     Use QFontMetrics::elidedText() instead.

   313 

   314     \oldcode

   315         QFontMetrics fm = ...

   316         QString str = QAbstractItemDelegate::elidedText(fm, width, mode, text);

   317     \newcode

   318         QFontMetrics fm = ...

   319         QString str = fm.elidedText(text, mode, width);

   320     \endcode

   321 */

   322 

   323 QString QAbstractItemDelegate::elidedText(const QFontMetrics &fontMetrics, int width,

   324                                           Qt::TextElideMode mode, const QString &text)

   325 {

   326     return fontMetrics.elidedText(text, mode, width);

   327 }

   328 

   329 /*!

   330     \since 4.3

   331     Whenever a help event occurs, this function is called with the \a event

   332     \a view \a option and the \a index that corresponds to the item where the

   333     event occurs.

   334 

   335     Returns true if the delegate can handle the event; otherwise returns false.

   336     A return value of true indicates that the data obtained using the index had

   337     the required role.

   338 

   339     For QEvent::ToolTip and QEvent::WhatsThis events that were handled successfully,

   340     the relevant popup may be shown depending on the user's system configuration.

   341 

   342     \sa QHelpEvent

   343 */

   344 // ### Qt 5: Make this a virtual non-slot function

   345 bool QAbstractItemDelegate::helpEvent(QHelpEvent *event,

   346                                       QAbstractItemView *view,

   347                                       const QStyleOptionViewItem &option,

   348                                       const QModelIndex &index)

   349 {

   350     Q_UNUSED(option);

   351 

   352     if (!event || !view)

   353         return false;

   354     switch (event->type()) {

   355 #ifndef QT_NO_TOOLTIP

   356     case QEvent::ToolTip: {

   357         QHelpEvent *he = static_cast<QHelpEvent*>(event);

   358         QVariant tooltip = index.data(Qt::ToolTipRole);

   359         if (qVariantCanConvert<QString>(tooltip)) {

   360             QToolTip::showText(he->globalPos(), tooltip.toString(), view);

   361             return true;

   362         }

   363         break;}

   364 #endif

   365 #ifndef QT_NO_WHATSTHIS

   366     case QEvent::QueryWhatsThis: {

   367         if (index.data(Qt::WhatsThisRole).isValid())

   368             return true;

   369         break; }

   370     case QEvent::WhatsThis: {

   371         QHelpEvent *he = static_cast<QHelpEvent*>(event);

   372         QVariant whatsthis = index.data(Qt::WhatsThisRole);

   373         if (qVariantCanConvert<QString>(whatsthis)) {

   374             QWhatsThis::showText(he->globalPos(), whatsthis.toString(), view);

   375             return true;

   376         }

   377         break ; }

   378 #endif

   379     default:

   380         break;

   381     }

   382     return false;

   383 }

   384 

   385 QT_END_NAMESPACE

   386 

   387 #endif // QT_NO_ITEMVIEWS