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