libkdegames/kgamepopupitem.h

   1 /*******************************************************************
   2     Copyright 2007 Dmitry Suzdalev <dimsuz@gmail.com>
   3
   4     This library 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 Free Software
  16     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  17  ********************************************************************/
  18 #ifndef K_GAME_POPUP_ITEM_H
  19 #define K_GAME_POPUP_ITEM_H
  20
  21 #include <libkdegames_export.h>
  22
  23 #include <QtGui/QGraphicsPathItem>
  24 #include <QtCore/QObject>
  25
  26 class KGamePopupItemPrivate;
  27
  28 /**
  29  * \class KGamePopupItem kgamepopupitem.h <KGamePopupItem>
  30  *
  31  * QGraphicsItem capable of showing short popup messages
  32  * which do not interrupt the gameplay.
  33  * Message can stay on screen for specified amount of time
  34  * and automatically hide after (unless user hovers it with mouse).
  35  *
  36  * Example of use:
  37  * \code
  38  * KGamePopupItem *messageItem = new KGamePopupItem();
  39  * myGraphicsScene->addItem(messageItem);
  40  * ...
  41  * messageItem->setMessageTimeout( 3000 ); // 3 sec
  42  * messageItem->showMessage("Hello, I'm a game message! How do you do?", BottomLeft);
  43  * \endcode
  44  */
  45 class KDEGAMES_EXPORT KGamePopupItem : public QObject, public QGraphicsItem
  46 {
  47     Q_OBJECT
  48 public:
  49     /**
  50      * Possible values for message showing mode in respect to a previous
  51      * message
  52      */
  53     enum ReplaceMode { LeavePrevious, ReplacePrevious };
  54     /**
  55      * Possible values for the popup angles sharpness
  56      */
  57     enum Sharpness { Square=0, Sharp=2, Soft=5, Softest=10 };
  58     /**
  59      * The possible places in the scene where a message can be shown
  60      */
  61     enum Position { TopLeft, TopRight, BottomLeft, BottomRight, Center };
  62     /**
  63      * Constructs a message item. It is hidden by default.
  64      */
  65     KGamePopupItem(QGraphicsItem * parent = 0);
  66     /**
  67      * Destructs a message item
  68      */
  69     ~KGamePopupItem();
  70     /**
  71      * Shows the message: item will appear at specified place
  72      * of the scene using simple animation
  73      * Item will be automatically hidden after timeout set in setMessageTimeOut() passes
  74      * If item is hovered with mouse it won't hide until user moves
  75      * the mouse away
  76      *
  77      * Note that if pos == Center, message animation will be of fade in/out type,
  78      * rather than slide in/out
  79      *
  80      * @param text holds the message to show
  81      * @param pos position on the scene where the message will appear
  82      * @param mode how to handle an already shown message by this item:
  83        either leave it and ignore the new one or replace it
  84      */
  85     void showMessage( const QString& text, Position pos, ReplaceMode mode = LeavePrevious);
  86     /**
  87      * Sets the amount of time the item will stay visible on screen
  88      * before it goes away.
  89      * By default item is shown for 2000 msec
  90      * If item is hovered with mouse it will hide only after
  91      * user moves the mouse away
  92      *
  93      * @param msec amount of time in milliseconds.
  94      * if msec is 0, then message will stay visible until it
  95      * gets explicitly hidden by forceHide()
  96      */
  97     void setMessageTimeout( int msec );
  98     /**
  99      * @return timeout that is currently set
 100      */
 101     int messageTimeout() const;
 102     /**
 103      * Sets the message opacity from 0 (fully transparent) to 1 (fully opaque)
 104      * For example 0.5 is half transparent
 105      * It defaults to 1.0
 106      */
 107     void setMessageOpacity( qreal opacity );
 108     /**
 109      * @return current message opacity
 110      */
 111     qreal messageOpacity() const;
 112     /**
 113      * Sets custom pixmap to show instead of default icon on the left
 114      */
 115     void setMessageIcon( const QPixmap& pix );
 116     /**
 117      * Sets whether to hide this popup item on mouse click.
 118      * By default a mouse click will cause an item to hide
 119      */
 120     void setHideOnMouseClick( bool hide );
 121     /**
 122      * @return whether this popup item hides on mouse click.
 123      */
 124     bool hidesOnMouseClick() const;
 125     /**
 126      * Used to specify how to hide in forceHide() - instantly or animatedly
 127      */
 128     enum HideType { InstantHide, AnimatedHide };
 129     /**
 130      * Requests the item to be hidden immediately.
 131      */
 132     void forceHide(HideType type=AnimatedHide);
 133     /**
 134      * Sets brush used to paint item backgound
 135      * By default system-default brush is used
 136      * @see KColorScheme
 137      */
 138     void setBackgroundBrush( const QBrush& brush );
 139     /**
 140      * Sets default color for unformatted text
 141      * By default system-default color is used
 142      * @see KColorScheme
 143      */
 144     void setTextColor( const QColor& color );
 145     /**
 146      * @return the bounding rect of this item. Reimplemented from QGraphicsItem
 147      */
 148     virtual QRectF boundingRect() const;
 149     /**
 150      * Paints item. Reimplemented from QGraphicsItem
 151      */
 152     virtual void paint( QPainter* p, const QStyleOptionGraphicsItem *option, QWidget* widget );
 153     /**
 154      * Sets the popup angles sharpness
 155      */
 156     void setSharpness( Sharpness sharpness );
 157     /**
 158      * @return current popup angles sharpness
 159      */
 160     Sharpness sharpness() const;
 161 Q_SIGNALS:
 162     /**
 163      * Emitted when user clicks on a link in item
 164      */
 165     void linkActivated( const QString& link );
 166     /**
 167      * Emitted when user hovers a link in item
 168      */
 169     void linkHovered( const QString& link );
 170     /**
 171      * Emitted when the popup finishes hiding. This includes hiding caused by
 172      * both timeouts and mouse clicks.
 173      */
 174     void hidden();
 175 private Q_SLOTS:
 176     void animationFrame(int);
 177     void hideMe();
 178     void playHideAnimation();
 179     void onLinkHovered(const QString&);
 180     void onTextItemClicked();
 181 private:
 182     void setupTimeline();
 183     virtual void mousePressEvent( QGraphicsSceneMouseEvent* );
 184     virtual void mouseReleaseEvent( QGraphicsSceneMouseEvent* );
 185     virtual void hoverEnterEvent( QGraphicsSceneHoverEvent* );
 186     virtual void hoverLeaveEvent( QGraphicsSceneHoverEvent* );
 187
 188     KGamePopupItemPrivate * const d;
 189 };
 190
 191 #endif