apps/plugins/lib/highscore.h

   1 /***************************************************************************
   2  *             __________               __   ___.
   3  *   Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
   4  *   Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
   5  *   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
   6  *   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
   7  *                     \/            \/     \/    \/            \/
   8  * $Id$
   9  *
  10  * Copyright (C) 2005 Linus Nielsen Feltzing
  11  *
  12  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License
  14  * as published by the Free Software Foundation; either version 2
  15  * of the License, or (at your option) any later version.
  16  *
  17  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  18  * KIND, either express or implied.
  19  *
  20  ****************************************************************************/
  21 #ifndef HIGHSCORE_H
  22 #define HIGHSCORE_H
  23
  24 /* see rockblox.c for the example of usage. */
  25
  26 struct highscore
  27 {
  28     char name[32];
  29     int score;
  30     int level;
  31 };
  32
  33 /* Saves the scores to a file
  34  *   - filename: name of the file to write the data to
  35  *   - scores  : scores to store
  36  *   - num_scores: number of the elements in the array 'scores'
  37  * Returns 0 on success or a negative value if an error occures
  38  */
  39 int highscore_save(char *filename, struct highscore *scores, int num_scores);
  40
  41 /* Reads the scores from a file. The file must be a text file, each line
  42  * represents a score entry.
  43  *
  44  *   - filename: name of the file to read the data from
  45  *   - scores  : where to put the read data
  46  *   - num_scores: max number of the scores to read (array capacity)
  47  *
  48  * Returns 0 on success or a negative value if an error occures
  49  */
  50 int highscore_load(char *filename, struct highscore *scores, int num_scores);
  51
  52 /* Inserts score and level into array of struct highscore in the
  53  * descending order of scores, i.e. higher scores are at lower array
  54  * indexes.
  55  *
  56  *   - score : the new score value to insert
  57  *   - level : the game level at which the score was reached
  58  *   - name  : the name of the new entry (whatever it means)
  59  *   - scores: the array of scores to insert the new value into
  60  *   - num_scores: number of elements in 'scores'
  61  *
  62  * Returns the 0-based position of the newly inserted score if it was
  63  * inserted. Returns a negative value if the score was not inserted
  64  * (i.e. it was less than the lowest score in the array).
  65  */
  66 int highscore_update(int score, int level, const char *name,
  67                      struct highscore *scores, int num_scores);
  68
  69 /* Checks whether the new score would be inserted into the score table.
  70  * This function can be used to find out whether a score with the given
  71  * value would be inserted into the score table. If yes, the program
  72  * can collect the name of the entry from the user (if it's done that
  73  * way) and then really update the score table with 'highscore_update'.
  74  *
  75  *   - score : the score value to check
  76  *   - scores: the array of existing scores
  77  *   - num_scores: number of elements in 'scores'
  78  *
  79  * Returns true iff the given score would be inserted into the score
  80  * table by highscore_update.
  81  */
  82 bool highscore_would_update(int score, struct highscore *scores,
  83                             int num_scores);
  84
  85 /* Displays a nice highscore table. In general the font is FONT_UI, but if
  86  * the highscore table doesn't fit on the the display size it uses
  87  * FONT_SYSFIXED.
  88  *
  89  *  - position : highlight position line
  90  *  - scores   : the array of existing scores
  91  *  - num_scores: number of elements in 'scores'
  92  *  - show_level: whether to display the level column or not
  93  */
  94 void highscore_show(int position, struct highscore *scores, int num_scores,
  95                     bool show_level);
  96 #endif