File indexing completed on 2024-07-14 04:00:05

0001 /*
0002     This file is part of the KDE games kwin4 program
0003     SPDX-FileCopyrightText: 2006 Martin Heni <kde@heni-online.de>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef PIXMAP_SPRITE_H
0009 #define PIXMAP_SPRITE_H
0010 
0011 // own
0012 #include "thememanager.h"
0013 // Qt
0014 #include <QElapsedTimer>
0015 #include <QGraphicsPixmapItem>
0016 #include <QPointF>
0017 
0018 /**
0019  * This sprite is used to display a pixmap on the canvas.
0020  * It can be animated and it is themeable.
0021  */
0022 class PixmapSprite : public QGraphicsPixmapItem, public virtual Themeable
0023 {
0024 public:
0025     /**
0026      * Constructor for the sprite.
0027      * @param no            A user defined ID number
0028      * @param scene        The graphics scene
0029      */
0030     PixmapSprite(int no, QGraphicsScene *scene);
0031 
0032     /**
0033      * Constructor for the sprite.
0034      * @param id            The theme file ID string
0035      * @param theme         The theme manager
0036      * @param no            A user defined ID number
0037      * @param scene        The graphics scene
0038      */
0039     PixmapSprite(const QString &id, ThemeManager *theme, int no, QGraphicsScene *scene);
0040 
0041     /**
0042      * Possible animation states of the sprite
0043      */
0044     enum AnimationState { Idle, Animated };
0045 
0046     /**
0047      * Standard QGI advance function.
0048      * @param phase The advance phase
0049      */
0050     void advance(int phase) override;
0051 
0052     /**
0053      * Retrieve the type of QGI. This item is UserType+3
0054      * @return The type of item.
0055      */
0056     int type() const override
0057     {
0058         return QGraphicsItem::UserType + 3;
0059     }
0060 
0061     /**
0062      * Retrieve the user defined sprite number (i.e. which PixmapSprite)
0063      * @return The sprite numbers.
0064      */
0065     int number()
0066     {
0067         return mNo;
0068     }
0069 
0070     /**
0071      * Main theme manager function. Called when any theme change like
0072      * a new theme or a theme size change occurs. This object needs to
0073      * resize and redraw then.
0074      */
0075     void changeTheme() override;
0076 
0077     /**
0078      * Choose a pixmap frame of this sprite. If the setting is forced a
0079      * redraw is even performed when the frame number stays the same. This
0080      * is important for theme changes.
0081      * @param no    The new frame number (0..)
0082      * @param force Force redraw
0083      */
0084     void setFrame(int no, bool force = false);
0085 
0086     /**
0087      * Initialize and start a frame animation between the start and end frame.
0088      * The delay between the frames is given in [ms]. After the last frame
0089      * is displayed the animation starts with the first frame.
0090      * @param start   The start frame number
0091      * @param end     The end frame number
0092      * @param delay   Delay between a frame change [ms]
0093      */
0094     void setAnimation(int start, int end, int delay);
0095 
0096     /**
0097      * Start or stop an animation.
0098      * @param status True to start and false to stop the animation
0099      */
0100     void setAnimation(bool status);
0101 
0102     /**
0103      * Set/Move the sprite to the given position. The position is
0104      * given in relative coordinates [0..1, 0..1] to its parent object.
0105      * Thus the position is scaled with the scale from the theme manager.
0106      * @param pos  The position of the sprite [0..1, 0..1]
0107      */
0108     void setPosition(QPointF pos);
0109 
0110     /**
0111      * Store the logical  coordinates (e.g 0-6, 0-5) for theme changes. Need to
0112      * manually be called after all setPosition or set Linear calls.
0113      * @param pos The logical position
0114      */
0115     void setLogicalPos(QPoint pos);
0116 
0117     /**
0118      * Retrieve the logical  coordinates.
0119      * @return The logical position.
0120      */
0121     QPoint logicalPos();
0122 
0123     /**
0124      * Reads a theme configuration item of type double and of the given
0125      * name.
0126      * @deprecated Thsi is debug only
0127      * @param item  The theme configuration item name
0128      * @return The read double value.
0129      */
0130     double getDoubleValue(const QString &item);
0131 
0132     /**
0133      * Set whether the sprite should respect a theme offset
0134      * (default: true) or not (false), that is, it is handled
0135      * by its parent item.
0136      * @param status True: Handle theme offset, False: do not
0137      */
0138     void setOffsetStatus(bool status);
0139 
0140 protected:
0141     /**
0142      * The user defined sprite number.
0143      */
0144     int mNo;
0145 
0146     /**
0147      * The state of the animation.
0148      */
0149     AnimationState mAnimationState;
0150 
0151     /**
0152      * The position of the sprite [rel 0..1, rel 0..1]
0153      */
0154     QPointF mStart;
0155 
0156     /**
0157      * The first frame in the frame animation.
0158      */
0159     int mStartFrame;
0160 
0161     /**
0162      * The last frame in the frame animation.
0163      */
0164     int mEndFrame;
0165 
0166     /**
0167      * The delay between two frames in the frame animation.
0168      */
0169     int mDelay;
0170 
0171     /**
0172      * The current running time for the animation.
0173      */
0174     QElapsedTimer mTime;
0175 
0176     /**
0177      * The current running frame number for the animation.
0178      */
0179     int mCurrentFrame;
0180 
0181     /**
0182      * Storage of the frame pixmaps.
0183      */
0184     QList<QPixmap> mFrames;
0185 
0186     /**
0187      * Storage of the frame pixmap offset points.
0188      */
0189     QList<QPointF> mHotspots;
0190 
0191     /**
0192      * The logical sprite pos for theme changs
0193      */
0194     QPoint mLPos;
0195 
0196     /**
0197      * Offset status.
0198      */
0199     bool mOffsetStatus;
0200 };
0201 
0202 #endif