libkdegames Library API Documentation

KExtHighscore::Manager Class Reference

This class manages highscores and players entries (several players can share the same highscores list if the libkdegame library is built to support a common highscores file; NOTE that to correctly implement such feature we probably need a locking mechanism in KHighscore). More...

#include <kexthighscore.h>

List of all members.

Public Types

enum  ScoreTypeBound { ScoreNotBound, ScoreBound }
enum  ShowMode { AlwaysShow, NeverShow, ShowForHigherScore, ShowForHighestScore }
enum  ScoreType { Normal, MinuteTime }
enum  ItemType { ScoreDefault, MeanScoreDefault, BestScoreDefault, ElapsedTime }
enum  PlayerItemType { MeanScore, BestScore }
enum  LabelType { Standard, I18N, WW, Icon }

Public Methods

 Manager (uint nbGameTypes=1, uint maxNbEntries=10)
virtual ~Manager ()
void setWWHighscores (const KURL &url, const QString &version)
void setTrackLostGames (bool track)
void showStatistics (bool show)
void setScoreHistogram (const QMemArray< uint > &scores, ScoreTypeBound type)
void setShowMode (ShowMode mode)
void setScoreType (ScoreType type)
void setScoreItem (uint worstScore, Item *item)
void addScoreItem (const QString &name, Item *item)
void setPlayerItem (PlayerItemType type, Item *item)
virtual bool isStrictlyLess (const Score &s1, const Score &s2) const
virtual QString gameTypeLabel (uint gameType, LabelType type) const

Static Public Methods

ItemcreateItem (ItemType type)

Protected Methods

virtual void convertLegacy (uint gameType)
void submitLegacyScore (const Score &score) const
virtual void additionalQueryItems (KURL &url, const Score &score) const

Static Protected Methods

void addToQueryURL (KURL &url, const QString &item, const QString &content)

Friends

class ManagerPrivate


Detailed Description

This class manages highscores and players entries (several players can share the same highscores list if the libkdegame library is built to support a common highscores file; NOTE that to correctly implement such feature we probably need a locking mechanism in KHighscore).

You need one instance of this class during the application lifetime ; in main() just insert

   KExtHighscore::Manager highscoresManager;
with the needed arguments. Use the derived class if you need to reimplement some of the default methods.

This class has three functions :

The highscores and the players lists contain several items described by the Item class.

The highscores list contains by default :

You can replace the score item (for e.g. displaying it differently) with setScoreItem or add an item with addScoreItem.

The players list contains :

You can replace the best score and the mean score item by calling setPlayerItem.

To submit a new score at game end, just construct a Score, set the score data and then call submitScore().

     KExtHighscore::Score score(KExtHighscore::Won);
     score.setScore(myScore);
     KExtHighscore::submitScore(score, widget);
You only need to set the score value with Score::setScore() and the value of the items that you have optionnally added with Score::setData() ; player name and date are set automatically.

Definition at line 138 of file kexthighscore.h.


Member Enumeration Documentation

enum KExtHighscore::Manager::ScoreType
 

Score type (.

See also:
setScoreType). Normal default score (unsigned integer without upper bound) MinuteTime score by time bound at 3599 seconds (for e.g. kmines)

Definition at line 204 of file kexthighscore.h.

enum KExtHighscore::Manager::ItemType
 

Some predefined item types.

