1/*
2 Copyright 2008 Aurélien Gâteau <agateau@kde.org>
3 Copyright 2009 Sebastian Trueg <trueg@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef _K_PIXMAPSEQUENCE_H_
22#define _K_PIXMAPSEQUENCE_H_
23
24#include <QtCore/QSharedDataPointer>
25#include <QtCore/QSize>
26
27#include "kdeui_export.h"
28#include <kiconloader.h>
29
30class QPixmap;
31
32/**
33 * \class KPixmapSequence kpixmapsequence.h KPixmapSequence
34 *
35 * \brief Loads and gives access to the frames of a typical multi-row pixmap
36 * as often used for spinners.
37 *
38 * KPixmapSequence is implicitly shared. Copying is fast.
39 *
40 * \author Aurélien Gâteau <agateau@kde.org>
41 * \author Sebastian Trueg <trueg@kde.org>
42 *
43 * \since 4.4
44 */
45class KDEUI_EXPORT KPixmapSequence
46{
47public:
48 /**
49 * Create an empty sequence
50 */
51 KPixmapSequence();
52
53 /**
54 * Copy constructor
55 */
56 KPixmapSequence(const KPixmapSequence &other);
57
58 /**
59 * Create a sequence from a pixmap.
60 *
61 * \param pixmap Pixmap to load
62 * \param frameSize The size of the frames to load. The width of the file has to be
63 * a multiple of the frame width; the same is true for the height. If an invalid
64 * size is specified the file is considered to be one column of square frames.
65 */
66 explicit KPixmapSequence(const QPixmap &pixmap, const QSize &frameSize = QSize());
67
68 /**
69 * Create a sequence from an icon name.
70 *
71 * \param iconName The name of the icon (example: process-working)
72 * \param size The icon/frame size
73 */
74 explicit KPixmapSequence(const QString &iconName, int size = KIconLoader::SizeSmall);
75
76 /**
77 * Destructor
78 */
79 ~KPixmapSequence();
80
81 /**
82 * Create a copy of \p other. The data is implicitly shared.
83 */
84 KPixmapSequence &operator=(const KPixmapSequence &other);
85
86 /**
87 * \return \p true if a sequence was loaded successfully.
88 *
89 * \sa isEmpty
90 */
91 bool isValid() const;
92
93 /**
94 * \return \p true if no sequence was loaded successfully.
95 *
96 * \sa isValid
97 */
98 bool isEmpty() const;
99
100 /**
101 * \return The size of an individual frame in the sequence.
102 */
103 QSize frameSize() const;
104
105 /**
106 * The number of frames in this sequence.
107 */
108 int frameCount() const;
109
110 /**
111 * Retrieve the frame at \p index.
112 *
113 * \param index The index of the frame in question starting at 0.
114 */
115 QPixmap frameAt(int index) const;
116
117private:
118 class Private;
119 QSharedDataPointer<Private> d;
120};
121
122#endif
123