/****************************************************************************+
−
**+
−
** Copyright (C) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).+
−
** All rights reserved.+
−
** Contact: Nokia Corporation (developer.feedback@nokia.com)+
−
**+
−
** This file is part of the HbCore module of the UI Extensions for Mobile.+
−
**+
−
** GNU Lesser General Public License Usage+
−
** This file may be used under the terms of the GNU Lesser General Public+
−
** License version 2.1 as published by the Free Software Foundation and+
−
** appearing in the file LICENSE.LGPL included in the packaging of this file.+
−
** Please review the following information to ensure the GNU Lesser General+
−
** Public License version 2.1 requirements will be met:+
−
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.+
−
**+
−
** In addition, as a special exception, Nokia gives you certain additional+
−
** rights.  These rights are described in the Nokia Qt LGPL Exception+
−
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.+
−
**+
−
** If you have questions regarding the use of this file, please contact+
−
** Nokia at developer.feedback@nokia.com.+
−
**+
−
****************************************************************************/+
−
+
−
#include "hbtooltip.h"+
−
#include "hbtooltiplabel_p.h"+
−
#include "hbinstance.h"+
−
#include "hbgraphicsscene.h"+
−
#include "hbgraphicsscene_p.h"+
−
+
−
#include <QGraphicsItem>+
−
+
−
/*!+
−
    @stable+
−
    @hbcore+
−
    \class HbToolTip+
−
+
−
    \brief The HbToolTip class provides tool tips (balloon help) for any graphics item.+
−
+
−
    \mainclass+
−
+
−
    The tip is a short piece of text reminding the user of the+
−
    graphics item's function.+
−
+
−
    The simplest and most common way to set a graphics item's tool tip is by+
−
    calling its QGraphicsItem::setToolTip() function.+
−
+
−
    When a tooltip is currently on+
−
    display, isVisible() returns true and text() the currently visible+
−
    text.+
−
+
−
    By default the tool tip framework is responsible for showing and hiding the tool tips+
−
    on the scene. When the framework detects a long mouse press event it checks what is the+
−
    top most QGraphicsItem on the scene having non empty tooltip text under the press point and+
−
    sends an QGraphicsSceneHelpEvent to it. This makes it possible that QGraphicsItem derived+
−
    objects can implement their own tool tip showing logic. If the sent QGraphicsSceneHelpEvent+
−
    event is accepted by the QGraphicsItem object then framework does nothing. Otherwise it shows+
−
    the tool tip text with Qt::AlignTop alignment.+
−
+
−
    In rare cases QGraphicsItem derived classes can handle QGraphicsSceneHelpEvent to provide+
−
    custom tool tip showing logic. An example on how to get custom tooltip alignment+
−
    on a QGraphicsItem derived class.+
−
    \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,25}+
−
+
−
    \sa QGraphicsItem::toolTip, QAction::toolTip+
−
*/+
−
+
−
/*!+
−
    \overload+
−
+
−
    This is analogous to calling HbToolTip::showText(\a text, \a item,+
−
                                                     item->boundingRect(), \a preferredAlignment)+
−
*/+
−
void HbToolTip::showText( const QString &text, QGraphicsItem *item,+
−
                          Qt::Alignment preferredAlignment )+
−
{+
−
    showText( text, item, item ? item->boundingRect() : QRectF(), preferredAlignment );+
−
}+
−
+
−
/*!+
−
    Shows \a text as a tool tip, with the prefererred alignment \a preferredAlignment in relation+
−
    to \a item.+
−
+
−
    If you specify a non-empty rect the tip will be hidden as soon+
−
    as you move your cursor out of this area.+
−
+
−
    The \a rect is in the coordinates of the graphics item you specify with+
−
    \a item.+
−
+
−
    If \a text is empty or the item 0 the tool tip is hidden.+
−
+
−
    The supported alignment flags are Qt::AlignTop, Qt::AlignRight, Qt::AlignLeft,+
−
    Qt::AlignTop|Qt::AlignRight, Qt::AlignTop|Qt::AlignLeft. Any other alignment flags are ignored.+
−
    Alignment flags are referring to the side of \a item i.e. when \a preferredAlignment+
−
    equals Qt::AlignTop the tool tip is aligned to the top of \a item and so on.+
−
    When Qt::AlignTop|Qt::AlignLeft combination is used the bottom-right corner of the tool tip is+
−
    aligned to the top-left corner of \a item. When Qt::AlignTop|Qt::AlignRight combination is used+
−
    the bottom-left corner of the tool tip is aligned to the top-right corner of \a item.+
−
+
−
    HbToolTip uses QStyle::visualAlignment() to transforms \a preferredAlignment according to the+
−
    current layout direction. Qt::AlignAbsolute is supported the way is described+
−
    in QStyle::visualAlignment().+
−
+
−
    If the tool tip could not be aligned properly i.e. without intersecting \a item's bounding+
−
    rectangle by using the provided \a preferredAlignment then it will be aligned by another+
−
    supported alignment option.+
−
+
−
    If none of the supported alignment options results proper alignment then Qt::AlignTop will+
−
    be used.+
−
+
−
*/+
−
void HbToolTip::showText( const QString &text, QGraphicsItem *item, const QRectF &rect,+
−
                          Qt::Alignment preferredAlignment )+
−
{+
−
    if (!item) {+
−
        return;+
−
    }+
−
    HbGraphicsScene *scene = qobject_cast<HbGraphicsScene *>( item->scene() );+
−
    if ( scene && text.isEmpty() ) { // empty text means hide current tip+
−
        scene->d_ptr->mToolTip->hide();+
−
    } else if (scene && scene->d_ptr->mToolTip) {+
−
+
−
        scene->d_ptr->mToolTip->setText(text);+
−
        scene->d_ptr->mToolTip->setRect( item->mapRectToScene(rect) );+
−
        scene->d_ptr->mToolTip->showText( item, preferredAlignment );+
−
    }+
−
}+
−
+
−
/*!+
−
    \fn void HbToolTip::hideText()+
−
+
−
    Hides the visible tooltip in the \a scene. This is the same as calling showText() with an+
−
    empty string or item parameter as 0.+
−
+
−
    \sa showText()+
−
*/+
−
void HbToolTip::hideText( HbGraphicsScene *scene )+
−
{+
−
    if ( scene && scene->d_ptr->mToolTip) {+
−
        if (scene->d_ptr->mToolTip->isVisible()) {+
−
            scene->d_ptr->mToolTip->hide();+
−
        } else {+
−
            //reset tooltip timers+
−
            scene->d_ptr->mToolTip->hideTextImmediately();+
−
        }+
−
    }+
−
}+
−
+
−
/*!+
−
  Returns true if this tooltip is currently shown.+
−
+
−
  \sa showText()+
−
 */+
−
bool HbToolTip::isVisible( const HbGraphicsScene *scene )+
−
{+
−
    if ( scene && scene->d_ptr->mToolTip ) {+
−
        return scene->d_ptr->mToolTip->isVisible();+
−
    } else {+
−
        return false;+
−
    }+
−
}+
−
+
−
/*!+
−
  Returns the tooltip text, if a tooltip is visible, or an+
−
  empty string if a tooltip is not visible.+
−
 */+
−
QString HbToolTip::text( const HbGraphicsScene *scene )+
−
{+
−
    if ( HbToolTip::isVisible(scene) ) {+
−
        return scene->d_ptr->mToolTip->text();+
−
    }+
−
    return QString();+
−
}+
−