diff -r b7da29130b0e -r 80e4d18b72f5 src/hbwidgets/widgets/hbcheckbox.cpp --- a/src/hbwidgets/widgets/hbcheckbox.cpp Fri Sep 17 08:32:10 2010 +0300 +++ b/src/hbwidgets/widgets/hbcheckbox.cpp Mon Oct 04 00:38:12 2010 +0300 @@ -109,39 +109,44 @@ } /*! - @beta @hbwidgets \class HbCheckBox - \brief The HbCheckBox widget provides a checkbox with a text label. + \brief The HbCheckBox class provides a check box widget with a text label. - \image html checkbox_unchecked.png A checkbox with unchecked state. - - \image html checkbox_checked.png A checkbox with checked state. + A check box is an option button that can be in checked, unchecked, and + partially checked states as shown in the pictures below. Check boxes are + typically used to represent application features that can be enabled or + disabled without affecting other features, but you can also subclass it to + implement different behavior. - \image html checkbox_partiallychecked.png A checkbox with partiallychecked state. + \image html checkbox_unchecked.png A check box in unchecked state. - A HbCheckBox is an option button that can be switched on (checked) - or off (unchecked). Checkboxes are typically used to represent - features in an application that can be enabled or disabled without - affecting others, but different types of behavior can be - implemented. + \image html checkbox_checked.png A check box in checked state. - Whenever a checkbox is checked or cleared it emits the signal - stateChanged(). Connect to this signal if you want to trigger an - action each time the checkbox changes state. You can use - isChecked() to query whether or not a checkbox is checked. + \image html checkbox_partiallychecked.png A check box in partially checked state. + + When a user checks or unchecks a check box, it emits the stateChanged() + signal. Connect a slot to this signal if you want to trigger an action every + time the check box state changes. You can use isChecked() to query whether a + check box is checked or not. - In addition to checked and unchecked states, HbCheckBox - optionally provides a third state which is PartiallyChecked. This - is useful for Hierarchical list item. If you need this third state, - enable it with setTristate(), and use checkState() to query the current - toggle state. + In addition to checked and unchecked states, %HbCheckBox provides + an optional partially checked state. This state is useful when you handle + hierarchical list items, for example. If you need the partially checked + state, enable it with setTristate() and query the state of the check box + with checkState(). - Checkbox has default icon for checked,unchecked and partiallyChecked states. - The text can be set in the constructor or with setText().For long text checkbox will show - multiline text,default checkbox will have text up to three lines. + A check box has default icons for checked, unchecked, and partially checked + states. The text can be set in the constructor or with setText(). If the + check box text is long, it is shown in multiple lines. By default a check box + can have up to three lines of text. - Example usage: + \section _usecases_hbcheckbox Using the HbCheckBox class + + \subsection _uc_hbcheckbox_001 Creating a check box. + + The following code snippet creates a check box in the layout. + \code HbCheckBox *checkbox = new HbCheckBox(QString("checkbox_text")); layout->addItem(checkbox); @@ -151,19 +156,28 @@ /*! + \fn void HbCheckBox::stateChanged(int state) - This signal is emitted whenever the check box's state changes, - i.e. whenever the user checks or unchecks it. - \a state contains the check box's new Qt::CheckState. + + This signal is emitted when the user checks or unchecks a check box causing a + state change of the check box. + + \param state The new state (Qt::CheckState) of the check box. + + \sa Qt + */ - /*! - @beta - Constructor an object of HbCheckBox with default parameters. - By default the state of check box will be Unchecked, text will - be empty and tristate will be false. + + Constructs a check box with the following default values: + - \a state is \c Qt::CheckState::Unchecked. + - \a text is empty. + - \a tristate is \c false. + + \sa Qt + */ HbCheckBox::HbCheckBox( QGraphicsItem *parent ) : HbAbstractButton( *new HbCheckBoxPrivate, parent ) @@ -179,10 +193,13 @@ } /*! - @beta - Constructor an object of HbCheckBox with \a text passed. - By default the state of check box will be Unchecked. - Tristate will be false by default. + + Constructs a check box with \a text and the following default values: + - \a state is \c Qt::CheckState::Unchecked. + - \a tristate is \c false. + + \sa Qt + */ HbCheckBox::HbCheckBox( const QString &text, QGraphicsItem *parent ) : HbAbstractButton( *new HbCheckBoxPrivate, parent ) @@ -202,9 +219,9 @@ } /*! - @beta - Sets the text of checkbox. - UpdatePrimitive is called by this functions once the text is changed. + + Sets the \a text shown on a check box. + \sa text() */ void HbCheckBox::setText( const QString &text ) @@ -222,8 +239,9 @@ } /*! - @beta - Returns the text of checkbox. + + Returns the text of a check box. + \sa setText() */ QString HbCheckBox::text( ) const @@ -233,9 +251,11 @@ } /*! - @beta - Sets tristate support for checkbox based upon \a flag. - By default tristate is false and checkbox has got only two states. + + Sets a check box to: + - tristate-enabled mode if \a isTristate is \c true. + - twostate-enabled mode if \a isTristate is \c false (default). + \sa isTristate( ) */ void HbCheckBox::setTristate( bool isTristate ) @@ -245,8 +265,12 @@ } /*! - @beta - Returns whether tristate is enabled for checkbox or not. + + Checks whether a check box can have two or three states. + + \return \c true if a check box is tristate-enabled. + \return \c false if a check box is twostate-enabled. + \sa setTristate( ) */ bool HbCheckBox::isTristate( ) const @@ -256,8 +280,10 @@ } /*! - @beta - Returns the current state of HbCheckBox. + + Returns the current state (checked, unchecked, or partially checked) of a + check box. + */ Qt::CheckState HbCheckBox::checkState() const { @@ -295,10 +321,10 @@ } /*! - @beta - Sets the state of HbCheckBox to the \a state passed. - Calls updatePrimitive when state is changed. - Emits signal stateChanged(state). + + Sets the state of a check box to \a state and emits the stateChanged() + signal. If the check box state changes, updatePrimitives() is called + */ void HbCheckBox::setCheckState( Qt::CheckState state ) { @@ -321,7 +347,7 @@ } /*! - Updates the icon and text primitives. + Updates the icon and the text primitives of a check box. */ void HbCheckBox::updatePrimitives( ) { @@ -343,7 +369,7 @@ } /*! - Initializes the style for check box with the \a option passed. + Initializes the style of a check box with the \a option style. */ void HbCheckBox::initStyleOption(HbStyleOptionCheckBox *option) const { @@ -361,7 +387,7 @@ } /*! - Updates the primitive as per new size. + */ void HbCheckBox::resizeEvent( QGraphicsSceneResizeEvent *event ) { @@ -369,7 +395,7 @@ } /*! - Overloaded hit detection to include touch area + */ bool HbCheckBox::hitButton( const QPointF &pos ) const { @@ -380,7 +406,7 @@ } /*! - \reimp. + */ void HbCheckBox::checkStateSet( ) { @@ -397,7 +423,7 @@ } /*! - \reimp. + */ void HbCheckBox::nextCheckState( ) { @@ -410,7 +436,7 @@ #ifndef HB_GESTURE_FW /*! - \reimp. + */ void HbCheckBox::mouseReleaseEvent( QGraphicsSceneMouseEvent *event ) { @@ -419,7 +445,7 @@ } /*! - \reimp. + */ void HbCheckBox::mouseMoveEvent( QGraphicsSceneMouseEvent *event ) { @@ -440,7 +466,7 @@ } #endif /*! - \reimp. + */ void HbCheckBox::keyPressEvent(QKeyEvent *keyEvent) { @@ -456,7 +482,7 @@ } /*! - \reimp + */ QVariant HbCheckBox::itemChange( GraphicsItemChange change, const QVariant &value ) {