/****************************************************************************

**

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

** All rights reserved.

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

**

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

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#include "qlistview.h"

#ifndef QT_NO_LISTVIEW

#include <qabstractitemdelegate.h>

#include <qapplication.h>

#include <qpainter.h>

#include <qbitmap.h>

#include <qvector.h>

#include <qstyle.h>

#include <qevent.h>

#include <qscrollbar.h>

#include <qrubberband.h>

#include <private/qlistview_p.h>

#include <qdebug.h>

#ifndef QT_NO_ACCESSIBILITY

#include <qaccessible.h>

#endif

QT_BEGIN_NAMESPACE

/*!

    \class QListView

    \brief The QListView class provides a list or icon view onto a model.

    \ingroup model-view

    \ingroup advanced

    A QListView presents items stored in a model, either as a simple

    non-hierarchical list, or as a collection of icons. This class is used

    to provide lists and icon views that were previously provided by the

    \c QListBox and \c QIconView classes, but using the more flexible

    approach provided by Qt's model/view architecture.

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

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

    This view does not display horizontal or vertical headers; to display

    a list of items with a horizontal header, use QTreeView instead.

    QListView implements the interfaces defined by the

    QAbstractItemView class to allow it to display data provided by

    models derived from the QAbstractItemModel class.

    Items in a list view can be displayed using one of two view modes:

    In \l ListMode, the items are displayed in the form of a simple list;

    in \l IconMode, the list view takes the form of an \e{icon view} in

    which the items are displayed with icons like files in a file manager.

    By default, the list view is in \l ListMode. To change the view mode,

    use the setViewMode() function, and to determine the current view mode,

    use viewMode().

    Items in these views are laid out in the direction specified by the

    flow() of the list view. The items may be fixed in place, or allowed

    to move, depending on the view's movement() state.

    If the items in the model cannot be completely laid out in the

    direction of flow, they can be wrapped at the boundary of the view

    widget; this depends on isWrapping(). This property is useful when the

    items are being represented by an icon view.

    The resizeMode() and layoutMode() govern how and when the items are

    laid out. Items are spaced according to their spacing(), and can exist

    within a notional grid of size specified by gridSize(). The items can

    be rendered as large or small icons depending on their iconSize().

    \table 100%

    \row \o \inlineimage windowsxp-listview.png Screenshot of a Windows XP style list view

         \o \inlineimage macintosh-listview.png Screenshot of a Macintosh style table view

         \o \inlineimage plastique-listview.png Screenshot of a Plastique style table view

    \row \o A \l{Windows XP Style Widget Gallery}{Windows XP style} list view.

         \o A \l{Macintosh Style Widget Gallery}{Macintosh style} list view.

         \o A \l{Plastique Style Widget Gallery}{Plastique style} list view.

    \endtable

    \section1 Improving Performance

    It is possible to give the view hints about the data it is handling in order

    to improve its performance when displaying large numbers of items. One approach

    that can be taken for views that are intended to display items with equal sizes

    is to set the \l uniformItemSizes property to true.

    \sa {View Classes}, QTreeView, QTableView, QListWidget

*/

/*!

    \enum QListView::ViewMode

    \value ListMode The items are laid out using TopToBottom flow, with Small size and Static movement

    \value IconMode The items are laid out using LeftToRight flow, with Large size and Free movement

*/

/*!

  \enum QListView::Movement

  \value Static The items cannot be moved by the user.

  \value Free The items can be moved freely by the user.

  \value Snap The items snap to the specified grid when moved; see

  setGridSize().

*/

/*!

  \enum QListView::Flow

  \value LeftToRight The items are laid out in the view from the left

  to the right.

  \value TopToBottom The items are laid out in the view from the top

  to the bottom.

*/

/*!

  \enum QListView::ResizeMode

  \value Fixed The items will only be laid out the first time the view is shown.

  \value Adjust The items will be laid out every time the view is resized.

*/

/*!

  \enum QListView::LayoutMode

  \value SinglePass The items are laid out all at once.

  \value Batched The items are laid out in batches of \l batchSize items.

  \sa batchSize

*/

/*!

  \since 4.2

  \fn void QListView::indexesMoved(const QModelIndexList &indexes)

  This signal is emitted when the specified \a indexes are moved in the view.

*/

/*!

    Creates a new QListView with the given \a parent to view a model.

    Use setModel() to set the model.

*/

QListView::QListView(QWidget *parent)

    : QAbstractItemView(*new QListViewPrivate, parent)

{

    setViewMode(ListMode);

    setSelectionMode(SingleSelection);

    setAttribute(Qt::WA_MacShowFocusRect);

    Q_D(QListView);               // We rely on a qobject_cast for PM_DefaultFrameWidth to change

    d->updateStyledFrameWidths(); // hence we have to force an update now that the object has been constructed

}

