diff -r e6ad4ef83b23 -r b7da29130b0e src/hbcore/gui/hbscrollbar.cpp --- a/src/hbcore/gui/hbscrollbar.cpp Thu Sep 02 20:44:51 2010 +0300 +++ b/src/hbcore/gui/hbscrollbar.cpp Fri Sep 17 08:32:10 2010 +0300 @@ -46,45 +46,98 @@ @stable @hbcore \class HbScrollBar - \brief HbScrollBar represents a scrollbar that can be used in different kinds of lists, options - menus and editors. + \brief The HbScrollBar class provides a vertical or horizontal scroll bar. + + Scroll bars indicate that more content is available than can fit within a container and + that the contents can be scrolled. A scroll bar consists of a groove and a handle (which + is sometimes called a thumb). The position of the handle on the groove indicates the + position of the visible content within the available contents. The size of the handle + indicates the amount of content that is visible relative to the total. For example, a + small handle indicates that there is a lot more content that is out of view. + + Scroll bars float above the content and do not need reserved space. There are two types of + scroll bar: + + - Indicative. These scroll bars simply give an indication that the content can be + scrolled and they do not provide features that enable scrolling (the ability to scroll + is provided by the widget to which the scroll bar is attached). Indicative scroll bars are + suitable for shorter lists and content that you expect the user to browse rather than to + search for specific items. This is the default type of scroll bar. + + - Interactive. With this type of scroll bar, the user can drag the handle or press the + groove to change the scroll position. When used in an item model view (classes derived + from HbAbstractItemView), these scroll bars can provide index feedback (HbIndexFeedback + class) when the user drags the scroll bar or taps on the groove. The feedback is a popup + that shows, for example, the initial letter in an alphabetical list. Interactive scroll bars + are particularly suitable for long lists. - A vertical scrollbar is created in this example to listview-parent and also shown: + Call \link HbScrollBar::setInteractive() setInteractive(true)\endlink to make a scroll bar + interactive. Call isInteractive() to discover whether a scroll bar is interactive. + + \image html hbscrollbar.png A list view with a vertical interactive scroll bar + + %HbScrollBar provides other properties that control the following aspects of a scroll bar: + + - Value. This is a real value in the range 0.0 to 1.0 that indicates how far the handle + is from the start of the groove. For example, 0.5 means the handle is half way along the + groove. Call setValue() to set this property. + + - Page size. This is a real value in the range 0.0 to 1.0 that indicates how much of the + total contents are currently visible. This property also controls the size of the handle. + For example, a page size of 0.1 indicates that one out of ten pages are visible. Call + setPageSize() to set this property. + + - Orientation. This controls whether the scroll bar is horizontal or vertical. Call + setOrientation() to set this property. + + \section _usecases_hbscrollbar Using the HbScrollBar class + + Although it is possible to create an HbScrollBar object directly, scroll bars are created + automatically when you create an HbScrollArea object or one of the item view classes that + are derived from it. This example demonstrates changing the default scroll bars + created for an HbScrollArea object from indicative to interactive: \code - //HbListView *listView is defined already - HbScrollBar *scrollbar = new HbScrollBar(Qt::Vertical, listView); - scrollbar->show(); + scrollArea->verticalScrollBar()->setInteractive(true); + scrollArea->horizontalScrollBar()->setInteractive(true); \endcode - By default scrollbar is hidden. -*/ + You can replace the existing scroll bars by calling HbScrollArea::setHorizontalScrollBar() + and HbScrollArea::setVerticalScrollBar(). + + \sa HbScrollArea, HbAbstractItemView, HbIndexFeedback + */ /*! - \reimp \fn int HbScrollBar::type() const */ /*! - \fn void HbScrollBar::valueChanged( qreal value, Qt::Orientation orientation ) + \fn void HbScrollBar::valueChanged( qreal value, Qt::Orientation orientation ); - This signal is emitted when thumb position is changed by the user. -*/ + This signal is emitted when the user changes the position of the handle in an interactive + scroll bar. + */ /*! - \fn void valueChangeRequested( qreal value, Qt::Orientation orientation ); + \fn void HbScrollBar::valueChangeRequested( qreal value, Qt::Orientation orientation ); + + This signal is emitted when the user presses an interactive scroll bar's groove. The widget + using the scroll bar must handle this signal (for example, by providing an animation that + scrolls to the target position). - This signal is emitted when the user presses scrollbar groove. + \param value The value to which the user wants to scroll. + \param orientation The scroll bar's orientation. - \param value, the new value of scrollbar after the change - */ + \sa HbScrollBar::setInteractive() + */ /*! \primitives - \primitive{groove} HbFrameItem representing the groove of a scrollbar. - \primitive{handle} HbFrameItem representing the handle of a scrollbar. - \primitive{toucharea} HbTouchArea representing the scrollbar toucharea. - */ + \primitive{groove} HbFrameItem representing the groove of a scroll bar. + \primitive{handle} HbFrameItem representing the handle of a scroll bar. + \primitive{toucharea} HbTouchArea representing the scroll bar toucharea. + */ HbScrollBarPrivate::HbScrollBarPrivate(): mOrientation(Qt::Vertical), @@ -222,8 +275,8 @@ } /*! - Constructs a scrollbar with \a parent. -*/ + Constructs a scroll bar with the given \a parent. + */ HbScrollBar::HbScrollBar( QGraphicsItem *parent ) : HbWidget(*new HbScrollBarPrivate, parent) { @@ -233,8 +286,8 @@ } /*! - Constructs a scrollbar with \a orientation and \a parent. -*/ + Constructs a scroll bar with the given \a orientation and \a parent. + */ HbScrollBar::HbScrollBar( Qt::Orientation orientation, QGraphicsItem *parent ) : HbWidget( *new HbScrollBarPrivate, parent ) { @@ -245,15 +298,15 @@ } /*! - Destructor + Destructor. */ HbScrollBar::~HbScrollBar() { } /*! - Returns the value of the scrollbar. The value is in range of 0.0 to 1.0. - The value corresponds to the position of the thumb. + Returns the scroll bar's \c value property. This indicates how far the handle is + from the start of the groove and can be in range of 0.0 to 1.0. \sa HbScrollBar::setValue() */ @@ -264,12 +317,12 @@ } /*! - Returns relative size of the visible area the scrollbar is attached to. - For example if the pageSize is 0.2 it means that the overall size of the content - is five times larger than what is shown currently. + Returns scroll bar's \c pageSize property. This is a real value in the range of 0.0 to + 1.0, which indicates the size of the visible content relative to the whole content. + For example, a page size of 0.2 indicates that the overall size of the content is five + times larger than what is currently visible. - The size is in range of 0.0 to 1.0. - \sa HbScrollBar::setPageSize() + \sa HbScrollBar::setPageSize() */ qreal HbScrollBar::pageSize() const { @@ -278,7 +331,7 @@ } /*! - Returns the orientation of scrollbar. + Returns the orientation of scroll bar. \sa HbScrollBar::setOrientation() */ @@ -289,7 +342,7 @@ } /*! - Returns whether scrollbar is in interactive mode. + Returns true if the scroll bar is interactive and false if it is indicative. \sa HbScrollBar::setInteractive() */ @@ -300,15 +353,23 @@ } /*! - Sets the value of interactive property. If this value is set - to true scrollbar is interactive, the user can change the scroll position by - dragging the thumb or pressing the groove. Dragging the thumb emits valueChanged - signal and pressing the groove emits valueChangeRequested which means - that the widget using scrollbars should handle the value change (for example - by animating to the given target value). + Sets the value of the scroll bar's \c interactive property, which controls whether the + scroll bar is interactive or indicative (the default). + + When the scroll bar is interactive, the user can drag the handle or press the groove to + change the scroll position. The following table lists the signals that an interactive + scroll bar emits when the user drags the handle or presses the groove. - The default behavior is non interactive, - which means that the scrollbar is just indicative. + + + + +
SignalDescription
valueChanged()This signal is emitted when the user drags the handle.
valueChangeRequested()This signal is emitted when the user presses the scroll + bar's groove. The widget using the scroll bar must handle this signal (for example, by + providing an animation that moves to the target position).
+ + \param enabled A Boolean value; true for an interactive scroll bar, false for an indicative + scroll bar. \sa HbScrollBar::isInteractive() */ @@ -332,11 +393,15 @@ } /*! - Sets the value of the scrollbar. The given \avalue should be from 0.0 to 1.0. - The value is used to position the thumb. + Sets the scroll bar's \c value property, which controls how far the handle is from + the start of the groove. + + \param value A real value in the range 0.0 to 1.0. A value of 0.0 indicates that the + handle is at the start of the groove and a value of 1.0 indicates that it is at the + end. \sa HbScrollBar::value() -*/ + */ void HbScrollBar::setValue( qreal value ) { Q_D(HbScrollBar); @@ -349,13 +414,13 @@ } /*! - Sets the page size for the scrollbar. The page size is relative size of the visible area - the scrollbar is attached to. For example if the pageSize is 0.2 it means that the - overall size of the content is five times larger than what is shown currently. + Sets the scroll bar's \c pageSize property, which indicates the size of the visible content + relative to the whole content. For example, a page size of 0.2 indicates that the + overall size of the content is five times larger than what is currently visible. - \asize should be in the range of 0.0 to 1.0. + \param size A real value in the range of 0.0 to 1.0. \sa HbScrollBar::pageSize() -*/ + */ void HbScrollBar::setPageSize( qreal size ) { Q_D(HbScrollBar); @@ -368,7 +433,10 @@ } /*! - Sets the orientation of scrollbar. + Sets the scroll bar's \c orientation property. + + \param orientation Set this to \c Qt::Horizontal for a horizontal scroll bar and + \c Qt::Vertical for a vertical scroll bar. \sa HbScrollBar::orientation() */ @@ -402,7 +470,7 @@ } /*! - \reimp + Reimplemented from QGraphicsWidget. */ void HbScrollBar::initStyleOption( HbStyleOptionScrollBar *option ) const { @@ -417,7 +485,7 @@ } /*! - \reimp + Reimplemented from QGraphicsItem. */ void HbScrollBar::mousePressEvent( QGraphicsSceneMouseEvent *event ) { @@ -491,7 +559,7 @@ } /*! - \reimp + Reimplemented from QGraphicsItem. */ void HbScrollBar::mouseReleaseEvent( QGraphicsSceneMouseEvent *event ) { @@ -521,7 +589,7 @@ } /*! - \reimp + Reimplemented from QGraphicsItem. */ void HbScrollBar::mouseMoveEvent( QGraphicsSceneMouseEvent *event ) { @@ -561,7 +629,7 @@ } /*! - \reimp + Reimplemented from QGraphicsWidget. */ QRectF HbScrollBar::boundingRect() const { @@ -586,7 +654,7 @@ } /*! - \reimp + Reimplemented from QObject. */ void HbScrollBar::timerEvent( QTimerEvent *event ) { @@ -682,7 +750,7 @@ } /*! - \reimp + \reimp */ void HbScrollBar::gestureEvent(QGestureEvent* event) {