[Kde-games-devel] A new highscore manager - KScoreManager

[Parker Coates]

2008/5/1 Matt Williams <matt at milliams.com>:
>  After some discussion with Albert, I've separated the UI from the management
>  even further. The functions for accessing the information about the scores
>  has now been made private. I've then created an abstract class called
>  KAbstractScoreBoard which is a friend of KScoreManager so that it can access
>  its private functions. This way, whatever funky display widget you can think
>  of will just have to subclass KAbstractScoreBoard.
>
>  This way, all the display based functions and enums can be moved to
>  KAbstractScoreBoard.

Unfortunately, friendship isn't inherited.
(http://www.parashift.com/c++-faq-lite/friends.html#faq-14.4) So while
KAbstractScoreBoard will have friend access to KScoreManager, any
classes derived from it won't. I had thought of using friendship to
clean up the API a while ago, but couldn't find a way to make it work
other than declaring every possible display class a friend. But of
course this would mean new classes couldn't be added without modifying
the KScoreManager header, which is nasty.

Unless, of course, Albert knows a way around this.

>  Do you think that the setMessage() function and the OutcomeFlag enum should be
>  moved as well since they're UI specific?

Yes.

>  > - Instead of
>  >
>  >  KScoreBoardDialog board();
>  >  board.show(KScoreDialog::HighlightLastScore |
>  > KScoreDialog::DisplayMessage);
>  >
>  > I'd prefer
>  >
>  >  KScoreBoardDialog board(KScoreDialog::HighlightLastScore |
>  > KScoreDialog::DisplayMessage);
>  >  board.show();
>  >
>  > as these seem like properties of the dialog that are unlikely to
>  > change during it's lifetime.
>
>  The reason I did it this way is that I've noticed people have a tendency of
>  storing dialogs such as this as member variables of their mainwindow class
>  (in fact that was a cause of bugs in a number of games using KScoreDialog).
>  To allow people to do this (or at least to avoid bugs _if_ they do) I decided
>  to build the dialog on the show() command rather than construction. People
>  can then use the same object for displaying the board (passing nothing to the
>  show() function) and displaying the end-of-game congratulation message/enter
>  name box (by passig the relevant flags to show()).
>
>  Now, honestly I don't like this way of doing it but I don't know of a way to
>  prevent people from using the Dialog as a member variable.
>
>  Suggestions on this are very much welcome.

Well, you could always make the user call m_board->setDisplayOptions(
KScoreDialog::HighlightLastScore | KScoreDialog::DisplayMessage ) if
they wanted to modify the dialog before calling m_board->show(). This
really isn't a major issue, more style than anything. I guess my
primary objection to adding the display options to the show() method
is that it's inherited from QDialog and I feel modifying inherited
methods without a really good reason is likely to clash with users
expectations. Also if you override show() and add parameters you
should probably do the same to exec() for consistency's sake.

This just reminded me of another potential use case. What if I wanted
to create a highscore dockwidget? The widget might only ever get
show()n once, so it would be nice if it could refresh the scores
automatically. Therefore, I still think KScoreManager should have a
scoresChanged() signal, just as a convenient way to keep things in
sync.

>  > - Dmitry's "leader board" style dialog should probably be it's own UI
>  > class (KLevelScoreDialog?), instead of an option passed to
>  > KScoreBoardDialog. It would certainly keep the implementation a lot
>  > cleaner.
>
>  Its certainly a possibility. Though this depends on the resolution the the
>  previous point.

I don't really see how this depends on the previous point. Could you explain?

>  > - Does calling "submitName( QString() )" submit a score with an empty
>  > name? Use the presupplied player name if one exists? Use
>  > "i18n("Anonymous")"? Or does it reject the current score? If not, will
>  > there be a way to cancel the last submitted score? I'm not sure that
>  > that's necessary, but someone did ask for it earlier.
>
>  submitName( QString() ) would submit the score with an empty name field.
>  There's not currently a way to cancel a score, though you're right, it's
>  probably a required feature.

I, personally, don't care for it. I think high scores should be
recorded regardless of what the user wants, but if others think its
important, they should probably argue their case. I guess the thread I
was thinking of was back in August,
http://lists.kde.org/?l=kde-games-devel&m=118708126008359&w=2

>  > - What does KScoreManager do if "submitName" is never called? If a new
>  > score is added while "isWaitingForName()" is true, what do we do about
>  > the last score? I guess these are situations that should never occur
>  > in a properly coded application, but they should probably be handled
>  > properly regardless.
>
>  In this case the first score would be saved with whatever the default name is
>  (in order: the Name field of ScoreInfo, the LastPlayer field from the file,
>  info from KUser).

Presumably, the display classes will want to prepopulate the line edit
with the appropriate default value, but how will they get it? Will the
default name be preloaded into the score as soon as it's addScore()d,
so that it can be extracted from scores()? Or should there be (yet)
another method like QString newestScoredefaultName()?

Parker