diff -r 4633027730f5 -r e6ad4ef83b23 src/hbwidgets/widgets/hbpushbutton.cpp --- 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(d->textItem); + //HbWidgetBase* textItem = static_cast(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(d->additionalTextItem); + //HbWidgetBase* additionalTextItem = static_cast(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 {