plasma-framework/tooltipmanager.h
Alex Merry e293d7d785 Specify includes in apidocs, so we get
#include <Plasma/Foo>
at the top of the apidocs pages.


svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=852289
2008-08-25 17:47:48 +00:00

205 lines
7.2 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_TOOL_TIP_MANAGER_H
#define PLASMA_TOOL_TIP_MANAGER_H
//plasma
#include <plasma/plasma.h>
#include <plasma/plasma_export.h>
namespace Plasma
{
class ToolTipManagerPrivate;
class Applet;
/**
* @class ToolTipManager plasma/tooltipmanager.h <Plasma/ToolTipManager>
*
* @short Manages tooltips for QGraphicsWidgets in Plasma
*
* If you want a widget to have a tooltip displayed when the mouse is hovered over
* it, you should do something like:
*
* @code
* // widget is a QGraphicsWidget*
* Plasma::ToolTipManager::ToolTipContent data;
* data.mainText = i18n("My Title");
* data.subText = i18n("This is a little tooltip");
* data.image = KIcon("some-icon").pixmap(IconSize(KIconLoader::Desktop));
* Plasma::ToolTipManager::self()->setToolTipContent(widget, data);
* @endcode
*
* Note that, since a Plasma::Applet is a QGraphicsWidget, you can use
* Plasma::ToolTipManager::self()->setToolTipContent(this, data); in the
* applet's init() method to set a tooltip for the whole applet.
*
* The tooltip will be registered automatically by setToolTipContent(). It will be
* automatically unregistered when the associated widget is deleted, freeing the
* memory used by the tooltip, but you can manually unregister it at any time by
* calling 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() slot
* will be invoked if it exists. This allows widgets to provide on-demand tooltip data.
*/
class PLASMA_EXPORT ToolTipManager : public QObject
{
Q_OBJECT
public:
/**
* @struct ToolTipContent plasma/tooltipmanager.h <Plasma/ToolTipManager>
*
* This provides the content for a tooltip.
*
* Normally you will want to set at least the @p mainText and
* @p subText.
*/
struct PLASMA_EXPORT ToolTipContent
{
/** Creates an empty ToolTipContent */
ToolTipContent();
/** @return true if all the fields are empty */
bool isEmpty() const;
/** Important information, e.g. the title */
QString mainText;
/** Elaborates on the @p mainText */
QString subText;
/** An icon to display */
QPixmap image;
/** Id of a window if you want to show a preview */
WId windowToPreview;
};
/**
* @return The singleton instance of the manager.
*/
static ToolTipManager *self();
/**
* Default constructor.
*
* You should normall use self() instead.
*/
explicit ToolTipManager(QObject* parent = 0);
/**
* Default destructor.
*/
~ToolTipManager();
/**
* Show the tooltip for a widget registered in the tooltip manager
*
* @param widget the widget for which the tooltip will be displayed
*/
void showToolTip(QGraphicsWidget *widget);
/**
* Find out whether the tooltip for a given widget is currently being displayed.
*
* @param widget the widget to check the tooltip for
* @return true if the tooltip of the widget is currently displayed,
* false if not
*/
bool isWidgetToolTipDisplayed(QGraphicsWidget *widget);
/**
* Hides the currently showing tooltip after a short amount of time.
*/
void delayedHideToolTip();
/**
* Hides the tooltip for a widget immediately.
*
* @param widget the widget to hide the tooltip for
*/
void hideToolTip(QGraphicsWidget *widget);
/**
* Registers a widget with the tooltip manager.
*
* Note that setToolTipContent() will register the widget if it
* has not already been registered, and so you do not normally
* need to use the method.
*
* This is useful for creating tooltip content on demand. You can
* register your widget with registerWidget(), then implement
* a slot named toolTipAboutToShow for the widget. This will be
* called before the tooltip is shown, allowing you to set the
* data with setToolTipContent().
*
* If the widget also has a toolTipHidden slot, this will be called
* after the tooltip is hidden.
*
* @param widget the desired widget
*/
void registerWidget(QGraphicsWidget *widget);
/**
* Unregisters a widget from the tooltip manager.
*
* This will free the memory used by the tooltip associated with the widget.
*
* @param widget the desired widget to delete
*/
void unregisterWidget(QGraphicsWidget *widget);
/**
* Sets the content for the tooltip associated with a widget.
*
* Note that this will register the widget with the ToolTipManager if
* necessary, so there is usually no need to call registerWidget().
*
* @param widget the widget the tooltip should be associated with
* @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);
/**
* Checks whether a widget has a tooltip associated with it.
*
* @param widget the widget to check for an associated tooltip
* @return true if the widget has a tooltip associated,
* false if it does not
*/
bool widgetHasToolTip(QGraphicsWidget *widget) const;
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())
};
} // namespace Plasma
#endif // PLASMA_TOOL_TIP_MANAGER_H