src/hbwidgets/sliders/hbprogressbar.cpp
changeset 3 11d3954df52a
parent 2 06ff229162e9
child 5 627c4a0fd0e7
equal deleted inserted replaced
2:06ff229162e9 3:11d3954df52a
    38     @beta
    38     @beta
    39     @hbwidgets
    39     @hbwidgets
    40     \class HbProgressBar
    40     \class HbProgressBar
    41 
    41 
    42     \brief HbProgressBar widget provides a vertical and horizontal progress bar.
    42     \brief HbProgressBar widget provides a vertical and horizontal progress bar.
    43     An infinite progressbar is also available.
       
    44 
       
    45     A progress bar is used to give the user an indication of the progress of an operation and to 
       
    46     reassure them that the application is still running.
       
    47 
       
    48     The progress bar uses the concept of steps. User can set it up by specifying the minimum and 
       
    49     maximum possible step values, and it will display the percentage of steps that have been completed
       
    50     when you later give it the current step value. 
       
    51     
    43     
    52     The percentage is calculated by dividing the progress (progressValue() - minimum()) divided by maximum() - minimum().
    44     \image html progressbar.png  "A Progress Bar with Min-Max text at bottom"
    53 
    45     \image html infiniteprogressbar.png  "An infinite progres bar"
    54     User can specify the minimum and maximum number of steps with setMinimum() and setMaximum() APIs. 
    46 
    55     The current number of steps is set with setProgressValue(). 
    47     The HbProgressBar widget provides a horizontal or vertical progress bar.
    56 
    48 
    57     If minimum and maximum both are set to 0, the bar shows a busy indicator instead of a percentage of steps.
    49     A progress bar is used to give the user an indication of the progress of an operation and to reassure them that 
    58     This is useful, for example, when using ftp or http to download items when they are unable to 
    50     the application is still running. The progress bar uses the concept of steps. You set it up by specifying the 
    59     determine the size of the item being downloaded.
    51     minimum and maximum possible step values, and it will display the percentage of steps that have been completed 
    60 
    52     when you later give it the current step value. The percentage is calculated by dividing the 
    61     ProgressBar also supports adding text . min max text pair is also supported which is commonly 
    53     progress (value() - minimum()) divided by maximum() - minimum().
    62     used for progress indication for music.
       
    63     
    54     
    64     \image html hbprogressbartext.png Left Aligned Text, Min Max Text.
    55     By default the min value is 0 and max value is 100.If minimum and maximum both are set to 0, the bar shows a busy indicator 
    65 
    56     instead of a percentage of steps.
       
    57 
       
    58     ProgressBar also supports adding text . Min-Max text pair is also supported which is commonly 
       
    59     used for progress indication for music. 
       
    60     
    66     Progress bar provides below signal.
    61     Progress bar provides below signal.
    67 
    62 
    68     \li valueChanged(int value) Emitted when the value of the progressbar is changed.
    63     \li valueChanged(int value) Emitted when the value of the progressbar is changed.
    69 */
    64 
    70 
    65 
    71 /*!
    66     Example code for creating normal ProgressBar:
    72     @beta
    67     \code
    73     \fn void HbProgressBar::valueChanged(int value)
    68     HbProgressBar *pb = new HbProgressBar();
    74     
    69     pb->setMinimum(0);
    75     Emitted when the value of the progressbar is changed.
    70     pb->setMaximum(500);
    76 */
    71     pb->setProgressValue(175);
    77 
    72     \endcode
    78 
    73 
    79 /*!
    74     Example code for creating infinite ProgressBar:
    80     @beta
    75     \code
    81     \reimp
    76     HbProgressBar *pb = new HbProgressBar();
    82     \fn int HbProgressBar::type() const
    77     pb->setMinimum(0);
    83  */
    78     pb->setMaximum(0);
    84 
    79     \endcode
    85 /*!
    80 
    86     @beta
    81     Example code for creating normal ProgressBar with Min-Max text at Top:
    87     \enum HbProgressBar::ProgressBarType
    82     \code
    88 
    83     HbProgressBar *pb = new HbProgressBar();
    89     This enum defines available progress bar types.
    84     pb->setMinimum(0);
       
    85     pb->setMaximum(500);
       
    86     pb->setProgressValue(175);
       
    87     pb->setMinMaxTextVisible(true);
       
    88     pb->setMinMaxTextAlignment(Qt::AlignTop);// The possible options are Qt::AlignTop ,Qt::AlignBottom ,Qt::AlignCenter
       
    89     pb->setminText("0");
       
    90     pb->setmaxText("500");
       
    91 
       
    92     \endcode
       
    93 
       
    94     Example code for creating vertical normal ProgressBar:
       
    95     \code
       
    96     HbProgressBar *pb = new HbProgressBar();
       
    97     pb->setOrientation(Qt::Vertical);
       
    98     pb->setMinimum(0);
       
    99     pb->setMaximum(500);
       
   100     pb->setProgressValue(175);
       
   101     \endcode
    90 */
   102 */
    91 
   103 
    92 
   104 
    93 /*
   105 /*
    94     HbProgressBarPrivate
   106     HbProgressBarPrivate
   273 }
   285 }
   274 #endif
   286 #endif
   275 
   287 
   276 /*!
   288 /*!
   277     @beta
   289     @beta
   278     Constructor of  Progressbar.
   290    Constructs a progress bar with the given parent.
   279     \param parent. Parent widget
   291    By default, the minimum step value is set to 0, and the maximum to 100.
       
   292    \param parent The parent of ProgressBar
   280 
   293 
   281 */
   294 */
   282 HbProgressBar::HbProgressBar(QGraphicsItem *parent) : 
   295 HbProgressBar::HbProgressBar(QGraphicsItem *parent) : 
   283     HbWidget(*new HbProgressBarPrivate, parent)
   296     HbWidget(*new HbProgressBarPrivate, parent)
   284 {    
   297 {    
   303 }
   316 }
   304 
   317 
   305 /*!
   318 /*!
   306     @beta
   319     @beta
   307     Return the inverted appearence property. 
   320     Return the inverted appearence property. 
   308 
       
   309     \sa setInvertedAppearance()
   321     \sa setInvertedAppearance()
   310 */
   322 */
   311 bool HbProgressBar::invertedAppearance() const 
   323 bool HbProgressBar::invertedAppearance() const 
   312 {
   324 {
   313     Q_D( const HbProgressBar );
   325     Q_D( const HbProgressBar );
   344 
   356 
   345 /*!
   357 /*!
   346     @beta
   358     @beta
   347     Sets the maximum value of the progressbar. By default it is 100. 
   359     Sets the maximum value of the progressbar. By default it is 100. 
   348 
   360 
   349     \param maximum the max value
   361     \param maximum the maximum value
   350 
   362 
   351     \sa maximum()
   363     \sa maximum()
   352 */
   364 */
   353 void HbProgressBar::setMaximum(int maximum)
   365 void HbProgressBar::setMaximum(int maximum)
   354 {
   366 {
   370 
   382 
   371 /*!
   383 /*!
   372     @beta
   384     @beta
   373     Sets the minimum value of the progressbar. By default it is 0. 
   385     Sets the minimum value of the progressbar. By default it is 0. 
   374 
   386 
   375     \param maximum the max value
   387     \param minimum the minimum value
   376 
   388 
   377     \sa minimum()
   389     \sa minimum()
   378 */
   390 */
   379 void HbProgressBar::setMinimum(int minimum)
   391 void HbProgressBar::setMinimum(int minimum)
   380 {
   392 {
   408 }
   420 }
   409 
   421 
   410 /*!
   422 /*!
   411     @beta
   423     @beta
   412     This function is provided for convenience.
   424     This function is provided for convenience.
   413 
       
   414     Sets the progress bar's minimum and its maximum.
   425     Sets the progress bar's minimum and its maximum.
   415 
   426 
   416     If  maximum is smaller than minimum, minimum becomes the only valid legal
   427     If  maximum is smaller than minimum, minimum becomes the only valid legal
   417     value.
   428     value.
   418 
   429 
   419      \param minimum the minimum value
   430     \param minimum the minimum value
   420      \param maximum the maximum value
   431     \param maximum the maximum value
   421 */
   432 */
   422 void HbProgressBar::setRange(int minimum, int maximum) 
   433 void HbProgressBar::setRange(int minimum, int maximum) 
   423 {
   434 {
   424     Q_D( HbProgressBar );
   435     Q_D( HbProgressBar );
   425     d->setRange(minimum , maximum);
   436     d->setRange(minimum , maximum);
   426 }
   437 }
   427 
   438 
   428 /*!
   439 /*!
   429     @beta
   440     @beta
   430     Sets the min text string. 
   441     A text can be shown at top,bottom or left-right of the progressbar near minimum and maximum.
       
   442     This will set the text near the minimum point.
   431 
   443 
   432     \param text mintext string
   444     \param text mintext string
   433 
   445 
   434     \sa minText()
   446     \sa minText()
   435 */
   447 */
   455     return d->mMinText;
   467     return d->mMinText;
   456 }
   468 }
   457 
   469 
   458 /*!
   470 /*!
   459     @beta
   471     @beta
   460     Sets the max text string. 
   472     A text can be shown at top,bottom or left-right of the progressbar near minimum and maximum.
       
   473     This will set the text near the minimum point.
   461 
   474 
   462     \param text max text string
   475     \param text max text string
   463 
   476 
   464     \sa maxText()
   477     \sa maxText()
   465 */
   478 */
   594     Q_D(const HbProgressBar);
   607     Q_D(const HbProgressBar);
   595     return d->mOrientation;    
   608     return d->mOrientation;    
   596 }
   609 }
   597 
   610 
   598 /*!
   611 /*!
   599     Returns the pointer for \a primitive passed.
   612     \deprecated HbProgressBar::primitive(HbStyle::Primitive)
   600     Will return NULL if \a primitive passed is invalid
   613         is deprecated.
   601 */
   614 */
   602 QGraphicsItem* HbProgressBar::primitive(HbStyle::Primitive primitive) const
   615 QGraphicsItem* HbProgressBar::primitive(HbStyle::Primitive primitive) const
   603 {
   616 {
   604     Q_D(const HbProgressBar);
   617     Q_D(const HbProgressBar);
   605 
   618 
   651     }
   664     }
   652     HbWidget::updatePrimitives();
   665     HbWidget::updatePrimitives();
   653 }
   666 }
   654 
   667 
   655 /*!
   668 /*!
   656     Initializes \a option with the values from this HbProgressBar. This method 
   669     \reimp
   657     is useful for subclasses when they need a HbStyleOptionProgressBar, but don't
   670 */
   658     want to fill in all the information themselves.
       
   659  */
       
   660 
   671 
   661 void HbProgressBar::initStyleOption(HbStyleOptionProgressBar *option) const
   672 void HbProgressBar::initStyleOption(HbStyleOptionProgressBar *option) const
   662 {
   673 {
   663     Q_D( const HbProgressBar );
   674     Q_D( const HbProgressBar );
   664 
   675