/*!

  \internal

*/

QListView::QListView(QListViewPrivate &dd, QWidget *parent)

    : QAbstractItemView(dd, parent)

{

    setViewMode(ListMode);

    setSelectionMode(SingleSelection);

    setAttribute(Qt::WA_MacShowFocusRect);

    Q_D(QListView);               // We rely on a qobject_cast for PM_DefaultFrameWidth to change

    d->updateStyledFrameWidths(); // hence we have to force an update now that the object has been constructed

}

/*!

  Destroys the view.

*/

QListView::~QListView()

{

}

/*!

    \property QListView::movement

    \brief whether the items can be moved freely, are snapped to a

    grid, or cannot be moved at all.

    This property determines how the user can move the items in the

    view. \l Static means that the items can't be moved the user. \l

    Free means that the user can drag and drop the items to any

    position in the view. \l Snap means that the user can drag and

    drop the items, but only to the positions in a notional grid

    signified by the gridSize property.

    Setting this property when the view is visible will cause the

    items to be laid out again.

    By default, this property is set to \l Static.

    \sa gridSize, resizeMode, viewMode

*/

void QListView::setMovement(Movement movement)

{

    Q_D(QListView);

    d->modeProperties |= uint(QListViewPrivate::Movement);

    d->movement = movement;

#ifndef QT_NO_DRAGANDDROP

    bool movable = (movement != Static);

    setDragEnabled(movable);

    d->viewport->setAcceptDrops(movable);

#endif

    d->doDelayedItemsLayout();

}

QListView::Movement QListView::movement() const

{

    Q_D(const QListView);

    return d->movement;

}

/*!

    \property QListView::flow

    \brief which direction the items layout should flow.

    If this property is \l LeftToRight, the items will be laid out left

    to right. If the \l isWrapping property is true, the layout will wrap

    when it reaches the right side of the visible area. If this

    property is \l TopToBottom, the items will be laid out from the top

    of the visible area, wrapping when it reaches the bottom.

    Setting this property when the view is visible will cause the

    items to be laid out again.

    By default, this property is set to \l TopToBottom.

    \sa viewMode

*/

void QListView::setFlow(Flow flow)

{

    Q_D(QListView);

    d->modeProperties |= uint(QListViewPrivate::Flow);

    d->flow = flow;

    d->doDelayedItemsLayout();

}

QListView::Flow QListView::flow() const

{

    Q_D(const QListView);

    return d->flow;

}

/*!

    \property QListView::isWrapping

    \brief whether the items layout should wrap.

    This property holds whether the layout should wrap when there is

    no more space in the visible area. The point at which the layout wraps

    depends on the \l flow property.

    Setting this property when the view is visible will cause the

    items to be laid out again.

    By default, this property is false.

    \sa viewMode

*/

void QListView::setWrapping(bool enable)

{

    Q_D(QListView);

    d->modeProperties |= uint(QListViewPrivate::Wrap);

    d->setWrapping(enable);

    d->doDelayedItemsLayout();

}

bool QListView::isWrapping() const

{

    Q_D(const QListView);

    return d->isWrapping();

}

/*!

    \property QListView::resizeMode

    \brief whether the items are laid out again when the view is resized.

    If this property is \l Adjust, the items will be laid out again

    when the view is resized. If the value is \l Fixed, the items will

    not be laid out when the view is resized.

    By default, this property is set to \l Fixed.

    \sa movement, gridSize, viewMode

*/

void QListView::setResizeMode(ResizeMode mode)

{

    Q_D(QListView);

    d->modeProperties |= uint(QListViewPrivate::ResizeMode);

    d->resizeMode = mode;

}

QListView::ResizeMode QListView::resizeMode() const

{

    Q_D(const QListView);

    return d->resizeMode;

}

/*!

    \property QListView::layoutMode

    \brief determines whether the layout of items should happen immediately or be delayed.

    This property holds the layout mode for the items. When the mode

    is \l SinglePass (the default), the items are laid out all in one go.

    When the mode is \l Batched, the items are laid out in batches of \l batchSize

    items, while processing events. This makes it possible to

    instantly view and interact with the visible items while the rest

    are being laid out.

    \sa viewMode

*/

void QListView::setLayoutMode(LayoutMode mode)

{

    Q_D(QListView);

    d->layoutMode = mode;

}

QListView::LayoutMode QListView::layoutMode() const

{

    Q_D(const QListView);

    return d->layoutMode;

}

/*!

    \property QListView::spacing

    \brief the space between items in the layout

    This property is the size of the empty space that is padded around

    an item in the layout.

    Setting this property when the view is visible will cause the

    items to be laid out again.

    By default, this property contains a value of 0.

    \sa viewMode

*/

// ### Qt5: Use same semantic as layouts (spacing is the size of space

