add option to show 'best time' in LevelStartButton

[pixelzoom]

This was identified in a meeting with @ariel-phet on 11/5/13, and is desirable in graphing-lines.

[pixelzoom]

Priority of this is now increased. Needed asap in graphing-lines, which has a deadline of 7/31/2014.

[pixelzoom]

Proposed requirements:

(1) Add {Property} options.bestTimeProperty, which is a time in milliseconds. If the property value is null, then there is no best time.

(2) options.bestTimeProperty will be null by default.

(3) If options.bestTimeProperty is non-null and options.bestTimeProperty.get() is non-null, then the button will show the best time.

(4) Best times should be recorded by the sim for perfect-score games only.

(5) Pressing the 'Reset All' button for the game screen should reset the best time properties to null for all games levels.

Questions:

(Q1) Where should the best time be displayed? Above or below the stars?

(Q2) What does the display look like? "2:33" ? "Best time: 2:33" ? " 2:33" ?

(Q3) What does the button look like when there is no best time yet for a level? Is there just a blank space where a time will eventually be displayed?

(Q4) When timer is turned off, should best times be hidden?

[pixelzoom]

5/20/14 dev meeting: Discuss whether this feature is really necessary at next graphing-lines design meeting.

[pixelzoom]

The current proposal is to put the best time below the button, so that it doesn't occupy space on the button. Opinions?

[samreid]

I recommend someone create a mockup and post it to this issue for review, before we take the time to implement it.

[pixelzoom]

Mockup below. Ignore the style of the text, it's irrelevant. Best time (minutes:seconds) centered below each button that has a perfect score. No label prefixing the time (i.e., not 'Best time: 3:13'). If a level does not have a perfect score, no time is shown. If the timer is off, no times are shown (or recorded).

[samreid]

(Q1) Where should the best time be displayed? Above or below the stars?

As in the mockup, below seems okay to me. It may be nice if we could think of a way to show correspondence between the score and the "full stars" idea. Perhaps the time is in Gold with a black outline, like the stars?

(Q2) What does the display look like? "2:33" ? "Best time: 2:33" ? " 2:33" ?

I think just showing the text seems good, as you have it.

(Q3) What does the button look like when there is no best time yet for a level? Is there just a blank space where a time will eventually be displayed?

Just leaving it blank (background color) where no best time is available seems good, as you have it.

(Q4) When timer is turned off, should best times be hidden?

In my opinion, times should be hidden when the timer is turned off. On the other hand, if the timer is off, best times should still be recorded, and shown if the timer is turned on. It is only a slight preference, if others have good reasons not to record times when the timer is off, that's okay with me too.

[jbphet]

Mockup looks good (font excepted) and I agree with @samreid 's responses in previous entry, though I don't think it is necessary to have yellow text with black boundary. I think simple black text should suffice. Users will figure what it means pretty quickly.

[samreid]

Black text sounds great to me.

[pixelzoom]

@samreid wrote:

In my opinion, times should be hidden when the timer is turned off. On the other hand, if the timer is off, best times should still be recorded, and shown if the timer is turned on. It is only a slight preference, if others have good reasons not to record times when the timer is off, that's okay with me too.

I agree that consistency about 'best times' is desirable at the sim design level. But it's the client's responsibility to decide whether to keep track of best times when the timer is off, and when to update the bestTimeProperty that updates this button. So irrelevant to the design of the LevelStartButtonAPI.

[pixelzoom]

Work completed, see graphing-lines.SettingsNode for example use. Assigned to @jbphet for review.

[pixelzoom]

FYI… In graphing-lines, best time is not recorded if a game is played with the timer off. (See LineGameModel.updateBestTime.) As I recall, this was a Java design decision that applied to graphing-lines, balancing-chemical-equations and reactants-products-and-leftovers: If you made a decision to play a game without timing yourself, then your time will not be recorded. If someone feels strongly that this behavior needs to be changed (or standardized), create an issue or bring it up at a design meeting for group discussion.

[jbphet]

On general principle, I agree that time should not be recorded when the timer is off.

[samreid]

Yes, that time should not be displayed if a level is completed with the timer off, but please review https://github.com/phetsims/fraction-matcher/issues/57 for a related issue.

[pixelzoom]

phetsims/fraction-matcher#57 is a problem with the game flow of Fraction Matcher. If you go back to the Level Select screen, then return to Level 1, you should not be continuing with Level 1 where you left off, you should be starting a new Level 1.

[samreid]

To clarify my statement above, the time should be recorded in the model, but not displayed or saved as a best time if the timer is off. This will permit the option to turn on the timer halfway through a level as in fraction matcher.

[jbphet]

Reviewed code, and it looks good. Also tried it out on current version of Graphing Lines and it appears to work and looks aesthetically reasonable. Closing.