API | Status Line

These functions control the display of text in the status box.

 

PS.statusText ( text )

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

Parameters:

  1. (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 ) {
   "use strict";

   // 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.

  1. (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.beadGlyphColor() returns a RGB multiplex 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 ) {
   "use strict";
   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:

  1. (optional) rate : integer, PS.CURRENT or PS.DEFAULT
  2. (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

The optional .rgb property specifies the initial color of the fade effect. It should be an RGB multiplex 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:

  1. An integer indicating the total number of steps in the fade
  2. A zero-based integer indicating the current fade step
  3. An RGB multiplex 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.

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:

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

The .rgb property is an RGB multiplex 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:

  1. text : string
  2. 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 inside the input box.

The status line automatically reverts to its normal appearance when input is complete, showing the text it was displaying before the call to PS.statusInput().

Usage notes

1. 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 );
} );