![[Logo]](images/logosm.png)
Perlenspiel³Learning 11: Status line text, color and input
This page describes the commands for setting the text and color of the status line, and for using it to obtain text input.
By default, the status line is empty. The PS.statusText() command lets you assign a short string of text to the status box.
The optional text parameter specifies the text to be displayed in the status box. Any previously assigned text is replaced.
If text is PS.DEFAULT or an empty string (""), the status box is emptied. 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.
Usage notes
1. Text is centered in the status box. It is limited to a single line. If the text is too wide to fit inside the box, the right edge of the text is clipped without warning.
2. If the status line color is close to or identical to the grid background color, the text may become difficult or impossible to read.
Demonstration
Click or touch any bead to see its coordinates reported in the status line.
![[Run Demo]](images/runarrow.png)
PS.init = function( system, options ) {
PS.gridSize( 8, 8 ); // set initial size
PS.statusText( "PS.statusText() Demo" );
};
PS.touch = function( x, y, data, options ) {
PS.statusText( "You touched bead " + x + ", " + y );
};
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.
By default, any text displayed in the status line is black. The PS.statusColor() command lets you assign any color to the text.
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.
Demonstration
This demo creates an 8x8 grid of randomly-colored beads. Click or touch any bead to see its color reported in the status line, with the text displayed in the matching color.
PS.init = function( system, options ) {
var x, y, hue;
PS.gridSize( 8, 8 ); // set initial size
PS.gridColor( PS.COLOR_BLACK );
PS.border( PS.ALL, PS.ALL, 0 ); // no borders
// Assign random color to each bead
// Uses an RGB object to specify color
// Saves that object in bead data for later use
for ( y = 0; y < 8; y += 1 ) {
for ( x = 0; x < 8; x += 1 ) {
hue = {
r : PS.random( 256 ) - 1, // random red 0-255
g : PS.random( 256 ) - 1, // random green
b : PS.random( 256 ) - 1 // random blue
}
PS.color( x, y, hue ); // set bead color
PS.data( x, y, hue ); // save in bead data
}
}
PS.statusText( "PS.statusColor() Demo" );
PS.statusColor( PS.COLOR_WHITE );
};
PS.touch = function( x, y, data, options ) {
// Bead data contains an RGB object
// Change status line color and report color
PS.statusColor( data );
PS.statusText( "r = " + data.r + ", g = " + data.g +
", b = " + data.b + "\n" );
};
Return value
PS.statusColor() returns a RGB triplet integer indicating the current status text color.
PS.ERROR is returned if an error occurs.
It is often useful to allow users to input text into a game, such as their name. PS.statusInput() provides a way to do this, temporarily converting the status line to a labeled, single-line text input box.
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, 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.
Demonstration
Click or touch any bead to convert the status line to an input box requesting a name. When input is complete, the status line reports the text that was input.
PS.init = function( system, options ) {
PS.gridSize( 8, 8 ); // set initial size
PS.statusText( "Touch a bead to enter your name" );
};
PS.touch = function( x, y, data, options ) {
PS.statusInput( "Name:", function ( result ) {
PS.statusText( "Welcome, " + result +
"!" );
} );
};
Return value
PS.statusInput() returns PS.DONE, or PS.ERROR if an error occurs.