--- 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:
+
+ - <b>Indicative</b>. 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.
+
+ - <b>Interactive</b>. 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:
+
+ - <b>Value</b>. 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.
+
+ - <b>Page size</b>. 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.
+
+ - <b>Orientation</b>. 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.
+ <table border="1" style="border-collapse: collapse; border: solid;">
+ <tr><th>Signal</th><th>Description</th></tr>
+ <tr><td>valueChanged()</td><td>This signal is emitted when the user drags the handle.</td></tr>
+ <tr><td>valueChangeRequested()</td><td>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).</td></tr>
+ </table>
+
+ \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)
{