* allocate ToolTip objects only as needed * invoke tool tip show/hide slots on the associated widget to allow for dynamic tooltip data svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=833526
181 lines
6.3 KiB
C++
181 lines
6.3 KiB
C++
/***************************************************************************
|
|
* Copyright 2008 by Alexis Ménard <darktears31@gmail.com> *
|
|
* Copyright 2008 by Aaron Seigo <aseigo@kde.org> *
|
|
* Copyright 2007 by Dan Meltzer <hydrogen@notyetimplemented.com> *
|
|
* *
|
|
* This program is free software; you can redistribute it and/or modify *
|
|
* it under the terms of the GNU General Public License as published by *
|
|
* the Free Software Foundation; either version 2 of the License, or *
|
|
* (at your option) any later version. *
|
|
* *
|
|
* This program is distributed in the hope that it will be useful, *
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
|
|
* GNU General Public License for more details. *
|
|
* *
|
|
* You should have received a copy of the GNU General Public License *
|
|
* along with this program; if not, write to the *
|
|
* Free Software Foundation, Inc., *
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA . *
|
|
***************************************************************************/
|
|
|
|
#ifndef PLASMA_TOOLTIP_MANAGER_H
|
|
#define PLASMA_TOOLTIP_MANAGER_H
|
|
|
|
//plasma
|
|
#include <plasma/plasma.h>
|
|
#include <plasma/plasma_export.h>
|
|
|
|
//KDE
|
|
#include <KWindowSystem>
|
|
|
|
#ifdef Q_WS_X11
|
|
#include <QX11Info>
|
|
#endif
|
|
|
|
//X11
|
|
#ifdef Q_WS_X11
|
|
#include <X11/Xlib.h>
|
|
#include <fixx11h.h>
|
|
#endif
|
|
|
|
namespace Plasma
|
|
{
|
|
class ToolTipManagerPrivate;
|
|
class Applet;
|
|
|
|
/**
|
|
* @short The class to manage tooltips on QGraphicsWidget in Plasma
|
|
*
|
|
* Manage tooltips on QGraphicsWidget. First you have to register your widget by calling
|
|
* registerWidget on the ToolTipManager singleton. After this you have to set the content of
|
|
* the tooltip by calling setToolTipContent using the struct ToolTipContent. Calling
|
|
* setToolTipContent on a widget that is not registered will cause it to be registered.
|
|
*
|
|
* The tooltip manager unregister automatically the widget when it is destroyed but if
|
|
* you want to do it manually call unregisterWidget.
|
|
*
|
|
* When a tooltip for a widget is about to be shown, the widget's toolTipAboutToShow slot will be
|
|
* invoked if it exists. Similarly, when a tooltip is hidden, the widget's toolTipHidden() slow
|
|
* will be invoked if it exists. This allows widgets to provide on-demand tooltip data.
|
|
*/
|
|
|
|
class PLASMA_EXPORT ToolTipManager : public QObject
|
|
{
|
|
Q_OBJECT
|
|
public:
|
|
|
|
/**
|
|
* Content of a tooltip
|
|
*/
|
|
struct ToolTipContent
|
|
{
|
|
ToolTipContent();
|
|
bool isEmpty() const;
|
|
|
|
QString mainText; /**Important information, e.g. the title*/
|
|
QString subText; /** Elaborates on the Main Text */
|
|
QPixmap image; /** Icon to show */
|
|
WId windowToPreview; /** Id of a window if you want to show a preview */
|
|
};
|
|
|
|
/**
|
|
*
|
|
* @return The singleton instance of the manager.
|
|
**/
|
|
static ToolTipManager *self();
|
|
|
|
/**
|
|
* Default constructor. Usually you want to use the singleton instead.
|
|
*/
|
|
explicit ToolTipManager(QObject* parent = 0);
|
|
|
|
/**
|
|
* Default destructor.
|
|
*/
|
|
~ToolTipManager();
|
|
|
|
/**
|
|
* Function to show a tooltip of a widget registered in the tooltip manager
|
|
* @param widget the widget on which the tooltip will be displayed
|
|
*/
|
|
void showToolTip(QGraphicsWidget *widget);
|
|
|
|
/**
|
|
* Function to know if a tooltip of a widget is displayed
|
|
* @param widget the desired widget
|
|
* @return true if te tooltip of the widget is currently displayed, otherwhise no
|
|
*/
|
|
bool isWidgetToolTipDisplayed(QGraphicsWidget *widget);
|
|
|
|
/**
|
|
* Function to launch a delayed hide of the current displayed tooltip
|
|
* @param widget the desired widget
|
|
*/
|
|
void delayedHideToolTip();
|
|
|
|
/**
|
|
* Function to hide the tooltip of the desired widget
|
|
* @param widget the desired widget
|
|
*/
|
|
void hideToolTip(QGraphicsWidget *widget);
|
|
|
|
/**
|
|
* Function to register a widget to the tooltip manager, after this a setWidgetToolTipContent
|
|
* must be called
|
|
* @param widget the desired widget
|
|
*/
|
|
void registerWidget(QGraphicsWidget *widget);
|
|
|
|
/**
|
|
* Function to unregister a widget in the tooltip manager, i.e. means that memory will be free
|
|
* @param widget the desired widget to delete
|
|
*/
|
|
void unregisterWidget(QGraphicsWidget *widget);
|
|
|
|
/**
|
|
* Function to set the content of a tooltip on a desired widget.
|
|
*
|
|
* @param widget the desired widget
|
|
* @param data the content of the tooltip. If an empty ToolTipContent is passed in,
|
|
* the tooltip content will be reset.
|
|
*/
|
|
void setToolTipContent(QGraphicsWidget *widget, const ToolTipContent &data);
|
|
|
|
/**
|
|
* Function to know if widget has a tooltip registered in the tooltip manager
|
|
* @param widget the widget
|
|
* @return true if this widget has a tooltip
|
|
*/
|
|
bool widgetHasToolTip(QGraphicsWidget *widget) const;
|
|
|
|
/**
|
|
* Reccomended position for a popup window like a menu or a tooltip
|
|
* given its size
|
|
* @param s size of the popup
|
|
* @returns reccomended position
|
|
*/
|
|
static QPoint popupPosition(const QGraphicsItem * item, const QSize &s);
|
|
|
|
/**
|
|
* Take an item and return its owning applet
|
|
* @param item the item on which we search an applet return NULL if no parent plasma applet
|
|
* found
|
|
*/
|
|
static const Applet * getItemItsApplet(const QGraphicsItem * item);
|
|
|
|
|
|
private:
|
|
friend class ToolTipManagerSingleton;
|
|
|
|
bool eventFilter(QObject * watched, QEvent * event);
|
|
|
|
ToolTipManagerPrivate* const d;
|
|
Q_PRIVATE_SLOT(d, void showToolTip())
|
|
Q_PRIVATE_SLOT(d, void resetShownState())
|
|
Q_PRIVATE_SLOT(d, void onWidgetDestroyed(QObject*))
|
|
Q_PRIVATE_SLOT(d, void themeUpdated())
|
|
};
|
|
}
|
|
#endif
|