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

**

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

** All rights reserved.

** Contact: Nokia Corporation (developer.feedback@nokia.com)

**

** This file is part of the HbCore module of the UI Extensions for Mobile.

**

** GNU Lesser General Public License Usage

** 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 developer.feedback@nokia.com.

**

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

#include "hbscrollarea.h"

#include "hbscrollarea_p.h"

#include "hbscrollbar.h"

#include "hbdeviceprofile.h"

#include "hbinstance.h"

#include <hbwidgetfeedback.h>

#include <hbevent.h>

#include "hbglobal_p.h"

#include <hbtapgesture.h>

#include <hbnamespace_p.h>

#include <QGesture>

#include <QDebug>

/*!

    @beta

    @hbcore

    \class HbScrollArea

    \brief The HbScrollArea class provides a touch-enabled scrolling view onto another

    widget.

    A scroll area displays the contents of another widget within a frame. If the size of

    this widget exceeds the size of the frame, the user can scroll so that the entire

    contents can be viewed. The user scrolls through the contents by using a dragging

    gesture. If scroll bars are enabled and the scroll bar is interactive, the user can

    also scroll through the contents using the scroll bar (HbScrollBar class).

    %HbScrollArea is a concrete class that you can use directly in your applications to

    provide default scrolling behavior. %HbScrollArea is also a base class for

    HbAbstractItemView and the item view classes that derive from it. If necessary, you

    can subclass %HbScrollArea to add additional features, such as touch and selection

    feedback.

    \image html hbscrollarea.png A scroll area containing a large image and showing scrollbars

    %HbScrollArea provides properties that you can use to customize the following aspects

    of the scroll area:

    - <b>Scrolling style</b>. The user scrolls through the contents by using a dragging

         movement. This property controls what happens when the user releases the pressure.

         The default is that a follow-on animation continues the scrolling if the dragging

         was fast. Alternatively, the scrolling can stop as soon as the user releases the

         pressure, regardless of the dragging speed. Call setScrollingStyle() to set this

         property.

    - <b>Friction effect</b>. This property controls the speed of the follow-on scrolling

         animation. When the friction effect is enabled, it slows the animation and causes

         it to stop more quickly than when the effect is not enabled. Call setFrictionEnabled()

         to set this property.

    - <b>Clamping style</b>. This property controls how scrolling is constrained relative

         to the contents of the scrolling area. Scrolling can be limited to the bounding

         rectangle of the contents or it can go beyond the bounding rectangle and bounce

         back to its limits (this is the default). Call setClampingStyle() to set this

         property.

    - <b>Scroll direction</b>. This property controls the scrolling direction. The default is

         vertical scrolling, but this can be changed to horizontal or bi-directional scrolling.

         Call setScrollDirections() to set this property.

    - <b>Scrollbar policy</b>. There is a separate scrollbar policy property for both scrollbars.

         You can set these so that the scrollbar is always shown, never shown, only shown when

         needed or for short periods (autohide), which is the default behavior. Call

         setVerticalScrollBarPolicy() and setHorizontalScrollBarPolicy() to set these properties.

    - <b>Continuation indicators</b>. This property controls whether visual feedback is provided

         to indicate when scrolling is possible. The default value is false. Call

         setContinuationIndicators() to set this property.

    The contents widget must be an object of a class derived from QGraphicsWidget. After

    constructing this widget, you set it into the scroll area by calling setContentWidget().

    The scroll area uses QGraphicsWidget::sizeHint() to resize the content widget to fit,

    taking into account the scroll direction. For example, when the scrolling direction is

    vertical, the scroll area resizes the contents widget to fit the width of the scroll area.

    \section _usecases_hbscrollarea Using the HbScrollArea class

    This example creates an HbScrollArea widget and sets a large photo as its contents.

    \code

int main(int argc, char *argv[])

{

    HbApplication app(argc, argv);

    app.setApplicationName( "Scroll Area" );

    HbMainWindow window;

    HbView* view = new HbView();

    // Create the scroll area object.

    HbScrollArea* scrollArea = new HbScrollArea();

    // Create the content widget.

    QGraphicsWidget* content = new QGraphicsWidget();

    // Create a pixmap as a child of the content widget.

    QString string(":/gfx/beach.jpg");

    QGraphicsPixmapItem* pixmapItem = new QGraphicsPixmapItem(string, content);

    // Set the preferred size of the content widget to match the full size of the photo.

    content->setPreferredSize(pixmapItem->boundingRect().size());

    // Load the content widget into the scrolling area.

    scrollArea->setContentWidget(content);

    // Set the scroll area to scroll in both directions.

    scrollArea->setScrollDirections(Qt::Vertical | Qt::Horizontal);

    view->setWidget(scrollArea);

    window.addView(view);

    window.show();

    return app.exec();

}

    \endcode

    \sa HbScrollBar

 */

/*!

    \fn void HbScrollArea::scrollDirectionsChanged(Qt::Orientations newValue)

    This signal is emitted when the scrolling direction changes.

*/

