Perlenspiel 3.3 | API

PS.statusText ( text )

PS.statusText() changes and inspects the text in the status box above the grid.

Parameters:

(optional) text : one of

string
PS.DEFAULT
PS.CURRENT

Returns: string

Default: "" (empty string)

The optional text parameter specifies the text to be displayed in the status box. Any previously assigned text is replaced.

The text is centered in the status box. If the text is too wide to fit inside the box, the right edge of the text is clipped without warning.

If text is PS.DEFAULT or an empty string (""), the status box is erased.

If text is PS.CURRENT or not supplied, the status box text is unchanged.

If text is not a string, the supplied parameter is converted to a string and displayed.

Return value

PS.statusText() returns the text currently assigned to the status box, or an empty string if no text is assigned.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Display game title in status box on startup

PS.init = function( options ) {
// set up a 16 x 16 grid

PS.gridSize( 16, 16 );

// show the title

PS.statusText( "My Clever Game Title" );

// additional init code goes here
};

PS.statusColor ( color )

PS.statusColor() changes and inspects the color of the text in the status box above the grid.

(optional) color : color expression, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default: PS.COLOR_BLACK

The optional color parameter can be supplied in any of the four Perlenspiel color expression formats.

If color is PS.DEFAULT, the default color (PS.COLOR_BLACK) is applied. If color is PS.CURRENT or not supplied, the color is not changed.

Return value

PS.statusColor() returns a RGB triplet integer indicating the current status text color.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Change status text color to a random color
// on mouse click or touch

PS.touch = function( x, y, data, options ) {
var color;

color = PS.random(0xFFFFFF);
PS.statusColor( color );
};

PS.statusFade ( rate, options )

PS.statusFade() changes or inspects the color fade effect of the status line.

Parameters:

(optional) rate : integer, PS.CURRENT or PS.DEFAULT
(optional) options : object, PS.CURRENT or PS.DEFAULT

Returns : object or PS.ERROR

Default : { rate : 0, rgb : null, onEnd : null, params : null }

By default, the PS.statusColor() command changes the color of the status line instantly. You can make the color fade smoothly from one hue to the next by using PS.statusFade().

Once a fade effect is assigned to the status line with PS.statusFade(), all subsequent calls to PS.statusColor() will smoothly fade from the current color (or an optionally specified color) to the new color.

The optional rate parameter(s) specifies the rate of the fade effect in 60ths of a second. If rate is less than 1 or PS.DEFAULT, the status line fade effect is disabled. If rate is PS.CURRENT or not supplied, the currently assigned fade rate is not changed.

The optional options parameter specifies additional fade options. It should be an object with one or more of the following properties:

.rgb : RGB triplet, PS.CURRENT or PS.DEFAULT
.onStep : function, PS.CURRENT or PS.DEFAULT
.onEnd : function, PS.CURRENT or PS.DEFAULT
.params : array, PS.CURRENT or PS.DEFAULT

.rgb

The optional .rgb property specifies the initial color of the fade effect. It should be an RGB triplet integer in the range 0-0xFFFFFF inclusive. Values outside this range are clamped. Non-integral values are floored.

If .rgb is PS.DEFAULT, null or not supplied, the current status line color is used as the starting color. If .rgb is PS.CURRENT, the currently assigned start color is not changed.

.onStep

The optional .onStep property specifies a function that will be called immediately before each step of the color fade is executed. Three arguments are passed to this function in the following order:

An integer indicating the total number of steps in the fade
A zero-based integer indicating the current fade step
An RGB triplet integer indicating the current step color

Any values specified by the .params property (see below) are passed to the function as additional arguments, following the three noted above.

The value returned by the .onStep function determines how the fade effect will proceed.

A return value of false or null immediately terminates the fade, and changes the status line to its assigned color.
Any other return value allows the fade to continue normally.

If .onStep is PS.DEFAULT, null, or not supplied, the default behavior (no function call) is used. If .onStep is PS.CURRENT, the currently assigned function is not changed.

.onEnd

The optional .onEnd property specifies a function that will be called when the fade effect is completed. Any values specified by the .params property (see below) are passed to this function as arguments.

If .onEnd is PS.DEFAULT, null, or not supplied, the default behavior (no function call) is used. If .onEnd is PS.CURRENT, the currently assigned function is not changed.

.params

The optional .params property specifies the additional parameters that will be passed to the functions specified by the .onStep and/or .onEnd properties. It should be an array containing any number of elements.

If .params is PS.DEFAULT, null, or not supplied, no additional parameters are passed to the .onStep and/or .onEnd functions. If .params is PS.CURRENT, the currently assigned parameters are not changed.

If options is PS.CURRENT or not supplied, the currently assigned fade settings are not changed.

If options is PS.DEFAULT, all fade settings (except for the fade rate) are reset to their default values.

Return value

PS.statusFade() returns an object with the following properties:

.rate : integer
.rgb : integer or null
.onStep : function or null
.onEnd : function or null
.params : array or null

The .rate property indicates the current status line fade rate, zero (0) if disabled.

The .rgb property is an RGB triplet integer indicating the start color currently assigned to the fade, null if none.

The .onStep property indicates the .onStep function currently assigned to the fade, null if none.

The .onEnd property indicates the .onEnd function currently assigned to the fade, null if none.

The .params property is an array containing the additional parameters currently assigned to the .onStep and .onEnd functions, null if none.

PS.ERROR is returned if an error occurs.

PS.statusInput ( text, exec )

PS.statusInput() temporarily converts the status line to a labeled text input box.

Parameters:

text : string
exec : function

Returns: PS.OK or PS.ERROR

The text parameter specifies the label text that will be displayed to the left of the input box. Up to 16 characters of the string are displayed; any characters beyond the 16th are discarded. If an empty string ("") is supplied, a caret character (>) is displayed.

If text is not a string, the supplied parameter is converted to a string.

The exec parameter must be a function expecting one argument. This function will be called when the player presses the return key, with its argument set to the text entered. If no text was entered, or if the ESC key was pressed during text entry, an empty string ("") is passed as the argument.

Usage notes

1. When input is complete, the status line reverts to its usual appearance, showing the text it was displaying (if any) before the call to PS.statusInput().

2. Event calls to PS.keyDown() and PS.keyUp() are suspended while the status line is being used for text input.

Return value

PS.statusInput() returns PS.DONE, or PS.ERROR if an error occurs.

// EXAMPLE:
// Echo a name input by a player

PS.statusInput( "Enter name:", function ( text ) {
PS.statusText( "Name = " + text );
} );