totalcross.game

Class Options

java.lang.Object

totalcross.util.Properties

totalcross.game.Options

public class Options
extends Properties

The game options management class.

The options are stored in a waba PDBFile object which is linked to the application through the software creatorID. This causes the options database deletion when the game with the same creatorID is erased.

The complete database name is composed by the game name 'appl' and its creatorID, both provided during the engine initialization via the GameEngineClient interface.
The options database name is : ${appl}_OPT.${creatorID}.DATA

You can find a complete game API sample named 'Scape' in the TotalCross samples folder.
Here is some sample code:

 import totalcross.game.*;
 import totalcross.util.props.*;
 ...

 <i>public class Ping extends <U>GameEngine</U></i> {

 // constructor
 public Ping()
 {
   totalcross.sys.Settings.setPalmOSStyle(true);

   // define the game API setup attributes

   gameName             = "Ping";

   // when not run on device, appCreatorId does not always return the same value.

   gameCreatorID        = Settings.onJavaSE ? totalcross.sys.Settings.appCreatorId:"PiNg";

   gameVersion          = 100;   // v1.00
   gameHighscoresSize   = 7;     // store the best 7 highscores
   gameRefreshPeriod    = 75;    // 75 ms refresh periods
   gameIsDoubleBuffered = true;  // used double buffering to prevent flashing display
   gameDoClearScreen    = true;  // screen is cleared before each frame display
   gameHasUI            = false; // no UI elements, frame displays are optimized
   ...
 }

 // declare 2 game settings

 protected <B>Properties.Str</B>      optUserName;
 protected <B>Properties.Boolean</B>  optSound;

 //---------------------------------------------------------
 // overload the API's game init event.
 // this function is called when the game is launched.
 //---------------------------------------------------------

 <i>public void onGameInit()</i> {

   // access the game settings: 'username' & 'sound'
   // if the properties do not yet exist, the default values are used

   <B>Options</B> settings=<U>getOptions</U>();

   optUserName = settings.<B>declareString</B>    ("userName","noname");
   optSound    = settings.<B>declareBoolean</B>   ("sound",false);
   ...

   if (optSound.<B>value</B>) Sound.tone(1520,10);

  }
 }
 

Nested Class Summary

Nested classes/interfaces inherited from class totalcross.util.Properties

Properties.Boolean, Properties.Double, Properties.Int, Properties.Long, Properties.Str, Properties.Value

Field Summary

Fields

Modifier and Type	Field and Description
int	newVersion The options database new version number.
int	oldVersion The options database old version number.

Fields inherited from class totalcross.util.Properties

MAX_PROPS

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Options(GameEngine engine)

Method Summary

Modifier and Type	Method and Description
void	close() closes the settings database.
Properties.Boolean	declareBoolean(java.lang.String name, boolean value) Declare a boolean option. This function tries to lookup the property in the Options database. If it fails, a new property with the default value specified is created.
Properties.Double	declareDouble(java.lang.String name, double value) Declare a double option. This function tries to lookup the property in the Options database. If it fails, a new property with the default value specified is created.
Properties.Int	declareInteger(java.lang.String name, int value) Declare an integer option. This function tries to lookup the property in the Options database. If it fails, a new property with the default value specified is created.
Properties.Long	declareLong(java.lang.String name, long value) Declare a long option. This function tries to lookup the property in the Options database. If it fails, a new property with the default value specified is created.
Properties.Str	declareString(java.lang.String name, java.lang.String value) Declare a string option. This function tries to lookup the property in the Options database. If it fails, a new property with the default value specified is created.
Properties.Value	getProp(java.lang.String key) Get a property value given the key.
boolean	save() stores the settings database.

Methods inherited from class totalcross.util.Properties

clear, dumpKeysValues, get, getKeys, load, load, put, remove, save, size

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

newVersion

public int newVersion

The options database new version number.

oldVersion

public int oldVersion

The options database old version number.

Constructor Detail

Options

protected Options(GameEngine engine)

Method Detail

declareBoolean

public Properties.Boolean declareBoolean(java.lang.String name,
                                         boolean value)

Declare a boolean option.
This function tries to lookup the property in the Options database.
If it fails, a new property with the default value specified is created.

Parameters:

name - the property name.

value - the property default value.

Returns:

a boolean property object.

declareLong

public Properties.Long declareLong(java.lang.String name,
                                   long value)

Declare a long option.
This function tries to lookup the property in the Options database.
If it fails, a new property with the default value specified is created.

Parameters:

name - the property name.

value - the property default value.

Returns:

a long property object.

declareInteger

public Properties.Int declareInteger(java.lang.String name,
                                     int value)

Declare an integer option.
This function tries to lookup the property in the Options database.
If it fails, a new property with the default value specified is created.

Parameters:

name - the property name.

value - the property default value.

Returns:

an integer property object.

declareDouble

public Properties.Double declareDouble(java.lang.String name,
                                       double value)

Declare a double option.
This function tries to lookup the property in the Options database.
If it fails, a new property with the default value specified is created.

Parameters:

name - the property name.

value - the property default value.

Returns:

a double property object.

declareString

public Properties.Str declareString(java.lang.String name,
                                    java.lang.String value)

Declare a string option.
This function tries to lookup the property in the Options database.
If it fails, a new property with the default value specified is created.

Parameters:

name - the property name.

value - the property default value.

Returns:

a string property object.

getProp

public Properties.Value getProp(java.lang.String key)

Get a property value given the key.

Parameters:

key - name of the property

Returns:

Value that can be casted to Properties.Str, Properties.Int,... depending on the value type, that can be retrieved with the type read-only property.

save

public boolean save()

stores the settings database.

Returns:

false if an error occurs

close

public void close()
           throws IOException

closes the settings database.

Throws:

IOException