src/tooltips/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      explicit 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     Q_OBJECT
 113 public:
 114      KToolTipDelegate();
 115      virtual ~KToolTipDelegate();
 116
 117      virtual QSize sizeHint(const KStyleOptionToolTip &option, const KToolTipItem &item) const;
 118
 119      /**
 120       * If haveAlphaChannel() returns true, the paint device will be filled with
 121       * Qt::transparent when this function is called, otherwise the content is
 122       * undefined.
 123       */
 124      virtual void paint(QPainter *painter,
 125                         const KStyleOptionToolTip &option,
 126                         const KToolTipItem &item) const;
 127
 128      /**
 129       * Reimplement this function to specify the region of the tooltip
 130       * that accepts input. Any mouse events that occur outside this
 131       * region will be sent to the widget below the tooltip.
 132       *
 133       * The default implementation returns a region containing the
 134       * bounding rect of the tooltip.
 135       *
 136       * This function will only be called if haveAlphaChannel()
 137       * returns true.
 138       */
 139      virtual QRegion inputShape(const KStyleOptionToolTip &option) const;
 140
 141      /**
 142       * Reimplement this function to specify a shape mask for the tooltip.
 143       *
 144       * The default implementation returns a region containing the
 145       * bounding rect of the tooltip.
 146       *
 147       * This function will only be called if haveAlphaChannel()
 148       * returns false.
 149       */
 150      virtual QRegion shapeMask(const KStyleOptionToolTip &option) const;
 151
 152 protected:
 153      /**
 154       * Returns true if the tooltip has an alpha channel, and false
 155       * otherwise.
 156       *
 157       * Implementors should assume that this condition may change at
 158       * any time during the runtime of the application, as compositing
 159       * can be enabled or disabled in the window manager.
 160       */
 161      bool haveAlphaChannel() const;
 162
 163 #if 0
 164 private Q_SLOTS:
 165      /**
 166       * Schedules a repaint of the tooltip item.
 167       * This slot can be connected to a timer to animate the tooltip.
 168       */
 169      void update(const KToolTipItem *item);
 170 #endif
 171 };
 172
 173
 174 /**
 175  * KToolTip provides customizable tooltips that can have animations as well as an alpha
 176  * channel, allowing for dynamic transparency effects.
 177  *
 178  * ARGB tooltips work on X11 even when the application isn't using the ARGB visual.
 179  */
 180 namespace KToolTip
 181 {
 182     void showText(const QPoint &pos, const QString &text, QWidget *widget, const QRect &rect);
 183     void showText(const QPoint &pos, const QString &text, QWidget *widget = 0);
 184
 185     /**
 186      * Shows the tip @p item at the global position indicated by @p pos.
 187      *
 188      * Ownership of the item is transferred to KToolTip. The item will be deleted
 189      * automatically when it is hidden.
 190      *
 191      * The tip is shown immediately when this function is called.
 192      */
 193     void showTip(const QPoint &pos, KToolTipItem *item);
 194     void hideTip();
 195
 196     void setToolTipDelegate(KToolTipDelegate *delegate);
 197 }
 198
 199 #endif