/*!

    \fn void HbScrollArea::scrollingStarted()

    This signal is emitted when a scrolling action begins.

*/

/*!

    \fn void HbScrollArea::scrollingEnded()

    This signal is emitted when a scrolling action ends.

*/

/*!

    \fn void HbScrollArea::scrollPositionChanged(const QPointF &newPosition)

    This signal is emitted when the scroll position is changed, but only if this signal

    is connected to a slot.

*/

/*!

    \enum HbScrollArea::ClampingStyle

    Defines the clamping styles supported by HbScrollArea. The clamping style

    controls the behavior when scrolling to the edge of the contents of the scrolling

    area.

    \sa setClampingStyle(), clampingStyle()

*/

/*!

    \var HbScrollArea::StrictClamping

    Scrolling is limited to the bounding rectangle of the contents.

*/

/*!

    \var HbScrollArea::BounceBackClamping

    Scrolling can go beyond the bounding rectangle of the contents, but bounces

    back to the limits of the bounding rectangle when released or when the follow-on

    scrolling animation stops. This is the default clamping style.

*/

/*!

    \var HbScrollArea::NoClamping

    Scrolling is unclamped. Typically you use this only in a subclass that implements

    its own custom clamping behavior.

*/

/*!

    \enum HbScrollArea::ScrollingStyle

    Defines the scrolling styles supported by HbScrollArea. The scrolling style

    controls which gestures the user can use to scroll the contents and how the scrolling

    responds to those gestures.

    \sa setScrollingStyle(), scrollingStyle()

*/

/*!

    \var HbScrollArea::Pan

    The user can scroll through the contents by using a dragging motion. The scrolling

    stops as soon as the user stops the dragging motion.

*/

/*!

    \var HbScrollArea::PanOrFlick

    \deprecated

    The user can scroll through the contents by using a dragging motion and a quick

    flicking motion triggers a follow-on scrolling animation.

*/

/*!

    \var HbScrollArea::PanWithFollowOn

    The user can scroll through the contents by using a dragging motion. In addition

    a fast dragging motion triggers a follow-on scrolling animation when the user

    stops dragging and releases the pressure. This is the default scrolling style.

*/

/*!

    \enum HbScrollArea::ScrollBarPolicy

    Defines the scroll bar visibility modes supported by  HbScrollArea.

    \sa setVerticalScrollBarPolicy(), verticalScrollBarPolicy(),

    setHorizontalScrollBarPolicy(), horizontalScrollBarPolicy()

*/

/*!

    \var HbScrollArea::ScrollBarAsNeeded

    Show the scroll bar only when the contents are too large to fit.

*/

/*!

    \var HbScrollArea::ScrollBarAlwaysOff

    Never show the scroll bar.

*/

/*!

    \var HbScrollArea::ScrollBarAlwaysOn

    Always show the scroll bar.

*/

/*!

    \var HbScrollArea::ScrollBarAutoHide

    Show the scroll bar for a short period when the contents are first displayed or

    when the user scrolls the contents. This is the default behavior.

*/

/*

    \primitives

    \primitives{continuation-indicator-bottom} HbFrameItem representing the scrollarea continuation indicator on the bottom of the scrollarea.

    \primitives{continuation-indicator-top} HbFrameItem representing the scrollarea continuation indicator on the top of the scrollarea.

    \primitives{continuation-indicator-left} HbFrameItem representing the scrollarea continuation indicator on the left side of the scrollarea.

    \primitives{continuation-indicator-right} HbFrameItem representing the scrollarea continuation indicator on the right side of the scrollarea.

  */

/*!

    Constructs an HbScrollArea object with the given \a parent.

 */

HbScrollArea::HbScrollArea(QGraphicsItem* parent) :

        HbWidget( *new HbScrollAreaPrivate, parent )

{

    Q_D( HbScrollArea );

    d->q_ptr = this;

    d->init();

}

/*!

    Protected constructor.

  */

HbScrollArea::HbScrollArea(HbScrollAreaPrivate &dd, QGraphicsItem *parent):

        HbWidget( dd, parent  )

{

    Q_D( HbScrollArea );

    d->q_ptr = this;

    d->init();

}

/*!

    Destructor

 */

HbScrollArea::~HbScrollArea()

{

    Q_D( HbScrollArea );

    if (d && d->mContents) {

        d->mContents->setParentLayoutItem(0);

    }

}

/*!

    Returns a pointer to the widget that is contained within the scroll area

    and that defines the contents to be scrolled.

    \sa setContentWidget()

 */

QGraphicsWidget* HbScrollArea::contentWidget() const

{

    Q_D( const HbScrollArea );

    return d->mContents;

}

/*!

   Assigns a widget (QGraphicsWidget object) to the scroll area. This widget defines

   the contents of the scroll area. The HbScrollArea object takes ownership of the

   contents widget.

   \sa contentWidget()

 */

void HbScrollArea::setContentWidget(QGraphicsWidget* contents)

