FCL/sf/mw/hb: comparison src/hbwidgets/widgets/hbpushbutton.cpp

equal deleted inserted replaced

-:4633027730f5
+:e6ad4ef83b23
 #include <QApplication>
 /*!
 @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.
-\image html hbpushbutton.png A pushbutton with text ,icon and tooltip provided .
+A push button widget enables a user to perform an important command.
-A push button enable users to perform important commands easily.
+A push button has a rectangular shape and typically there is a text
-A push button has a rectangular shape and typically displays a text label describing its command.
+describing its command, an icon, and a tooltip shown on the button as in the
-Push Button can appear in any container except toolbars where ToolButton HbToolButton is used and palettes.
+following picture.
-A simple push button can be created as shown in the example below.
+\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:
+- 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.
+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.
+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.
+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}
-A Push buttons display a textual label. Pushbutton also
+\subsection _uc_hbpushbutton_002 Adding buttons to the layout.
-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.
+The push button is derived from HbWidget so it can be added to any
-Additional text can be set using setAdditionalText().
+QGraphicsLayout object for defining the layout. The following code snippet
-Aligning of icon , text and additional text can be changed using setStretched()true/false property.
+adds a button with "Stop" text and an another button with an image and "Play"
-Default with setStretched()=false it will place icon and text vertically.
+text to a QGraphicsLinearLayout object. Note that QGraphicsLinearLayout
+inherits QGraphicsLayout.
-\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.
-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.
-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.
-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.
-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
+\subsection _uc_hbpushbutton_003 Using a push button as a toggle button.
-\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,30}
+The following code snippet creates a push button which is used as a toggle
-and onOffButton as
+button. The button has a text, an icon, a tooltip, and its \c Checkable
-\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,29}
+property value is set to \c true.
-Push button will come up with additional text following is code snippet.
+\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,30}
-1. Push button with icon , text and additionalText
+\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.
+\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
 */
 /*!
-\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() :
 textItem(0),
 additionalTextItem(0),
 q_ptr = q;
 createPrimitives( );
 }
 /*!
-@beta
+Constructs a push button with \a parent.
-Constructs a new HbPushButton with \a parent.
 */
 HbPushButton::HbPushButton( QGraphicsItem *parent )
 : HbAbstractButton( *new HbPushButtonPrivate, parent )
 {
 Q_D( HbPushButton );
 setProperty( "state", "normal" );
 }
 /*!
-@beta
+Constructs a push button with \a text and \a parent.
-Constructs a new HbPushButton with \a text and \a parent.
 */
 HbPushButton::HbPushButton( const QString &text, QGraphicsItem *parent )
 : HbAbstractButton( *new HbPushButtonPrivate, parent )
 {
 Q_D( HbPushButton );
 }
 /*!
-@beta
+Constructs a push button with \a icon, \a text, and \a parent.
-Constructs a new HbPushButton with \a icon, \a text and \a parent.
 */
 HbPushButton::HbPushButton( const HbIcon &icon, const QString &text, QGraphicsItem *parent )
 : HbAbstractButton( *new HbPushButtonPrivate, parent )
 {
 Q_D( HbPushButton );
 setProperty( "state", "normal" );
 }
 /*!
-Destructs the push button.
+Destructor.
 */
 HbPushButton::~HbPushButton( )
 {
 }
 /*!
-@beta
+Sets the \a background shown on a push button. The background of a push
-Sets the \a background of the button.
+button can have different images for pressed and released states.
-\note The background can contain different images for pressed and released states.
 \sa background()
 */
 void  HbPushButton::setBackground( const HbIcon &background )
 {
 HbStylePrivate::updatePrimitive( d->frameItem, HbStylePrivate::P_PushButton_background, &buttonOption );
 }
 }
 /*!
-@beta
+Returns the background shown on a push button.
-Returns the background of the button.
 \sa setBackground()
 */
 HbIcon HbPushButton::background( ) const
 {
 Q_D( const HbPushButton );
 return d->background;
 }
 /*!
-@beta
+Sets the \a frame background shown on a push button. The frame background
-Sets the \a framebackground of the button.
+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
-\note The background can contain different types of frame drawers(Nine piece,
+to the push button.
-three piece or single).Ownership is transferred to the Pushbutton
 \sa frameBackground()
 */
 void  HbPushButton::setFrameBackground( HbFrameDrawer *backgroundFrameDrawer )
 {
 HbStylePrivate::updatePrimitive( d->frameItem, HbStylePrivate::P_PushButton_background, &buttonOption );
 }
 }
 /*!
-@beta
+Returns the background shown on a push button.
-Returns the background of the button.
 \sa setBackground()
 */
 HbFrameDrawer *HbPushButton::frameBackground( ) const
 {
 return ( d->backgroundFrameDrawer );
 }
 /*!
-@beta
+Sets the \a text shown on a push button.
-Sets the \a text shown on the button.
 \sa text()
 */
 void HbPushButton::setText( const QString &text )
 {
 }
 }
 /*!
-@beta
+Returns the text shown on a push button.
-Returns the text shown on the button.
 \sa setText()
 */
 QString HbPushButton::text( ) const
 {
 return d->text;
 }
 /*!
-@beta
+Sets the additional text shown on a push button, defined by \a
-Sets the \a additional text shown on the button.
+additionalText. Additional text is only shown on the button in the following
-Additional text is only shown in case
+cases:
-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.
+- Icon, text, and additional text are horizontally aligned in one line.
-3. with additionalText and text in Qt::Vertical alignment.
+- 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 );
 if ( d->additionalText != additionalText ) {
 bool doPolish = additionalText.isEmpty() || d->additionalText.isEmpty();
 }
 }
 }
 /*!
-@beta
+Returns the additional text shown on a push button.
-Returns the additional text shown on the button.
 \sa setAdditionalText()
 */
 QString HbPushButton::additionalText( ) const
 {
 Q_D( const HbPushButton );
 return d->additionalText;
 }
 /*!
-@beta
-Sets the \a icon shown on the button.
+Sets the \a icon shown on a push button. Each icon mode can have a
+different image.
-\note The icon can contain images for different modes.
 \sa icon()
 */
 void HbPushButton::setIcon( const HbIcon &icon )
 {
 }
 }
 }
 /*!
-@beta
+Returns the icon shown on a push button.
-Returns the icon shown on the button.
 \sa setIcon()
 */
 HbIcon HbPushButton::icon( ) const
 {
 Q_D( const HbPushButton );
 return d->icon;
 }
 /*!
-@beta
+Sets the alignment for the text. The default alignment is
-Set the text alignment for primarytext.
+horizontally and vertically aligned.
-The default alignment is Qt::AlignHCenter | Qt::AlignVCenter.
 \sa textAlignment()
 */
 void HbPushButton::setTextAlignment( Qt::Alignment alignment )
 {
 Q_D( HbPushButton );
 //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);
 // check for textitem and api protection flag
 if( alignment != d->textAlignment ){
 //take the alignment
 d->textAlignment = alignment;
 //set the api protection flag
 }
 d->hasTextAlignment = true;
 }
 /*!
-@beta
+Returns the text alignment for the text.
-Returns the text alignment for primary text.
 \sa setTextAlignment()
 */
 Qt::Alignment HbPushButton::textAlignment( ) const
 {
 Q_D(const HbPushButton);
 return d->textAlignment;
 }
 /*!
-@beta
+Sets the \a alignment for the additional text. The default alignment is
-Set the text alignment for additional text.
+horizontally and vertically centered alignment.
-The default alignment is Qt::AlignHCenter | Qt::AlignVCenter.
 \sa additionalTextAlignment()
 */
 void HbPushButton::setAdditionalTextAlignment( Qt::Alignment alignment )
 {
 Q_D( HbPushButton );
 //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);
 }
 // check for textitem and api protection flag
 d->additionalTextItem, HbStylePrivate::P_PushButton_additionaltext, &buttonOption );
 }
 }
 /*!
-@beta
+Returns the text alignment for the additional text.
-Returns the text alignment for additional text
 \sa setAdditionalTextAlignment()
 */
 Qt::Alignment HbPushButton::additionalTextAlignment( ) const
 {
 Q_D(const HbPushButton);
 return d->additionalTextAlignment;
 }
 /*!
-@beta
+Sets the alignment of an icon, a text and an additional text for stretched and non-
-Sets the stretched layout for button by default it set to true. setStretched true/false.
+stretched layouts of a push button.  The push button layouts with \a
-For the case icon and text with value false will appear icon and text vertically aligned.
+stretched value \c true and \c false (default) are the following:
-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
+- Icon and text:
-both text will be vertically aligned and icon will be horizontally.
+- \c true:  Icon and text are horizontally aligned.
-and with value true icon , text and additionaltext will come horizontally aligned in one line
+- \c false: Icon and text are vertically aligned.
-For the case text and additonaltext(dialer button case ) only value false is applicable and both texts will
+- Icon, text and additional text:
-appeare vertically
+- \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 )
 {
 Q_D(HbPushButton);
 repolish();
 }
 }
 /*!
-@beta
+Returns \c true if the push button has streteched layout, otherwise returns
-Returns the whether button has streteched layout or not.
+\c false.
 \sa setStretched ()
 */
 bool HbPushButton::isStretched() const
 {
 Q_D(const HbPushButton);
 return d->stretched;
 }
 /*!
-\deprecated HbPushButton::primitive(HbStyle::Primitive)
+\deprecated HbPushButton::primitive(HbStyle::Primitive) is deprecated.
-is deprecated.
-\reimp
 */
 QGraphicsItem *HbPushButton::primitive( HbStyle::Primitive primitive ) const
 {
 Q_D( const HbPushButton );
 return 0;
 }
 }
 /*!
-\reimp
 */
 void HbPushButton::recreatePrimitives()
 {
 Q_D( HbPushButton );
 HbWidget::recreatePrimitives();
 delete d->frameItem;
 d->frameItem = 0;
 delete d->iconItem;
 d->iconItem = 0;
 d->focusItem = 0;
 d->createPrimitives( );
 setFrameBackground( 0 );
 }
