1/***************************************************************************
2 * Copyright 2010 Stefan Majewsky <majewsky@gmx.net> *
3 * *
4 * This program is free software; you can redistribute it and/or modify *
5 * it under the terms of the GNU Library General Public License *
6 * version 2 as published by the Free Software Foundation *
7 * *
8 * This program is distributed in the hope that it will be useful, *
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
11 * GNU Library General Public License for more details. *
12 * *
13 * You should have received a copy of the GNU Library General Public *
14 * License along with this program; if not, write to the *
15 * Free Software Foundation, Inc., *
16 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. *
17 ***************************************************************************/
18
19#ifndef KGAMERENDEREDOBJECTITEM_H
20#define KGAMERENDEREDOBJECTITEM_H
21
22#include <QtCore/QObject>
23#include <QtGui/QGraphicsItem>
24class QGraphicsView;
25
26#include <kgamerendererclient.h>
27#include <libkdegames_export.h>
28
29class KGameRenderedObjectItemPrivate;
30
31/**
32 * @class KGameRenderedObjectItem kgamerenderedobjectitem.h <KGameRenderedObjectItem>
33 * @since 4.6
34 * @short A QGraphicsObject which displays pixmaps from a KGameRenderer.
35 *
36 * This item displays a pixmap which is retrieved from a KGameRenderer, and is
37 * updated automatically when the KGameRenderer changes the theme.
38 *
39 * The item has built-in handling for animated sprites (i.e. those with multiple
40 * frames). It is a QGraphicsObject and exposes a "frame" property, so you can
41 * easily run the animation by plugging in a QPropertyAnimation.
42 *
43 * @section operationalmodes Modes of operation
44 *
45 * By default, this item behaves just like a QGraphicsPixmapItem. The size of
46 * its bounding rect is equal to the size of the pixmap, i.e. the renderSize().
47 *
48 * However, the KGameRenderedObjectItem has a second mode of operation, which is
49 * enabled by setting a "primary view". (This can be done automatically via
50 * KGameRenderer::setDefaultPrimaryView.)
51 *
52 * If such a primary view is set, the following happens:
53 * \li The renderSize of the pixmap is automatically determined from the
54 * painting requests received from the primary view (manual calls to
55 * setRenderSize() are unnecessary and need to be avoided).
56 * \li The size of the item's boundingRect() is independent of the renderSize().
57 * The default fixedSize() is 1x1, which means that the item's bounding rect
58 * is the unit square (moved by the configured offset()).
59 */
60class KDEGAMES_EXPORT KGameRenderedObjectItem : public QGraphicsObject, public KGameRendererClient
61{
62 Q_OBJECT
63 Q_PROPERTY(int frame READ frame WRITE setFrame)
64 public:
65 ///Creates a new KGameRenderedObjectItem which renders the sprite with
66 ///the given @a spriteKey as provided by the given @a renderer.
67 KGameRenderedObjectItem(KGameRenderer* renderer, const QString& spriteKey, QGraphicsItem* parent = 0);
68 virtual ~KGameRenderedObjectItem();
69
70 ///@return the item's offset, which defines the point of the top-left
71 ///corner of the bounding rect, in local coordinates.
72 QPointF offset() const;
73 ///Sets the item's offset, which defines the point of the top-left
74 ///corner of the bounding rect, in local coordinates.
75 void setOffset(const QPointF& offset);
76 ///@overload
77 void setOffset(qreal x, qreal y);
78 ///@return the fixed size of this item (or (-1, -1) if this item has no
79 ///primary view)
80 QSizeF fixedSize() const;
81 ///Sets the fixed size of this item, i.e. the guaranteed size of the
82 ///item. This works only when a primary view has been set.
83 void setFixedSize(const QSizeF& size);
84
85 ///Returns a pointer to the current primary view, or 0 if no primary
86 ///view has been set (which is the default).
87 ///@see setPrimaryView()
88 QGraphicsView* primaryView() const;
89 ///Sets the primary view of this item. (See class documentation for what
90 ///the primary view does.) Pass a null pointer to just disconnect from
91 ///the current primary view. The fixed size is then reset to (-1, -1).
92 ///If a primary view is set, the fixed size is initialized to (1, 1).
93 ///@warning While a primary view is set, avoid any manual calls to
94 ///setRenderSize().
95 ///@see {Modes of operation}
96 void setPrimaryView(QGraphicsView* view);
97
98 //QGraphicsItem reimplementations (see comment in source file for why we need all of this)
99 virtual QRectF boundingRect() const;
100 virtual bool contains(const QPointF& point) const;
101 virtual bool isObscuredBy(const QGraphicsItem* item) const;
102 virtual QPainterPath opaqueArea() const;
103 virtual void paint(QPainter* painter, const QStyleOptionGraphicsItem* option, QWidget* widget = 0);
104 virtual QPainterPath shape() const;
105 protected:
106 virtual void receivePixmap(const QPixmap& pixmap);
107 private:
108 friend class KGameRenderedObjectItemPrivate;
109 KGameRenderedObjectItemPrivate* const d;
110};
111
112#endif // KGAMERENDEREDOBJECTITEM_H
113