File indexing completed on 2022-11-29 18:40:55

0001 /*
0002     SPDX-FileCopyrightText: 2001-2003 Nicolas Hadacek <hadacek@kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-only
0005 */
0006 
0007 #ifndef KEXTHIGHSCORE_ITEM_H
0008 #define KEXTHIGHSCORE_ITEM_H
0009 
0010 #include <QMap>
0011 #include <QVariant>
0012 #include <QVector>
0013 #include <libkdegames_export.h>
0014 class QWidget;
0015 
0016 
0017 namespace KExtHighscore
0018 {
0019 
0020 //-----------------------------------------------------------------------------
0021 /**
0022  * This class defines how to convert and how to display
0023  * a highscore element (such as the score, the date, ...) or a player
0024  * info (such as the player name, the best score, ...).
0025  */
0026 class  Item
0027 {
0028  public:
0029     /**
0030      * Possible display format.
0031      * <ul>
0032      * <li> @p NoFormat : no formatting (default) </li>
0033      * <li> @p OneDecimal : with one decimal (only for Double) </li>
0034      * <li> @p Percentage : with one decimal + % (only for Double) </li>
0035      * <li> @p MinuteTime : MM:SS ie 3600 is 00:00, 1 is 59:59 and 0 is
0036      *      undefined (only for UInt, Int and Double) </li>
0037      * <li> @p DateTime : date and time according to locale (only for
0038      *      DateTime) </li>
0039      * </ul>
0040      */
0041     enum Format { NoFormat, OneDecimal, Percentage, MinuteTime,
0042                   DateTime };
0043 
0044     /**
0045      * Possible special value for display format.
0046      * <ul>
0047      * <li> @p NoSpecial : no special value ; a null DateTime is replaced by
0048      *      "--" (default) </li>
0049      * <li> ZeroNotDefined : 0 is replaced by "--" (only for UInt, Int and
0050      *      Double) </li>
0051      * <li> @p NegativeNotDefined : negative values are replaced by "--" (only
0052      *      for Int and Double) </li>
0053      * <li> @p DefaultNotDefined : default value is replaced by "--" </li>
0054      * <li> @p Anonymous : replace the special value ItemBase::ANONYMOUS
0055      *      by i18n("anonymous") (only for String) </li>
0056      * </ul>
0057      */
0058     enum Special { NoSpecial, ZeroNotDefined, NegativeNotDefined,
0059                    DefaultNotDefined, Anonymous };
0060 
0061     /**
0062      * Constructor.
0063      *
0064      * @param def default value ; the QVariant also gives the type of data.
0065      * Be sure to cast the value to the required type (for e.g. with uint).
0066      * @param label the label corresponding to the item. If empty, the item
0067      *              is not shown.
0068      * @param alignment the alignment of the item.
0069      */
0070     explicit Item(const QVariant &def = QVariant::Invalid,
0071          const QString &label = QString(), Qt::AlignmentFlag alignment = Qt::AlignRight);
0072 
0073     virtual ~Item();
0074 
0075     /**
0076      * Set the display format.
0077      * @see Format
0078      */
0079     void setPrettyFormat(Format format);
0080 
0081     /**
0082      * Set the special value for display.
0083      * @see Special
0084      */
0085     void setPrettySpecial(Special special);
0086 
0087     /**
0088      * @return if the item is shown.
0089      */
0090     bool isVisible() const    { return !_label.isEmpty(); }
0091 
0092     /**
0093      * Set the label.
0094      */
0095     void setLabel(const QString &label) { _label = label; }
0096 
0097     /**
0098      * @return the label.
0099      */
0100     QString label() const { return _label; }
0101 
0102     /**
0103      * @return the alignment.
0104      */
0105     int alignment() const { return _alignment; }
0106 
0107     /**
0108      * Set default value.
0109      */
0110     void setDefaultValue(const QVariant &value) { _default = value; }
0111 
0112     /**
0113      * @return the default value.
0114      */
0115     QVariant defaultValue() const { return _default; }
0116 
0117     /**
0118      * @return the converted value (by default the value is left
0119      * unchanged). Most of the time you don't need to reimplement this method.
0120      *
0121      * @param i the element index ("rank" for score / "id" for player)
0122      * @param value the value to convert
0123      */
0124     virtual QVariant read(uint i, const QVariant &value) const;
0125 
0126     /**
0127      * @return the string to be displayed. You may need to reimplement this
0128      * method for special formatting (different from the standard ones).
0129      *
0130      * @param i the element index ("rank" for score / "id" for player)
0131      * @param value the value to convert
0132      */
0133     virtual QString pretty(uint i, const QVariant &value) const;
0134 
0135  private:
0136     QVariant _default;
0137     QString  _label;
0138     Qt::AlignmentFlag   _alignment;
0139     Format   _format;
0140     Special  _special;
0141 
0142     class ItemPrivate;
0143     ItemPrivate *d;
0144 
0145     static QString timeFormat(uint);
0146 };
0147 
0148 //-----------------------------------------------------------------------------
0149 /**
0150  * Possible score type.
0151  * @p Won the game has been won.
0152  * @p Lost the game has been lost or has been aborted.
0153  * @p Draw the game is a draw.
0154  */
0155 enum ScoreType { Won = 0, Lost = -1, Draw = -2 };
0156 
0157 class Score;
0158  QDataStream &operator <<(QDataStream &stream, const Score &score);
0159  QDataStream &operator >>(QDataStream &stream, Score &score);
0160 
0161 /**
0162  * This class contains data for a score. You should not inherit from
0163  * this class but reimplement the methods in Highscores.
0164  */
0165 class  Score
0166 {
0167  public:
0168     explicit Score(ScoreType type = Won);
0169 
0170     ~Score();
0171 
0172     /**
0173      * @return the game type.
0174      */
0175     ScoreType type() const { return _type; }
0176 
0177     /**
0178      * Set the game type.
0179      */
0180     void setType(ScoreType type) { _type = type; }
0181 
0182     /**
0183      * @return the data associated with the named Item.
0184      */
0185     QVariant data(const QString &name) const;
0186 
0187     /**
0188      * Set the data associated with the named Item. Note that the
0189      * value should have the type of the default value of the
0190      * Item.
0191      */
0192     void setData(const QString &name, const QVariant &value);
0193 
0194     /**
0195      * @return the score value.
0196      *
0197      * Equivalent to <pre>data("score").toUInt()</pre>.
0198      */
0199     uint score() const { return data(QStringLiteral("score")).toUInt(); }
0200 
0201     /**
0202      * Set the score value.
0203      *
0204      * Equivalent to <pre>setData("score", score)</pre>.
0205      */
0206     void setScore(uint score) { setData(QStringLiteral("score"), score); }
0207 
0208     /**
0209      * @return true if this is the worst possible score (ie the default
0210      * argument of ScoreItem).
0211      */
0212     bool isTheWorst() const;
0213 
0214     /**
0215      * Comparison operator.
0216      *
0217      * @see Manager::isStrictlyLess
0218      */
0219     bool operator <(const Score &score) const;
0220 
0221  private:
0222     ScoreType  _type;
0223     QMap<QString, QVariant> _data;
0224 
0225     class ScorePrivate;
0226     ScorePrivate *d;
0227 
0228     friend class MultiplayerScores;
0229 
0230     friend  QDataStream &operator <<(QDataStream &stream, const Score &score);
0231     friend  QDataStream &operator >>(QDataStream &stream, Score &score);
0232 };
0233 
0234 class MultiplayerScores;
0235  QDataStream &operator <<(QDataStream &stream, const MultiplayerScores &score);
0236  QDataStream &operator >>(QDataStream &stream, MultiplayerScores &score);
0237 
0238 /**
0239  * This class is used to store and show scores for multiplayer games.
0240  *
0241  * Example of use:
0242  * Initialize the class:
0243  * <pre>
0244  * KExtHighscore::MultiScore ms(2);
0245  * ms.setPlayerName(0, "player 1");
0246  * ms.setPlayerName(1, "player 2");
0247  * </pre>
0248  * At the end of each game, add the score of each players:
0249  * <pre>
0250  * KExtHighscore::Score score(KExtHighscore::Won);
0251  * score.setScore(100);
0252  * ms.addScore(0, score);
0253  * score.setType(KExtHighscore::Lost);
0254  * score.setScore(20);
0255  * ms.addScore(1, score);
0256  * </pre>
0257  */
0258 class  MultiplayerScores
0259 {
0260  public:
0261     MultiplayerScores();
0262 
0263     ~MultiplayerScores();
0264 
0265     /**
0266      * Set the number of players and clear the scores.
0267      */
0268     void setPlayerCount(uint nb);
0269 
0270     /**
0271      * Set the name of player.
0272      */
0273     void setName(uint player, const QString &name);
0274 
0275     /**
0276      * Add the score of player.
0277      */
0278     void addScore(uint player, const Score &score);
0279 
0280     /**
0281      * Clear all scores.
0282      */
0283     void clear();
0284 
0285     /**
0286      * Show scores.
0287      */
0288     void show(QWidget *parent);
0289 
0290  private:
0291     QVector<uint>  _nbGames;
0292     QVector<Score> _scores;
0293 
0294     class MultiplayerScoresPrivate;
0295     MultiplayerScoresPrivate *d;
0296 
0297     friend  QDataStream &operator <<(QDataStream &stream,
0298                                     const MultiplayerScores &score);
0299     friend  QDataStream &operator >>(QDataStream &stream,
0300                                     MultiplayerScores &score);
0301 };
0302 
0303 } // namespace
0304 
0305 #endif