--- 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 )
{