-/*!
-\reimp
+/*!
 */
 void HbPushButton::updatePrimitives()
 {
 Q_D( HbPushButton );
 HbWidget::updatePrimitives( );
 HbPushButton::HbPushButton(HbPushButtonPrivate &dd, QGraphicsItem *parent) :
 HbAbstractButton(dd, parent)
 {
 }
 /*!
-\reimp
-Initializes \a option with the values from this HbPushButton.
+Initializes the style option push button defined by \a option with the push
-This method is useful for subclasses when they need a HbStyleOptionPushButton,
+button values. This method is useful for setting the style option push button
-but don't want to fill in all the information themselves.
+values of the subclasses.
+\param option Style option push button to be initialized.
 */
 void HbPushButton::initStyleOption( HbStyleOptionPushButton *option ) const
 {
 Q_D( const HbPushButton );
 }
 option->backgroundFrameDrawer = ( d->backgroundFrameDrawer );
 }
 /*!
-\reimp
 */
 void HbPushButton::keyPressEvent(QKeyEvent *event)
 {
 Q_D( HbPushButton );
 HbAbstractButton::keyPressEvent(event);
 }
 /*!
-\reimp
 */
 void HbPushButton::keyReleaseEvent(QKeyEvent *event)
 {
 Q_D(HbPushButton);
 switch(event->key()){
 }
 HbAbstractButton::keyReleaseEvent( event );
 }
 /*!
-\reimp
 */
 void HbPushButton::mousePressEvent( QGraphicsSceneMouseEvent *event )
 {
 #ifndef HB_GESTURE_FW
 Q_D( HbPushButton );
 #endif
 }
 #ifndef HB_GESTURE_FW
 /*!
-\reimp
 */
 void HbPushButton::mouseReleaseEvent( QGraphicsSceneMouseEvent *event )
 {
 Q_D( HbPushButton );
 HbAbstractButton::mouseReleaseEvent( event );
 #endif
 setProperty( "state", "normal" );
 }
 /*!
-\reimp
 */
 void HbPushButton::mouseMoveEvent( QGraphicsSceneMouseEvent *event )
 {
 Q_D( HbPushButton );
 HbAbstractButton::mouseMoveEvent( event );
 }
 #endif
 #ifdef HB_GESTURE_FW
 void HbPushButton::gestureEvent( QGestureEvent *event )
 {
 Q_D(HbPushButton);
 if(HbTapGesture *tap = qobject_cast<HbTapGesture *>(event->gesture(Qt::TapGesture))) {
 bool hit = hitButton(mapFromScene(event->mapToGraphicsScene(tap->position())));
 }
 #endif
 /*!
-\reimp
 */
 void HbPushButton::resizeEvent( QGraphicsSceneResizeEvent *event )
 {
 HbAbstractButton::resizeEvent( event );
 }
-/*!
-reimp
+/*!
 */
 void HbPushButton::polish( HbStyleParameters &params )
 {
 Q_D( HbPushButton );
 HbAbstractButton::polish( params );
 }
 /*!
-\reimp
 */
 void HbPushButton::focusInEvent( QFocusEvent *event )
 {
 Q_D( HbPushButton );
 if( ( event->reason() == Qt::TabFocusReason || event->reason() == Qt::BacktabFocusReason )
 }
 HbAbstractButton::focusInEvent( event );
 }
 /*!
-\reimp
 */
 void HbPushButton::focusOutEvent( QFocusEvent *event )
 {
 Q_D( HbPushButton );
 if( d->focusItem ) {
 }
 HbAbstractButton::focusOutEvent( event );
 }
 /*!
-\reimp
 */
 QVariant HbPushButton::itemChange(GraphicsItemChange change, const QVariant &value)
 {
 switch ( change ) {
 case ItemEnabledHasChanged:
 }
 return HbAbstractButton::itemChange( change, value );
 }
 /*!
-Overloaded hit detection to include touch area
+Overloaded hit detection to include touch area.
 */
 bool HbPushButton::hitButton( const QPointF &pos ) const
 {
 Q_D( const HbPushButton );
 QRectF compRect = d->touchArea->boundingRect( );

changeset 23	e6ad4ef83b23
parent 21	4633027730f5
child 28	b7da29130b0e