--- a/src/hbwidgets/widgets/hbpushbutton.cpp Wed Aug 18 10:05:37 2010 +0300
+++ b/src/hbwidgets/widgets/hbpushbutton.cpp Thu Sep 02 20:44:51 2010 +0300
@@ -48,69 +48,116 @@
/*!
@beta
@hbwidgets
+
\class HbPushButton
- \brief The HbPushButton widget provides a button with command.
+ \brief The HbPushButton class provides a push button widget, which enables the
+ user to perform a command.
+
+ A push button widget enables a user to perform an important command.
+ A push button has a rectangular shape and typically there is a text
+ describing its command, an icon, and a tooltip shown on the button as in the
+ following picture.
- \image html hbpushbutton.png A pushbutton with text ,icon and tooltip provided .
+ \image html hbpushbutton.png A push button with a text, an icon, and a tooltip.
+
+ You can set the text and the icon of a push button with HbPushButton()
+ constructors and change them later with setText() and setIcon(). A push
+ button also can have an additional text which you can set with
+ setAdditionalText(). You can set the alignment of the text and additional text
+ with setTextAlignment() and setAdditionalTextAlignment(). The default value
+ for the alignment of the text and additional text is the horizontally and vertically
+ centered alignment. The push button layouts with \a stretched value \c true
+ and \c false (default) are the following:
- A push button enable users to perform important commands easily.
- A push button has a rectangular shape and typically displays a text label describing its command.
- Push Button can appear in any container except toolbars where ToolButton HbToolButton is used and palettes.
- A simple push button can be created as shown in the example below.
- \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,16}
-
- A Push buttons display a textual label. Pushbutton also
- can have icon.These can be set using the constructors and changed later using setText(),setIcon( ).
- In addition to this a push button also displays additional text label.
- Additional text can be set using setAdditionalText().
- Aligning of icon , text and additional text can be changed using setStretched()true/false property.
- Default with setStretched()=false it will place icon and text vertically.
-
- \image html buttonIconTextV.png A pushbutton with icon ,text.
-
- and along with additional text will place icon horizontally to both texts ,where both text comes vertically aligned.
-
- \image html buttonIconTextAdditionalTextV.png A pushbutton with icon ,text and additional text.
+ - Icon and text:
+ - \a stretched = \c true: The icon and the text are horizontally aligned.
+ \image html buttonIconTextH.png A stretched push button with an icon and a text.
+ - \a stretched = \c false: The icon and the text are vertically aligned.
+ \image html buttonIconTextV.png A non-stretched push button with an icon and a text.
+ - Icon, text and additional text:
+ - \a stretched = \c true: The icon and both texts are horizontally aligned in one
+ line.
+ \image html buttonIconTextAdditionalTextH.png A stretched push button with an icon, a text and an additional text.
+ - \a stretched = \c false: Both texts are vertically aligned and an icon is
+ horizontally aligned in relation to the texts.
+ \image html buttonIconTextAdditionalTextV.png A non-stretched push button with an icon, a text and an additional text.
+ - Text and additional text
+ - \a stretched = \c true: Not applicable.
+ - \a stretched = \c false: Both texts are vertically aligned. You can use this
+ layout for a dialer or a virtual keypad button, for example.
+ \image html buttonTextAdditional.png A non-stretched push button with a text and an additional text.
+
+ Note that a push button does not have a stretched layout by default.
- For setStretched()=true, it will stretch layout to have icon and text horizontally,side by side.
-
- \image html buttonIconTextH.png A pushbutton with icon ,text.
+ A toggle button is a special type of a push button. The push button becomes
+ a 'toggle button' -type push button, a 'toggle button' for short, if you set
+ the \c Checkable property value of a push button to \c true. A toggle button
+ can be in \c normal, \c highlighted , \c disabled, or \c latched state (see
+ state descriptions below). Normally you use a toggle button as an on-off
+ button that varies between \c normal (off) and \c latched (on) states as the
+ user presses the toggle button.
- and along with additional text will place all of them to Horizontally in one line .
-
- \image html buttonIconTextAdditionalTextH.png A pushbutton with custom icon ,text and additional text.
+ A push button can have the following states:
+ - normal: the push button does not have focus (i.e. it is not highlighted)
+ but the user can press it down.
+ - highlighted: the push button has focus.
+ - pressed: the push button is pressed down.
+ - latched: the push button stays pressed down even though the user does not
+ press it.
+ - disabled: the user cannot press down the push button.
- Pushbutton can have both text and additoinal text placed vertically,this can be used in case Dialer button or
- Virtual key pad buttons with stretched = false.Pushbutton doesn't supports both text in one line
- stretched = true is not valid.
- Pushbutton will not have stretch layout by default.
-
- \image html buttonTextAdditional.png A pushbutton with additional text and text.
+ A push button emits the pressed(), released(), clicked() and toggled()
+ signals which are inherited from HbAbstractButton as well as
+ HbPushButton::longPress() signal when a push button is pressed for a long
+ time. You can use a push button in any container except toolbars with
+ HbToolButton objects and palettes.
+
+
+ \section _usecases_hbpushbutton Using the HbPushButton class
+
+ \subsection _uc_hbpushbutton_001 Creating a push button.
+
+ The following code snippet creates a simple push button.
+
+ \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,16}
+
+ \subsection _uc_hbpushbutton_002 Adding buttons to the layout.
+
+ The push button is derived from HbWidget so it can be added to any
+ QGraphicsLayout object for defining the layout. The following code snippet
+ adds a button with "Stop" text and an another button with an image and "Play"
+ text to a QGraphicsLinearLayout object. Note that QGraphicsLinearLayout
+ inherits QGraphicsLayout.
- Pushbutton can have different states like normal, pressed, disabled, latched and focused.
- A push button emits the signal clicked() when it is activated by tapping it.
- Push buttons also provide less commonly used signals, for example, pressed() and
- released() and emits longPress() on long press.
-
- Alignment of the text within the text and additionaltext items can be set using
- setTextAlignment() and setAdditionalText(), default text alignment is Qt::AlignHCenter | Qt::AlignVCenter
-
- The push button is derived from HbWidget so it can be added to any QGraphicsLayout
- instance for layouting.
\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,17}
- Push button can also be used as toggle button , following is code snippet
- \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,30}
+ \subsection _uc_hbpushbutton_003 Using a push button as a toggle button.
+
+ The following code snippet creates a push button which is used as a toggle
+ button. The button has a text, an icon, a tooltip, and its \c Checkable
+ property value is set to \c true.
+
+ \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,30}
- and onOffButton as
- \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,29}
+ \subsection _uc_hbpushbutton_004 Using a push button as an on-off button.
+
+ The following code snippet creates a push button which is used as an on-off
+ button. The button has an icon, a text, and a tooltip.
- Push button will come up with additional text following is code snippet.
- 1. Push button with icon , text and additionalText
+ \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,29}
+
+ \subsection _uc_hbpushbutton_005 Creating a push button with an icon, a text, and an additional text.
+
+ The following code snippet creates a push button with with an icon, a text
+ and, an additional text.
+
\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,35}
- 2. Pushbutton with additionalText and text.
+ \subsection _uc_hbpushbutton_006 Creating a push button with a text and an additional text.
+
+ The following code snippet creates a push button with a text, and an additional text.
+
\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,36}
\sa HbAbstractButton , HbToolButton
@@ -118,13 +165,15 @@
/*!
- \reimp
+
\fn int HbPushButton::type() const
*/
/*!
\fn void HbPushButton::longPress( QPointF )
- This signal is emitted in case of longpress.
+
+ This signal is emitted when the user presses the push button for a long
+ time.
*/
HbPushButtonPrivate::HbPushButtonPrivate() :
@@ -235,8 +284,7 @@
}
/*!
- @beta
- Constructs a new HbPushButton with \a parent.
+ Constructs a push button with \a parent.
*/
HbPushButton::HbPushButton( QGraphicsItem *parent )
: HbAbstractButton( *new HbPushButtonPrivate, parent )
@@ -249,8 +297,7 @@
}
/*!
- @beta
- Constructs a new HbPushButton with \a text and \a parent.
+ Constructs a push button with \a text and \a parent.
*/
HbPushButton::HbPushButton( const QString &text, QGraphicsItem *parent )
: HbAbstractButton( *new HbPushButtonPrivate, parent )
@@ -265,8 +312,7 @@
}
/*!
- @beta
- Constructs a new HbPushButton with \a icon, \a text and \a parent.
+ Constructs a push button with \a icon, \a text, and \a parent.
*/
HbPushButton::HbPushButton( const HbIcon &icon, const QString &text, QGraphicsItem *parent )
: HbAbstractButton( *new HbPushButtonPrivate, parent )
@@ -281,7 +327,7 @@
}
/*!
- Destructs the push button.
+ Destructor.
*/
HbPushButton::~HbPushButton( )
{
@@ -289,10 +335,8 @@
}
/*!
- @beta
- Sets the \a background of the button.
-
- \note The background can contain different images for pressed and released states.
+ Sets the \a background shown on a push button. The background of a push
+ button can have different images for pressed and released states.
\sa background()
*/
@@ -309,8 +353,7 @@
}
/*!
- @beta
- Returns the background of the button.
+ Returns the background shown on a push button.
\sa setBackground()
*/
@@ -321,11 +364,10 @@
}
/*!
- @beta
- Sets the \a framebackground of the button.
-
- \note The background can contain different types of frame drawers(Nine piece,
- three piece or single).Ownership is transferred to the Pushbutton
+ Sets the \a frame background shown on a push button. The frame background
+ of a push button can have the following types of frame drawers: 9-piece, 3-
+ piece horizontal, 3-piece vertical, and single. The ownership is transferred
+ to the push button.
\sa frameBackground()
*/
@@ -342,8 +384,7 @@
}
/*!
- @beta
- Returns the background of the button.
+ Returns the background shown on a push button.
\sa setBackground()
*/
@@ -355,8 +396,7 @@
/*!
- @beta
- Sets the \a text shown on the button.
+ Sets the \a text shown on a push button.
\sa text()
*/
@@ -384,8 +424,7 @@
/*!
- @beta
- Returns the text shown on the button.
+ Returns the text shown on a push button.
\sa setText()
*/
@@ -397,15 +436,18 @@
/*!
- @beta
- Sets the \a additional text shown on the button.
- Additional text is only shown in case
- 1. with icon and text in Qt::Horizontal alignment.
- 2. with icon and text where both the texts are aligned vertically and icon placed horizontally in relation to texts.
- 3. with additionalText and text in Qt::Vertical alignment.
+ Sets the additional text shown on a push button, defined by \a
+ additionalText. Additional text is only shown on the button in the following
+ cases:
+
+ - Icon, text, and additional text are horizontally aligned in one line.
+ - Text and additional text are vertically aligned and icon is horizontally
+ aligned in relation to the texts.
+ - Text and additional text are vertically aligned.
\sa additionalText()
*/
+
void HbPushButton::setAdditionalText( const QString &additionalText )
{
Q_D( HbPushButton );
@@ -429,8 +471,7 @@
}
/*!
- @beta
- Returns the additional text shown on the button.
+ Returns the additional text shown on a push button.
\sa setAdditionalText()
*/
@@ -441,10 +482,9 @@
}
/*!
- @beta
- Sets the \a icon shown on the button.
-
- \note The icon can contain images for different modes.
+
+ Sets the \a icon shown on a push button. Each icon mode can have a
+ different image.
\sa icon()
*/
@@ -474,8 +514,8 @@
}
/*!
- @beta
- Returns the icon shown on the button.
+ Returns the icon shown on a push button.
+
\sa setIcon()
*/
@@ -486,21 +526,21 @@
}
/*!
- @beta
- Set the text alignment for primarytext.
- The default alignment is Qt::AlignHCenter | Qt::AlignVCenter.
+ Sets the alignment for the text. The default alignment is
+ horizontally and vertically aligned.
+
\sa textAlignment()
*/
void HbPushButton::setTextAlignment( Qt::Alignment alignment )
{
Q_D( HbPushButton );
- //HbWidgetBase* textItem = static_cast<HbWidgetBase*>(d->textItem);
+ //HbWidgetBase* textItem = static_cast<HbWidgetBase*>(d->textItem);
if( !d->textItem ) {
//need to create text item if user call alignment api before setText.
d->textItem = HbStylePrivate::createPrimitive( HbStylePrivate::P_PushButton_text, this);
}
- //HbWidgetBasePrivate *textItem_p = HbWidgetBasePrivate::d_ptr(textItem);
+ //HbWidgetBasePrivate *textItem_p = HbWidgetBasePrivate::d_ptr(textItem);
// check for textitem and api protection flag
if( alignment != d->textAlignment ){
//take the alignment
@@ -517,8 +557,8 @@
}
/*!
- @beta
- Returns the text alignment for primary text.
+ Returns the text alignment for the text.
+
\sa setTextAlignment()
*/
Qt::Alignment HbPushButton::textAlignment( ) const
@@ -529,16 +569,16 @@
/*!
- @beta
- Set the text alignment for additional text.
- The default alignment is Qt::AlignHCenter | Qt::AlignVCenter.
+ Sets the \a alignment for the additional text. The default alignment is
+ horizontally and vertically centered alignment.
+
\sa additionalTextAlignment()
*/
void HbPushButton::setAdditionalTextAlignment( Qt::Alignment alignment )
{
Q_D( HbPushButton );
- //HbWidgetBase* additionalTextItem = static_cast<HbWidgetBase*>(d->additionalTextItem);
+ //HbWidgetBase* additionalTextItem = static_cast<HbWidgetBase*>(d->additionalTextItem);
if(!d->additionalTextItem) {
//need to create text item if user call alignment api before setAdditionalText.
d->additionalTextItem = HbStylePrivate::createPrimitive( HbStylePrivate::P_PushButton_additionaltext, this);
@@ -558,8 +598,8 @@
}
/*!
- @beta
- Returns the text alignment for additional text
+ Returns the text alignment for the additional text.
+
\sa setAdditionalTextAlignment()
*/
Qt::Alignment HbPushButton::additionalTextAlignment( ) const
@@ -569,16 +609,20 @@
}
/*!
- @beta
- Sets the stretched layout for button by default it set to true. setStretched true/false.
- For the case icon and text with value false will appear icon and text vertically aligned.
- and with value true will appear icon and text horizontally aligned.
- For the case icon , text and additional text with value false will appear like
- both text will be vertically aligned and icon will be horizontally.
- and with value true icon , text and additionaltext will come horizontally aligned in one line
- For the case text and additonaltext(dialer button case ) only value false is applicable and both texts will
- appeare vertically
-
+ Sets the alignment of an icon, a text and an additional text for stretched and non-
+ stretched layouts of a push button. The push button layouts with \a
+ stretched value \c true and \c false (default) are the following:
+
+ - Icon and text:
+ - \c true: Icon and text are horizontally aligned.
+ - \c false: Icon and text are vertically aligned.
+ - Icon, text and additional text:
+ - \c true: Icon and both texts are horizontally aligned in one line.
+ - \c false: Both texts are vertically aligned and icon is horizontally aligned.
+ - Text and additonal text (a dialer push button case):
+ - \c true: Not applicable.
+ - \c false: Both texts are vertically aligned.
+
\sa isStretched()
*/
void HbPushButton::setStretched( bool stretched )
@@ -591,8 +635,9 @@
}
/*!
- @beta
- Returns the whether button has streteched layout or not.
+ Returns \c true if the push button has streteched layout, otherwise returns
+ \c false.
+
\sa setStretched ()
*/
bool HbPushButton::isStretched() const
@@ -603,10 +648,9 @@
/*!
- \deprecated HbPushButton::primitive(HbStyle::Primitive)
- is deprecated.
+ \deprecated HbPushButton::primitive(HbStyle::Primitive) is deprecated.
- \reimp
+
*/
QGraphicsItem *HbPushButton::primitive( HbStyle::Primitive primitive ) const
{
@@ -631,12 +675,12 @@
}
/*!
- \reimp
+
*/
void HbPushButton::recreatePrimitives()
{
Q_D( HbPushButton );
- HbWidget::recreatePrimitives();
+ HbWidget::recreatePrimitives();
delete d->frameItem;
d->frameItem = 0;
@@ -654,8 +698,9 @@
d->createPrimitives( );
setFrameBackground( 0 );
}
+
/*!
- \reimp
+
*/
void HbPushButton::updatePrimitives()
{
@@ -694,11 +739,13 @@
{
}
-/*!
- \reimp
- Initializes \a option with the values from this HbPushButton.
- This method is useful for subclasses when they need a HbStyleOptionPushButton,
- but don't want to fill in all the information themselves.
+/*!
+
+ Initializes the style option push button defined by \a option with the push
+ button values. This method is useful for setting the style option push button
+ values of the subclasses.
+
+ \param option Style option push button to be initialized.
*/
void HbPushButton::initStyleOption( HbStyleOptionPushButton *option ) const
{
@@ -724,7 +771,7 @@
}
/*!
- \reimp
+
*/
void HbPushButton::keyPressEvent(QKeyEvent *event)
{
@@ -760,7 +807,7 @@
/*!
- \reimp
+
*/
void HbPushButton::keyReleaseEvent(QKeyEvent *event)
{
@@ -792,7 +839,7 @@
}
/*!
- \reimp
+
*/
void HbPushButton::mousePressEvent( QGraphicsSceneMouseEvent *event )
{
@@ -817,7 +864,7 @@
#ifndef HB_GESTURE_FW
/*!
- \reimp
+
*/
void HbPushButton::mouseReleaseEvent( QGraphicsSceneMouseEvent *event )
{
@@ -837,7 +884,7 @@
}
/*!
- \reimp
+
*/
void HbPushButton::mouseMoveEvent( QGraphicsSceneMouseEvent *event )
{
@@ -858,6 +905,7 @@
#ifdef HB_GESTURE_FW
+
void HbPushButton::gestureEvent( QGestureEvent *event )
{
Q_D(HbPushButton);
@@ -907,14 +955,15 @@
/*!
- \reimp
+
*/
void HbPushButton::resizeEvent( QGraphicsSceneResizeEvent *event )
{
HbAbstractButton::resizeEvent( event );
}
+
/*!
- reimp
+
*/
void HbPushButton::polish( HbStyleParameters ¶ms )
@@ -929,7 +978,7 @@
/*!
- \reimp
+
*/
void HbPushButton::focusInEvent( QFocusEvent *event )
{
@@ -951,7 +1000,7 @@
}
/*!
- \reimp
+
*/
void HbPushButton::focusOutEvent( QFocusEvent *event )
{
@@ -963,7 +1012,7 @@
}
/*!
- \reimp
+
*/
QVariant HbPushButton::itemChange(GraphicsItemChange change, const QVariant &value)
{
@@ -984,7 +1033,7 @@
}
/*!
- Overloaded hit detection to include touch area
+ Overloaded hit detection to include touch area.
*/
bool HbPushButton::hitButton( const QPointF &pos ) const
{