49     \brief HbScrollBar represents a scrollbar that can be used in different kinds of lists, options

    49     \brief The HbScrollBar class provides a vertical or horizontal scroll bar.

    50     menus and editors.

    50 

    51 

    51     Scroll bars indicate that more content is available than can fit within a container and

    52     A vertical scrollbar is created in this example to listview-parent and also shown:

    52     that the contents can be scrolled. A scroll bar consists of a groove and a handle (which

    53     is sometimes called a thumb). The position of the handle on the groove indicates the

    54     position of the visible content within the available contents. The size of the handle

    55     indicates the amount of content that is visible relative to the total. For example, a

    56     small handle indicates that there is a lot more content that is out of view.

    57 

    58     Scroll bars float above the content and do not need reserved space. There are two types of

    59     scroll bar:

    60 

    61     - <b>Indicative</b>. These scroll bars simply give an indication that the content can be

    62       scrolled and they do not provide features that enable scrolling (the ability to scroll

    63       is provided by the widget to which the scroll bar is attached). Indicative scroll bars are

    64       suitable for shorter lists and content that you expect the user to browse rather than to

    65       search for specific items. This is the default type of scroll bar.

    66 

    67     - <b>Interactive</b>. With this type of scroll bar, the user can drag the handle or press the

    68       groove to change the scroll position. When used in an item model view (classes derived

    69       from HbAbstractItemView), these scroll bars can provide index feedback (HbIndexFeedback

    70       class) when the user drags the scroll bar or taps on the groove. The feedback is a popup

    71       that shows, for example, the initial letter in an alphabetical list. Interactive scroll bars

    72       are particularly suitable for long lists.

    73 

    74     Call \link HbScrollBar::setInteractive() setInteractive(true)\endlink to make a scroll bar

    75     interactive. Call isInteractive() to discover whether a scroll bar is interactive.

    76 

    77     \image html hbscrollbar.png A list view with a vertical interactive scroll bar

    78 

    79     %HbScrollBar provides other properties that control the following aspects of a scroll bar:

    80 

    81     - <b>Value</b>. This is a real value in the range 0.0 to 1.0 that indicates how far the handle

    82       is from the start of the groove. For example, 0.5 means the handle is half way along the

    83       groove. Call setValue() to set this property.

    84 

    85     - <b>Page size</b>. This is a real value in the range 0.0 to 1.0 that indicates how much of the

    86       total contents are currently visible. This property also controls the size of the handle.

    87       For example, a page size of 0.1 indicates that one out of ten pages are visible. Call

    88       setPageSize() to set this property.

    89 

    90     - <b>Orientation</b>. This controls whether the scroll bar is horizontal or vertical. Call

    91       setOrientation() to set this property.

    92 

    93     \section _usecases_hbscrollbar Using the HbScrollBar class

    94 

    95     Although it is possible to create an HbScrollBar object directly, scroll bars are created

    96     automatically when you create an HbScrollArea object or one of the item view classes that

    97     are derived from it. This example demonstrates changing the default scroll bars

    98     created for an HbScrollArea object from indicative to interactive:

    55     //HbListView *listView is defined already

   101     scrollArea->verticalScrollBar()->setInteractive(true);

    56     HbScrollBar *scrollbar = new HbScrollBar(Qt::Vertical, listView);

   102     scrollArea->horizontalScrollBar()->setInteractive(true);

    57     scrollbar->show();

    60     By default scrollbar is hidden.

   105     You can replace the existing scroll bars by calling HbScrollArea::setHorizontalScrollBar()

    61 */

   106     and HbScrollArea::setVerticalScrollBar().

    62 

   107 

    63 /*!

   108     \sa HbScrollArea, HbAbstractItemView, HbIndexFeedback

    64     \reimp

   109  */

   110 

   111 /*!

    69     \fn void HbScrollBar::valueChanged( qreal value, Qt::Orientation orientation )

   116     \fn void HbScrollBar::valueChanged( qreal value, Qt::Orientation orientation );

    70 

   117 

    71     This signal is emitted when thumb position is changed by the user.

   118     This signal is emitted when the user changes the position of the handle in an interactive

    72 */

   119     scroll bar.

    73 

   120  */

    74 /*!

   121 

    75     \fn void valueChangeRequested( qreal value, Qt::Orientation orientation );

   122 /*!

    76 

   123     \fn void HbScrollBar::valueChangeRequested( qreal value, Qt::Orientation orientation );

    77     This signal is emitted when the user presses scrollbar groove.

   124 

    78 

   125     This signal is emitted when the user presses an interactive scroll bar's groove. The widget

    79     \param value, the new value of scrollbar after the change

   126     using the scroll bar must handle this signal (for example, by providing an animation that

    80   */

   127     scrolls to the target position).

   128 

   129     \param value The value to which the user wants to scroll.

   130     \param orientation The scroll bar's orientation.

   131 

   132     \sa HbScrollBar::setInteractive()

   133  */

    84     \primitive{groove} HbFrameItem representing the groove of a scrollbar.

   137     \primitive{groove} HbFrameItem representing the groove of a scroll bar.

    85     \primitive{handle} HbFrameItem representing the handle of a scrollbar.

   138     \primitive{handle} HbFrameItem representing the handle of a scroll bar.

    86     \primitive{toucharea} HbTouchArea representing the scrollbar toucharea.

   139     \primitive{toucharea} HbTouchArea representing the scroll bar toucharea.

    87   */

   140  */

   225     Constructs a scrollbar with \a parent.

   278     Constructs a scroll bar with the given \a parent.

   226 */

   279  */

   236     Constructs a scrollbar with \a orientation and \a parent.

   289     Constructs a scroll bar with the given \a orientation and \a parent.

   237 */

   290  */

   248     Destructor

   301     Destructor.

   255     Returns the value of the scrollbar. The value is in range of 0.0 to 1.0.

   308     Returns the scroll bar's \c value property. This indicates how far the handle is

   256     The value corresponds to the position of the thumb.

   309     from the start of the groove and can be in range of 0.0 to 1.0.

   267    Returns relative size of the visible area the scrollbar is attached to.

   320     Returns scroll bar's \c pageSize property. This is a real value in the range of 0.0 to

   268    For example if the pageSize is 0.2 it means that the overall size of the content

   321     1.0, which indicates the size of the visible content relative to the whole content.

   269    is five times larger than what is shown currently.

   322     For example, a page size of 0.2 indicates that the overall size of the content is five

   270 

   323     times larger than what is currently visible.

   271    The size is in range of 0.0 to 1.0.

   324 

   272    \sa HbScrollBar::setPageSize()

   325     \sa HbScrollBar::setPageSize()

   281     Returns the orientation of scrollbar.

   334     Returns the orientation of scroll bar.

   292     Returns whether scrollbar is in interactive mode.

   345     Returns true if the scroll bar is interactive and false if it is indicative.

   303     Sets the value of interactive property. If this value is set

   356     Sets the value of the scroll bar's \c interactive property, which controls whether the

   304     to true scrollbar is interactive, the user can change the scroll position by

   357     scroll bar is interactive or indicative (the default).

   305     dragging the thumb or pressing the groove. Dragging the thumb emits valueChanged

   358 

   306     signal and pressing the groove emits valueChangeRequested which means

   359     When the scroll bar is interactive, the user can drag the handle or press the groove to

   307     that the widget using scrollbars should handle the value change (for example

   360     change the scroll position. The following table lists the signals that an interactive

   308     by animating to the given target value).

   361     scroll bar emits when the user drags the handle or presses the groove.

   309 

   362 

   310     The default behavior is non interactive,

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

   311     which means that the scrollbar is just indicative.

   364     <tr><th>Signal</th><th>Description</th></tr>

   365     <tr><td>valueChanged()</td><td>This signal is emitted when the user drags the handle.</td></tr>

   366     <tr><td>valueChangeRequested()</td><td>This signal is emitted when the user presses the scroll

   367     bar's groove. The widget using the scroll bar must handle this signal (for example, by

   368     providing an animation that moves to the target position).</td></tr>

   369     </table>

   370 

   371     \param enabled A Boolean value; true for an interactive scroll bar, false for an indicative

   372            scroll bar.

   335     Sets the value of the scrollbar. The given \avalue should be from 0.0 to 1.0.

   396     Sets the scroll bar's \c value property, which controls how far the handle is from

   336     The value is used to position the thumb.

   397     the start of the groove.

   398 

   399     \param value A real value in the range 0.0 to 1.0. A value of 0.0 indicates that the

   400     handle is at the start of the groove and a value of 1.0 indicates that it is at the

   401     end.

   339 */

   404  */

   352     Sets the page size for the scrollbar. The page size is relative size of the visible area

   417     Sets the scroll bar's \c pageSize property, which indicates the size of the visible content

   353     the scrollbar is attached to. For example if the pageSize is 0.2 it means that the

   418     relative to the whole content. For example, a page size of 0.2 indicates that the

   354     overall size of the content is five times larger than what is shown currently.

   419     overall size of the content is five times larger than what is currently visible.

   355 

   420 

   356     \asize should be in the range of 0.0 to 1.0.

   421     \param size A real value in the range of 0.0 to 1.0.

   358 */

   423  */

   371     Sets the orientation of scrollbar.

   436     Sets the scroll bar's \c orientation property.

   437 

   438     \param orientation Set this to \c Qt::Horizontal for a horizontal scroll bar and

   439             \c Qt::Vertical for a vertical scroll bar.

   405     \reimp

   473     Reimplemented from QGraphicsWidget.

   420     \reimp

   488     Reimplemented from QGraphicsItem.

   494     \reimp

   562     Reimplemented from QGraphicsItem.

   524     \reimp

   592     Reimplemented from QGraphicsItem.

   564     \reimp

   632     Reimplemented from QGraphicsWidget.

   589     \reimp

   657     Reimplemented from QObject.

   685   \reimp

   753     \reimp