1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (developer.feedback@nokia.com)

     6 **

     7 ** This file is part of the HbCore module of the UI Extensions for Mobile.

     8 **

     9 ** GNU Lesser General Public License Usage

    10 ** This file may be used under the terms of the GNU Lesser General Public

    11 ** License version 2.1 as published by the Free Software Foundation and

    12 ** appearing in the file LICENSE.LGPL included in the packaging of this file.

    13 ** Please review the following information to ensure the GNU Lesser General

    14 ** Public License version 2.1 requirements will be met:

    15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    16 **

    17 ** In addition, as a special exception, Nokia gives you certain additional

    18 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    20 **

    21 ** If you have questions regarding the use of this file, please contact

    22 ** Nokia at developer.feedback@nokia.com.

    23 **

    24 ****************************************************************************/

    25 

    26 #include "hbtooltip.h"

    27 #include "hbtooltiplabel_p.h"

    28 #include "hbinstance.h"

    29 #include "hbgraphicsscene.h"

    30 #include "hbgraphicsscene_p.h"

    31 

    32 #include <QGraphicsItem>

    33 

    34 /*!

    35     @stable

    36     @hbcore

    37     \class HbToolTip

    38 

    39     \brief The HbToolTip class provides tool tips (balloon help) for any graphics item.

    40 

    41     \mainclass

    42 

    43     The tip is a short piece of text reminding the user of the

    44     graphics item's function.

    45 

    46     The simplest and most common way to set a graphics item's tool tip is by

    47     calling its QGraphicsItem::setToolTip() function.

    48 

    49     When a tooltip is currently on

    50     display, isVisible() returns true and text() the currently visible

    51     text.

    52 

    53     By default the tool tip framework is responsible for showing and hiding the tool tips

    54     on the scene. When the framework detects a long mouse press event it checks what is the

    55     top most QGraphicsItem on the scene having non empty tooltip text under the press point and

    56     sends an QGraphicsSceneHelpEvent to it. This makes it possible that QGraphicsItem derived

    57     objects can implement their own tool tip showing logic. If the sent QGraphicsSceneHelpEvent

    58     event is accepted by the QGraphicsItem object then framework does nothing. Otherwise it shows

    59     the tool tip text with Qt::AlignTop alignment.

    60 

    61     In rare cases QGraphicsItem derived classes can handle QGraphicsSceneHelpEvent to provide

    62     custom tool tip showing logic. An example on how to get custom tooltip alignment

    63     on a QGraphicsItem derived class.

    64     \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,25}

    65 

    66     \sa QGraphicsItem::toolTip, QAction::toolTip

    67 */

    68 

    69 /*!

    70     \overload

    71 

    72     This is analogous to calling HbToolTip::showText(\a text, \a item,

    73                                                      item->boundingRect(), \a preferredAlignment)

    74 */

    75 void HbToolTip::showText( const QString &text, QGraphicsItem *item,

    76                           Qt::Alignment preferredAlignment )

    77 {

    78     showText( text, item, item ? item->boundingRect() : QRectF(), preferredAlignment );

    79 }

    80 

    81 /*!

    82     Shows \a text as a tool tip, with the prefererred alignment \a preferredAlignment in relation

    83     to \a item.

    84 

    85     If you specify a non-empty rect the tip will be hidden as soon

    86     as you move your cursor out of this area.

    87 

    88     The \a rect is in the coordinates of the graphics item you specify with

    89     \a item.

    90 

    91     If \a text is empty or the item 0 the tool tip is hidden.

    92 

    93     The supported alignment flags are Qt::AlignTop, Qt::AlignRight, Qt::AlignLeft,

    94     Qt::AlignTop|Qt::AlignRight, Qt::AlignTop|Qt::AlignLeft. Any other alignment flags are ignored.

    95     Alignment flags are referring to the side of \a item i.e. when \a preferredAlignment

    96     equals Qt::AlignTop the tool tip is aligned to the top of \a item and so on.

    97     When Qt::AlignTop|Qt::AlignLeft combination is used the bottom-right corner of the tool tip is

    98     aligned to the top-left corner of \a item. When Qt::AlignTop|Qt::AlignRight combination is used

    99     the bottom-left corner of the tool tip is aligned to the top-right corner of \a item.

   100 

   101     HbToolTip uses QStyle::visualAlignment() to transforms \a preferredAlignment according to the

   102     current layout direction. Qt::AlignAbsolute is supported the way is described

   103     in QStyle::visualAlignment().

   104 

   105     If the tool tip could not be aligned properly i.e. without intersecting \a item's bounding

   106     rectangle by using the provided \a preferredAlignment then it will be aligned by another

   107     supported alignment option.

   108 

   109     If none of the supported alignment options results proper alignment then Qt::AlignTop will

   110     be used.

   111 

   112 */

   113 void HbToolTip::showText( const QString &text, QGraphicsItem *item, const QRectF &rect,

   114                           Qt::Alignment preferredAlignment )

   115 {

   116     if (!item) {

   117         return;

   118     }

   119     HbGraphicsScene *scene = qobject_cast<HbGraphicsScene *>( item->scene() );

   120     if ( scene && text.isEmpty() ) { // empty text means hide current tip

   121         scene->d_ptr->mToolTip->hide();

   122     } else if (scene && scene->d_ptr->mToolTip) {

   123 

   124         scene->d_ptr->mToolTip->setText(text);

   125         scene->d_ptr->mToolTip->setRect( item->mapRectToScene(rect) );

   126         scene->d_ptr->mToolTip->showText( item, preferredAlignment );

   127     }

   128 }

   129 

   130 /*!

   131     \fn void HbToolTip::hideText()

   132 

   133     Hides the visible tooltip in the \a scene. This is the same as calling showText() with an

   134     empty string or item parameter as 0.

   135 

   136     \sa showText()

   137 */

   138 void HbToolTip::hideText( HbGraphicsScene *scene )

   139 {

   140     if ( scene && scene->d_ptr->mToolTip) {

   141         scene->d_ptr->mToolTip->hide();

   142     }

   143 }

   144 

   145 /*!

   146   Returns true if this tooltip is currently shown.

   147 

   148   \sa showText()

   149  */

   150 bool HbToolTip::isVisible( const HbGraphicsScene *scene )

   151 {

   152     if ( scene && scene->d_ptr->mToolTip ) {

   153         return scene->d_ptr->mToolTip->isVisible();

   154     } else {

   155         return false;

   156     }

   157 }

   158 

   159 /*!

   160   Returns the tooltip text, if a tooltip is visible, or an

   161   empty string if a tooltip is not visible.

   162  */

   163 QString HbToolTip::text( const HbGraphicsScene *scene )

   164 {

   165     if ( HbToolTip::isVisible(scene) ) {

   166         return scene->d_ptr->mToolTip->text();

   167     }

   168     return QString();

   169 }