1 /*
2     This file is part of the KDE games library
3     SPDX-FileCopyrightText: 2008 Andreas Pakulat <apaku@gmx.de>
4 
5     SPDX-License-Identifier: LGPL-2.0-only
6 */
7 
8 #ifndef CARDCACHE_H
9 #define CARDCACHE_H
10 
11 #include <QFlags>
12 
13 #include "libkdegames_export.h"
14 class QPixmap;
15 class QString;
16 class QSize;
17 class QSizeF;
18 
19 /**
20  * \class KCardInfo cardcache.h <KCardCache>
21  */
22 class KCardInfo
23 {
24 public:
25     enum Suit { None, Diamond, Heart, Club, Spade };
26     enum Card { Joker, Ace, King, Queen, Jack, Ten, Nine, Eight, Seven, Six, Five, Four, Three, Two };
27 
28     KCardInfo(Suit s, Card c);
29 
30     void setCard(Card c);
31     Card card() const;
32 
33     void setSuit(Suit s);
34     Suit suit() const;
35 
36     QString svgName() const;
37     bool operator==(KCardInfo c) const;
38 private:
39     Suit m_suit;
40     Card m_card;
41 };
42 
43 /**
44  * \class KCardCache cardcache.h <KCardCache>
45  *
46  * This class implements a kdegames wide cache for cards.
47  *
48  * Card games such as lskat or kpat should use this cache
49  * to load the various decks into QPixmaps instead of inventing
50  * their own. It uses KImageCache behind the scenes, set up to
51  * use disk and memory caching. Thus a SVG card deck that was loaded
52  * by kpat for the size 100x200 does not need re-rendering when
53  * requested from lskat.
54  *
55  * Usage is quite simple. During initialization of the game the
56  * cache object should be created and it should be told to load the
57  * currently selected theme.
58  * <code>
59  * myCache = new KCardCache();
60  * myCache->loadTheme(myTheme);
61  * </code>
62  *
63  * Later when actually drawing the cards the getter methods can be used to
64  * get the pixmap of a specific card at a specific size from a given theme.
65  * <code>
66  * myCache->getCard(myTheme, KCardCache::Club, KCardCache::Ace, calculatedSize);
67  * </code>
68  *
69  */
70 class KCardCache
71 {
72 public:
73     /**
74      * Can be used to load only parts of a theme, in case
75      * the user chose to have front and backside from different
76      * themes
77      */
78     enum LoadInfo
79     {
80         LoadFrontSide = 1 << 0 /**< Load only the front sides of the theme. */,
81         LoadBackSide = 1 << 2 /**< Load only the back side of the theme. */,
82         Load52Cards = 1 << 3 /**< Load a 52 card deck, ranges from Ace down to two */,
83         Load32Cards = 1 << 4 /**< Load a 32 card deck, ranges from Ace down to seven */,
84         Load53Cards = 1 << 5 /**< Load a 52 card deck as above, but include Jolly Joker */
85     };
86     Q_DECLARE_FLAGS(LoadInfos, LoadInfo)
87 
88     /**
89      * Constructor creates and initializes a KImageCache
90      * card games
91      */
92     KCardCache();
93 
94     /**
95      * Cleans up the cache
96      */
97     ~KCardCache();
98 
99     /**
100      * Set the size of rendered pixmaps.
101      *
102      * Make sure to set a reasonable size, before fetching pixmaps from the
103      * cache.
104      *
105      * @param size the new size for rendering cards and backsides
106      */
107     void setSize(const QSize &size);
108 
109     /**
110      * Returns the currently used size to render cards and backsides.
111      *
112      * @returns the size of pixmaps for rendering.
113      */
114     QSize size() const;
115 
116     /**
117      * Set the theme to be used to render the frontside of cards.
118      *
119      * Make sure to set a proper theme before fetching frontside pixmaps from
120      * the cache.
121      *
122      * @param theme the name of the theme to be use for rendering frontsides
123      */
124     void setDeckName(const QString &theme);
125 
126     /**
127      * Return the currently used frontside theme
128      * @returns the name of the frontside theme
129      */
130     QString deckName() const;
131 
132     /**
133      * Retrieve the backside of the given theme @p theme at the specified
134      * size @p size
135      *
136      * Make sure to set a reasonable size and theme, before calling this
137      * function.
138      *
139      * @param variant which variant, like a back with another color,
140      * to use for rendering. Defaults to -1 which means no variant.
141      *
142      * @returns a QPixmap with the card backside rendered
143      *
144      * @see setBackTheme
145      * @see setSize
146      */
147     QPixmap backside() const;
148 
149     /**
150      * Retrieve the default size for the backside card.
151      *
152      * Make sure to set a reasonable theme, before calling this function.
153      *
154      * @param variant which variant, like a back with another color, to use.
155      * Defaults to -1 which means no variant.
156      *
157      * @returns the default size of the selected background variant
158      *
159      */
160     QSizeF defaultBackSize() const;
161 
162     /**
163      * Invalidates all cached images in the current size for the current
164      * backside theme
165      */
166     void invalidateBackside();
167 
168     /**
169      * Retrieve the frontside pixmap.
170      *
171      * The @p info parameter is used to determine which frontside to load.
172      * Make sure to set a reasonable size and theme, before calling this
173      * function.
174      *
175      * @param info A combination of CardInfo flags to identify what type of card
176      * to load. There are of course only certain combinations that make sense,
177      * like King | Heart, some flags are used standalone, like Joker.
178      *
179      * @returns a QPixmap with the card frontside rendered
180      *
181      * @see setBackTheme
182      * @see setSize
183      * @see CardInfo
184      */
185     QPixmap frontside(KCardInfo info) const;
186 
187     /**
188      * Retrieve the default size for the frontside card.
189      *
190      * Make sure to set a reasonable theme, before calling this function.
191      *
192      * @param info A combination of CardInfo flags to identify what type of card
193      * to load. There are of course only certain combinations that make sense,
194      * like King | Heart, some flags are used standalone, like Joker.
195      *
196      * @returns the default size of the selected frontside card
197      *
198      */
199     QSizeF defaultCardSize(KCardInfo info) const;
200 
201     /**
202      * Invalidates all cached images in the current size for the current
203      * frontside theme
204      */
205     void invalidateCache();
206 
207     /**
208      * Loads a whole theme in the background.
209      *
210      * Depending on the value of @p type only parts may be rendered.
211      *
212      * @param infos whether to load all entries in the theme or just the front
213      * or back sides. Also its possible to specify a different deck, like a
214      * 32 card deck.
215      */
216     void loadTheme(LoadInfos infos = LoadInfos(LoadFrontSide | LoadBackSide | Load53Cards));
217 private:
218     class KCardCachePrivate *const d;
219 };
220 
221 Q_DECLARE_OPERATORS_FOR_FLAGS(KCardCache::LoadInfos)
222 
223 #endif
224