Development/Tutorials/Games/Highscores: Difference between revisions

    From KDE TechBase
    (KScoreDialog Tutorial)
    m (Prerequisites)
    Line 5: Line 5:
    name=High Scores|
    name=High Scores|


    pre=[[Development/Tutorials/Programming_Tutorial_KDE_4|Introduction to KDE4 programming]]|
    pre=[[Development/Tutorials/Programming_Tutorial_KDE_4|Introduction to KDE4 programming]], [[Projects/Games/KStandardGameAction|KStandardGameAction Tutorial]]|


    next=|  
    next=|  

    Revision as of 23:50, 17 April 2007

    High Scores
    Tutorial Series   KDE Games
    Previous   Introduction to KDE4 programming, KStandardGameAction Tutorial
    What's Next  
    Further Reading   KScoreDialog

    Abstract

    This tutorial will explain how to use the high score system built into kdegames in your application.

    KScoreDialog

    The high score system is provided through the KScoreDialog class. It is intended to be a lightweight solution and offers the following abilities:

    1. Grouping of scores (for different difficulty levels etc.)
    2. Standard fields: Name, Level, Date, Time, Score
    3. Custom fields (e.g. number of moves)

    Usage

    Displaying Scores

    To display the high score table, it's as simple as two lines of code.

    1. include <KScoreDialog>

    void showHighscores() {

     KScoreDialog ksdialog(KScoreDialog::Name | 
                           KScoreDialog::Score,
                           this);
     ksdialog.exec();
    

    } In order to comply with the kdegames standards, you should use a KStandardGameAction to launch this function. This will set up the icons and toolbars correctly. See the KStandardGameAction tutorial for more information on this.

    1. include <KStandardGameAction>

    void setupActions() {

     KStandardGameAction::highscores(this, 
                          SLOT(showHighscores()), 
                          actionCollection());
     setupGUI();
    

    }

    Simplest way to add a score

    The simplest way to add a new score to the table is as follows:

    1. include <KScoreDialog>

    void newHighscore() {

     KScoreDialog ksdialog(KScoreDialog::Name | 
                           KScoreDialog::Score, this);
     ksdialog.addScore(playersScore);
     ksdialog.exec();
    

    } This will add the score playersScore to the high score table and then launch the dialog. If it is the first score to be entered on the table, a blank line-edit will be provided for the player to enter their name, otherwise the line-edit will still be provided but the player's name will be automatically filled in.

    Passing name by code

    If you want to suggest a name programatically you can do so by using the KScoreDialog::FieldInfo type. It's easy to use, for example:

    1. include <KScoreDialog>

    void newHighscore() {

     KScoreDialog ksdialog(KScoreDialog::Name | 
                           KScoreDialog::Score, this);
     
     KScoreDialog::FieldInfo scoreInfo;
     scoreInfo[KScoreDialog::Name] = "Matt";
     scoreInfo[KScoreDialog::Score].setNum(playersScore);
     
     ksdialog.addScore(scoreInfo);
    

    }

    And in this same way you can display other default fields by passing them to the KScoreDialog constructor and adding the information to your KScoreDialog::FieldInfo. For example, to display the level the player got to:

    1. include <KScoreDialog>

    void newHighscore() {

     KScoreDialog ksdialog(KScoreDialog::Name | 
                           KScoreDialog::Score |
                           KScoreDialog::Level, this);
     
     KScoreDialog::FieldInfo scoreInfo;
     scoreInfo[KScoreDialog::Name] = "Matt";
     scoreInfo[KScoreDialog::Score].setNum(playersScore);
     scoreInfo[KScoreDialog::Level].setNum(levelAttained);
     
     ksdialog.addScore(scoreInfo);
    

    }

    Custom fields

    Since there are only a set number of standatd fields it is possible to add you own custom fields. For example you may want to put the number of moves the player made on the table. This is done through the KScoreDialog::addField() function.

    1. include <KScoreDialog>

    void newHighscore() {

     KScoreDialog ksdialog(KScoreDialog::Name | 
                           KScoreDialog::Score, this);
     
     KScoreDialog::FieldInfo scoreInfo;
     scoreInfo[KScoreDialog::Name] = "Matt";
     scoreInfo[KScoreDialog::Score].setNum(playersScore);
     
     ksdialog.addField(KScoreDialog::Custom1, 
                       "Num of Moves", "moves");
     scoreInfo[KScoreDialog::Custom1].setNum(numMoves);
     
     ksdialog.addScore(scoreInfo);
    

    } The first argument to KScoreDialog::addField() must be from KScoreDialog::Custom1 to KScoreDialog::Custom5, the second is the text that will appear on the high score table at the head of the column and the last argument is a unique identify for the field. After that, it is added to your KScoreDialog::FieldInfo in the same way as before.