/****************************************************************************
**
** 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();
}