Score default item for the score in the highscores list. MeanScore default item for the mean score (only show one decimal and 0 is shown as "--". BestScore default item for the best score (0 is shown as "--"). Optionnal item for elapsed time (maximum value is 3599 seconds).

Definition at line 220 of file kexthighscore.h.

enum KExtHighscore::Manager::LabelType
 

Possible type of label (.

See also:
gameTypeLabel). Standard label used in config file. I18N label used to display the game type. WW label used when contacting the world-wide highscores server. Icon label used to load the icon corresponding to the game type.

Definition at line 268 of file kexthighscore.h.


Constructor & Destructor Documentation

KExtHighscore::Manager::Manager uint    nbGameTypes = 1,
uint    maxNbEntries = 10
 

Constructor.

Parameters:
nbGameTypes  the number of different game types (usually one). For example KMines has easy, normal and expert levels.
maxNbEntries  the maximum numbers of highscores entries (by game types)

Definition at line 107 of file kexthighscore.cpp.


Member Function Documentation

void KExtHighscore::Manager::setWWHighscores const KURL &    url,
const QString   version
 

Set the world-wide highscores.

Note: should be called at construction time.

Parameters:
url  the web server url
version  the game version which is sent to the wrb server (it can be useful for backward compatibility on the server side).

Definition at line 133 of file kexthighscore.cpp.

void KExtHighscore::Manager::setTrackLostGames bool    track
 

Set if the number of lost games should be track for the world-wide highscores statistics.

By default, there is no tracking.

Note: should be called at construction time.

Definition at line 123 of file kexthighscore.cpp.

void KExtHighscore::Manager::showStatistics bool    show
 

Set if the statistics tab should be shown in the highscores dialog.

You only want to show this tab if it makes sense to lose or to win the game (for e.g. it makes no sense for a tetris game but it does for a minesweeper game).

Note: should be called at construction time.

Definition at line 128 of file kexthighscore.cpp.

void KExtHighscore::Manager::setScoreHistogram const QMemArray< uint > &    scores,
ScoreTypeBound    type
 

Set the ranges for the score histogram.

Note: should be called at construction time.

Definition at line 145 of file kexthighscore.cpp.

References QMemArray::size().

void KExtHighscore::Manager::setShowMode ShowMode    mode
 

Set how the highscores dialog is shown at game end.

By default, the mode is ShowAtHigherScore.

Note: should be called at construction time.

Definition at line 154 of file kexthighscore.cpp.

void KExtHighscore::Manager::setScoreType ScoreType    type
 

Set score type.

Helper method to quickly set the type of score.

Note: should be called at construction time.

Definition at line 159 of file kexthighscore.cpp.

References createItem(), setPlayerItem(), KExtHighscore::Item::setPrettyFormat(), and setScoreItem().

Item * KExtHighscore::Manager::createItem ItemType    type [static]
 

Create a predefined item.

Definition at line 191 of file kexthighscore.cpp.

References KExtHighscore::Item::setPrettyFormat(), and KExtHighscore::Item::setPrettySpecial().

Referenced by setScoreType().

void KExtHighscore::Manager::setScoreItem uint    worstScore,
Item   item
 

Replace the default score item in the highscores list by the given one.

worstScore is the worst possible score. By default it is 0.

Note : This method should be called at construction time.

Definition at line 216 of file kexthighscore.cpp.

References KExtHighscore::Item::setDefaultValue().

Referenced by setScoreType().

void KExtHighscore::Manager::addScoreItem const QString   name,
Item   item
 

Add an item in the highscores list (it will add a column to this list).

Note : This method should be called at construction time.

Definition at line 226 of file kexthighscore.cpp.

void KExtHighscore::Manager::setPlayerItem PlayerItemType    type,
Item   item
 

Replace an item in the players list.

Note : This method should be called at construction time.

Definition at line 231 of file kexthighscore.cpp.

References KExtHighscore::Item::defaultValue(), KExtHighscore::Item::setDefaultValue(), and QVariant::toUInt().

Referenced by setScoreType().

bool KExtHighscore::Manager::isStrictlyLess const Score   s1,
const Score   s2
const [virtual]
 

Returns:
true if the first score is strictly worse than the second one. By default return
s1.score()<s2.score()
. You can reimplement this method if additional items added to Score can further differentiate the scores (for e.g. the time spent).
Note that you do not need to use directly this method, simply write
s1<s2
since the operator calls this method.

Definition at line 186 of file kexthighscore.cpp.

References KExtHighscore::Score::score().

QString KExtHighscore::Manager::gameTypeLabel uint    gameType,
LabelType    type
const [virtual]
 

Returns:
the label corresponding to the game type. The default implementation works only for one game type : you need to reimplement this method if the number of game types is more than one.

Definition at line 249 of file kexthighscore.cpp.

virtual void KExtHighscore::Manager::convertLegacy uint    gameType [inline, protected, virtual]
 

This method is called once for each player (ie for each user).

You can reimplement it to convert old style highscores to the new mechanism (

See also:
submitLegacyScore). By default this method does nothing.
Parameters:
gameType  the game type

Definition at line 285 of file kexthighscore.h.

void KExtHighscore::Manager::submitLegacyScore const Score   score const [protected]
 

This method should be called from convertLegacy.

It is used to submit an old highscore (it will not be send over the network). For each score do something like:

 Score score(Won);
 score.setScore(oldScore);
 score.setData("name", name);
 submitLegacyScore(score);
Note that here you can set the player "name" and the highscore "date" if they are known.

Definition at line 181 of file kexthighscore.cpp.

virtual void KExtHighscore::Manager::additionalQueryItems KURL &    url,
const Score   score
const [inline, protected, virtual]
 

This method is called before submitting a score to the world-wide highscores server.

You can reimplement this method to add an entry with addToQueryURL. By default this method does nothing.

Parameters:
url  the URL to query
score  the score to be submitted.

Definition at line 310 of file kexthighscore.h.

void KExtHighscore::Manager::addToQueryURL KURL &    url,
const QString   item,
const QString   content
[static, protected]
 

Add an entry to the url to be submitted (.

See also:
additionalQueryItems).
Parameters:
url  the URL to query
item  the item name
content  the item content

Definition at line 263 of file kexthighscore.cpp.

References QString::isEmpty().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for libkdegames Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat May 1 10:06:40 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003