{

    Q_D( HbScrollArea );

    if ( contents == d->mContents ) {

        return;

    }

    d->stopAnimating();

    if (0 != d->mContents) {

        d->mContents->setParentLayoutItem(0);

        delete d->mContents;

    }

    d->mContents = contents;

    updateGeometry();

    if (0 != contents) {

        contents->setParentLayoutItem(this);

        contents->setParentItem(this);

        contents->installEventFilter(this);

        d->mResetAlignment = true;

        d->adjustContent();

        setContinuationIndicators(d->mContinuationIndicators);

    } else {

        d->hideChildComponents();

    }

}

/*!

    Removes the scroll area's content widget from the scroll area, returns it, and

    transfers ownership of the content widget to the caller. This is useful when you

    need to switch the contents without deleting previous contents.

    \sa setContentWidget()

 */

QGraphicsWidget *HbScrollArea::takeContentWidget()

{

    Q_D(HbScrollArea);

    QGraphicsWidget* content = d->mContents;

    d->mContents = 0;

    // Reset the ownership

    if (content) {

        content->setParentLayoutItem(0);

        content->setParentItem(0);

        content->removeEventFilter(this);

    }

    d->hideChildComponents();

    return content;

}

/*!

    Returns the value of the \c clampingStyle property.

    \sa setClampingStyle(), HbScrollArea::ClampingStyle

 */

HbScrollArea::ClampingStyle HbScrollArea::clampingStyle() const

{

    Q_D( const HbScrollArea );

    return d->mClampingStyle;

}

/*!

    Sets the \c clampingStyle property, which controls how scrolling is constrained

    relative to the contents of the scrolling area. The possible values are defined

    by the HbScrollArea::ClampingStyle enum. The default is

    HbScrollArea::BounceBackClamping.

    \sa clampingStyle()

 */

void HbScrollArea::setClampingStyle(ClampingStyle value)

{

    Q_D( HbScrollArea );

    d->mClampingStyle = value;

}

/*!

    Returns the value of the \c scrollingStyle property.

    \sa setScrollingStyle()

 */

HbScrollArea::ScrollingStyle HbScrollArea::scrollingStyle() const

{

    Q_D( const HbScrollArea );

    return d->mScrollingStyle;

}

/*!

    Sets the \c scrollingStyle property, which controls which gestures the user can

    use to scroll the contents and how the scrolling responds to those gestures. The

    possible values are defined by the HbScrollArea::ScrollingStyle enum. The default

    value is HbScrollArea::PanWithFollowOn.

    \sa scrollingStyle()

 */

void HbScrollArea::setScrollingStyle(ScrollingStyle value)

{

    Q_D( HbScrollArea );

    if (value == HbScrollArea::PanOrFlick) {

        d->mScrollingStyle = HbScrollArea::PanWithFollowOn;

        HB_DEPRECATED("HbScrollArea::PanOrFlick is deprecated");

    } else {

        d->mScrollingStyle = value;

    }

}

/*!

    Returns the value of the \c scrollDirections property.

    \sa setScrollDirections()

 */

Qt::Orientations HbScrollArea::scrollDirections() const

{

    Q_D( const HbScrollArea );

    return d->mScrollDirections;

}

/*!

    Sets the \c scrollDirections property, which controls the scrolling direction. The

    possible values are defined by the Qt::Orientations enum, as shown in the following

    table. The default value is Qt::Vertical.

    <table border="1" style="border-collapse: collapse; border: solid;">

    <tr><th>To enable:</th><th>Set to:</th></tr>

    <tr><td>Horizontal scrolling</td><td>Qt::Horizontal</td></tr>

    <tr><td>Vertical scrolling</td><td>Qt::Vertical</td></tr>

    <tr><td>Scrolling in both directions</td><td>Qt::Horizontal | Qt::Vertical</td></tr>

    </table>

    \sa scrollDirections()

 */

void HbScrollArea::setScrollDirections(Qt::Orientations value)

{

    Q_D( HbScrollArea );

    bool isChanged = (d->mScrollDirections != value);

    d->mScrollDirections = value;        

    if (d->mContents && isChanged) {

        QPointF pos = d->mContents->pos();

        QEvent layoutRequest(QEvent::LayoutRequest);

        QCoreApplication::sendEvent(this, &layoutRequest);

        d->mContents->setPos(pos);

    }

    if (isChanged) {

        emit scrollDirectionsChanged( value );

    }

}

/*!

    Returns true if the friction effect is enabled, false otherwise.

    \sa setFrictionEnabled()

 */

bool HbScrollArea::frictionEnabled() const

{

    Q_D( const HbScrollArea );

    return d->mFrictionEnabled;

}

/*!

    Sets the \c frictionEnabled property. The default value is true, which

    indicates that the friction effect is enabled.

    When the HbScrollArea::PanWithFollowOn scrolling style is in use, the

    \c frictionEnabled property controls the speed of the follow-on scrolling

    animation. When the friction effect is enabled (the default), it slows the

    animation and causes it to stop earlier than when the friction effect is not

    in use.

    \sa frictionEnabled()

 */