// *between* items)

void QListView::setSpacing(int space)

{

    Q_D(QListView);

    d->modeProperties |= uint(QListViewPrivate::Spacing);

    d->setSpacing(space);

    d->doDelayedItemsLayout();

}

int QListView::spacing() const

{

    Q_D(const QListView);

    return d->spacing();

}

/*!

    \property QListView::batchSize

    \brief the number of items laid out in each batch if \l layoutMode is

    set to \l Batched

    The default value is 100.

    \since 4.2

*/

void QListView::setBatchSize(int batchSize)

{

    Q_D(QListView);

    if (batchSize <= 0) {

        qWarning("Invalid batchSize (%d)", batchSize);

        return;

    }

    d->batchSize = batchSize;

}

int QListView::batchSize() const

{

    Q_D(const QListView);

    return d->batchSize;

}

/*!

    \property QListView::gridSize

    \brief the size of the layout grid

    This property is the size of the grid in which the items are laid

    out. The default is an empty size which means that there is no

    grid and the layout is not done in a grid. Setting this property

    to a non-empty size switches on the grid layout. (When a grid

    layout is in force the \l spacing property is ignored.)

    Setting this property when the view is visible will cause the

    items to be laid out again.

    \sa viewMode

*/

void QListView::setGridSize(const QSize &size)

{

    Q_D(QListView);

    d->modeProperties |= uint(QListViewPrivate::GridSize);

    d->setGridSize(size);

    d->doDelayedItemsLayout();

}

QSize QListView::gridSize() const

{

    Q_D(const QListView);

    return d->gridSize();

}

/*!

    \property QListView::viewMode

    \brief the view mode of the QListView.

    This property will change the other unset properties to conform

    with the set view mode. QListView-specific properties that have already been set

    will not be changed, unless clearPropertyFlags() has been called.

    Setting the view mode will enable or disable drag and drop based on the

    selected movement. For ListMode, the default movement is \l Static

    (drag and drop disabled); for IconMode, the default movement is

    \l Free (drag and drop enabled).

    \sa isWrapping, spacing, gridSize, flow, movement, resizeMode

*/

void QListView::setViewMode(ViewMode mode)

{

    Q_D(QListView);

    if (d->commonListView && d->viewMode == mode)

        return;

    d->viewMode = mode;

    delete d->commonListView;

    if (mode == ListMode) {

        d->commonListView = new QListModeViewBase(this, d);

        if (!(d->modeProperties & QListViewPrivate::Wrap))

            d->setWrapping(false);

        if (!(d->modeProperties & QListViewPrivate::Spacing))

            d->setSpacing(0);

        if (!(d->modeProperties & QListViewPrivate::GridSize))

            d->setGridSize(QSize());

        if (!(d->modeProperties & QListViewPrivate::Flow))

            d->flow = TopToBottom;

        if (!(d->modeProperties & QListViewPrivate::Movement))

            d->movement = Static;

        if (!(d->modeProperties & QListViewPrivate::ResizeMode))

            d->resizeMode = Fixed;

        if (!(d->modeProperties & QListViewPrivate::SelectionRectVisible))

            d->showElasticBand = false;

    } else {

        d->commonListView = new QIconModeViewBase(this, d);

        if (!(d->modeProperties & QListViewPrivate::Wrap))

            d->setWrapping(true);

        if (!(d->modeProperties & QListViewPrivate::Spacing))

            d->setSpacing(0);

        if (!(d->modeProperties & QListViewPrivate::GridSize))

            d->setGridSize(QSize());

        if (!(d->modeProperties & QListViewPrivate::Flow))

            d->flow = LeftToRight;

        if (!(d->modeProperties & QListViewPrivate::Movement))

            d->movement = Free;

        if (!(d->modeProperties & QListViewPrivate::ResizeMode))

            d->resizeMode = Fixed;

        if (!(d->modeProperties & QListViewPrivate::SelectionRectVisible))

            d->showElasticBand = true;

    }

#ifndef QT_NO_DRAGANDDROP

    bool movable = (d->movement != Static);

    setDragEnabled(movable);

    setAcceptDrops(movable);

#endif

    d->clear();

    d->doDelayedItemsLayout();

}

QListView::ViewMode QListView::viewMode() const

{

    Q_D(const QListView);

    return d->viewMode;

}

/*!

    Clears the QListView-specific property flags. See \l{viewMode}.

    Properties inherited from QAbstractItemView are not covered by the

    property flags. Specifically, \l{QAbstractItemView::dragEnabled}

    {dragEnabled} and \l{QAbstractItemView::acceptDrops}

    {acceptsDrops} are computed by QListView when calling

    setMovement() or setViewMode().

*/

void QListView::clearPropertyFlags()

{

    Q_D(QListView);

    d->modeProperties = 0;

}