src/ktooltip.h

   1 /***************************************************************************
   2  *   Copyright (C) 2008 by Fredrik Höglund <fredrik@kde.org>               *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; either version 2 of the License, or     *
   7  *   (at your option) any later version.                                   *
   8  *                                                                         *
   9  *   This program is distributed in the hope that it will be useful,       *
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  12  *   GNU General Public License for more details.                          *
  13  *                                                                         *
  14  *   You should have received a copy of the GNU General Public License     *
  15  *   along with this program; if not, write to the                         *
  16  *   Free Software Foundation, Inc.,                                       *
  17  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA            *
  18  ***************************************************************************/
  19
  20 #ifndef KTOOLTIP_H
  21 #define KTOOLTIP_H
  22
  23 #include <QObject>
  24 #include <QPalette>
  25 #include <QFont>
  26 #include <QRect>
  27 #include <QStyle>
  28 #include <QFontMetrics>
  29
  30 class QString;
  31 class QIcon;
  32 class QSize;
  33 class QPainter;
  34 class QRegion;
  35
  36 class KToolTipItemPrivate;
  37
  38 /**
  39  * KToolTipItem contains the data to be displayed in a tooltip.
  40  *
  41  * Custom data can be stored as QVariants in the object by calling
  42  * setData() with a custom item role, and retrieved and displayed
  43  * by a tooltip delegate by calling data().
  44  *
  45  * The default tooltip delegate uses Qt::DecorationRole and
  46  * Qt::DisplayRole.
  47  *
  48  * To display the tooltip, call KToolTip::showTip() with a pointer
  49  * to the KToolTipItem.
  50  *
  51  * You can reimplement the setData() and/or data() methods in this
  52  * class to implement on-demand loading of data.
  53  */
  54 class KToolTipItem
  55 {
  56 public:
  57      enum ItemType { DefaultType, UserType = 1000 };
  58
  59      /**
  60       * Creates a KToolTipItem with @p text and no icon.
  61       */
  62      KToolTipItem(const QString &text, int type = DefaultType);
  63
  64      /**
  65       * Creates a KToolTipItem with an @p icon and @p text.
  66       */
  67      KToolTipItem(const QIcon &icon, const QString &text, int type = DefaultType);
  68
  69      /**
  70       * Destroys the KToolTipItem.
  71       */
  72      virtual ~KToolTipItem();
  73
  74      /**
  75       * Returns the item type.
  76       */
  77      int type() const;
  78
  79      QString text() const;
  80      QIcon icon() const;
  81
  82      virtual QVariant data(int role) const;
  83      virtual void setData(int role, const QVariant &data);
  84
  85 private:
  86      KToolTipItemPrivate * const d;
  87 };
  88
  89
  90 class KStyleOptionToolTip
  91 {
  92 public:
  93     KStyleOptionToolTip();
  94     enum Corner { TopLeftCorner, TopRightCorner, BottomLeftCorner, BottomRightCorner, NoCorner };
  95
  96     Qt::LayoutDirection direction;
  97     QFontMetrics fontMetrics;
  98     QPalette palette;
  99     QRect rect;
 100     QStyle::State state;
 101     QFont font;
 102     QSize decorationSize;
 103     Corner activeCorner;
 104 };
 105
 106 /**
 107  * KToolTipDelegate is responsible for providing the size hint and
 108  * painting the tooltips.
 109  */
 110 class KToolTipDelegate : public QObject
 111 {
 112 public:
 113      KToolTipDelegate();
 114      virtual ~KToolTipDelegate();
 115
 116      virtual QSize sizeHint(const KStyleOptionToolTip *option, const KToolTipItem *item) const;
 117
 118      /**
 119       * If haveAlphaChannel() returns true, the paint device will be filled with
 120       * Qt::transparent when this function is called, otherwise the content is
 121       * undefined.
 122       */
 123      virtual void paint(QPainter *painter, const KStyleOptionToolTip *option,
 124                         const KToolTipItem *item) const;
 125
 126      /**
 127       * Reimplement this function to specify the region of the tooltip
 128       * that accepts input. Any mouse events that occur outside this
 129       * region will be sent to the widget below the tooltip.
 130       *
 131       * The default implementation returns a region containing the
 132       * bounding rect of the tooltip.
 133       *
 134       * This function will only be called if haveAlphaChannel()
 135       * returns true.
 136       */
 137      virtual QRegion inputShape(const KStyleOptionToolTip *option) const;
 138
 139      /**
 140       * Reimplement this function to specify a shape mask for the tooltip.
 141       *
 142       * The default implementation returns a region containing the
 143       * bounding rect of the tooltip.
 144       *
 145       * This function will only be called if haveAlphaChannel()
 146       * returns false.
 147       */
 148      virtual QRegion shapeMask(const KStyleOptionToolTip *option) const;
 149
 150 protected:
 151      /**
 152       * Returns true if the tooltip has an alpha channel, and false
 153       * otherwise.
 154       *
 155       * Implementors should assume that this condition may change at
 156       * any time during the runtime of the application, as compositing
 157       * can be enabled or disabled in the window manager.
 158       */
 159      bool haveAlphaChannel() const;
 160
 161 #if 0
 162 private Q_SLOTS:
 163      /**
 164       * Schedules a repaint of the tooltip item.
 165       * This slot can be connected to a timer to animate the tooltip.
 166       */
 167      void update(const KToolTipItem *item);
 168 #endif
 169 };
 170
 171
 172 /**
 173  * KToolTip provides customizable tooltips that can have animations as well as an alpha
 174  * channel, allowing for dynamic transparency effects.
 175  *
 176  * ARGB tooltips work on X11 even when the application isn't using the ARGB visual.
 177  */
 178 namespace KToolTip
 179 {
 180     void showText(const QPoint &pos, const QString &text, QWidget *widget, const QRect &rect);
 181     void showText(const QPoint &pos, const QString &text, QWidget *widget = 0);
 182
 183     /**
 184      * Shows the tip @p item at the global position indicated by @p pos.
 185      *
 186      * Ownership of the item is transferred to KToolTip. The item will be deleted
 187      * automatically when it is hidden.
 188      *
 189      * The tip is shown immediately when this function is called.
 190      */
 191     void showTip(const QPoint &pos, KToolTipItem *item);
 192     void hideTip();
 193
 194     void setToolTipDelegate(KToolTipDelegate *delegate);
 195 }
 196
 197 #endif