Perlenspiel 3.3 | Learning 21

The PS.random() function returns a random integer between 1 and the supplied value, inclusive.

The val parameter should be an integer greater than or equal to two (2). Values less than two are clamped. Non-integral values are floored.

// EXAMPLE
// Set bead to a random shade of red

PS.touch = function( x, y, data, options ) {
PS.color( x, y, PS.random(256) - 1, 0, 0 );
};

Return value

PS.random() returns a random integer in the range 1 to val, inclusive.

PS.ERROR is returned if an error occurs.

PS.makeRGB ( r, g, b )

The PS.makeRGB() function takes three color component values (in red, green and blue order) and converts them to a single RGB triplet integer.

Each parameter must be an integer in the range of 0-255 inclusive. Values outside this range are clamped. Non-integral values are floored.

// EXAMPLE
// Set bead to a random shade of green

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

rgb = PS.makeRGB( 0, PS.random(256) - 1, 0 );
PS.color( x, y, rgb );
};

Return value

PS.makeRGB() returns an RGB triplet integer in the range 0 to 0xFFFFFF inclusive, formatted RRGGBB.

PS.ERROR is returned if an error occurs.

PS.unmakeRGB ( rgb, colors )

The PS.unmakeRGB() function takes an RGB triplet integer and returns an object representing the separate red, green and blue color components.

The rgb parameter should be an RGB triplet integer in the range 0 to 0xFFFFFF inclusive. Values outside this range are clamped. Non-integral values are floored.

The colors parameter should be a valid reference to either an array or an object.

If colors is an array reference, the first three elements of the array will be populated with integers in the range of 0-255 inclusive, corresponding to the red, green and blue components of rgb:

array[0] = red : integer
array[1] = green : integer
array[2] = blue : integer

Values previously assigned to the first three array elements are lost. Any elements beyond the first three are not changed.

If colors is an object reference, the .rgb property of the object is set to the value of rgb, and the .r, .g and .b properties are populated with integers in the range of 0-255 inclusive, corresponding to the red, green and blue components of rgb:

.rgb : integer
.r : integer
.g : integer
.b : integer

Any values previously assigned to these properties are lost. Any other properties in the object are not changed.

// EXAMPLES
// Copy r/g/b values into an array

var a = [];

PS.unmakeRGB ( PS.COLOR_ORANGE, a );

PS.debug( "r = " + a[0] + ", g = " + a[1] +
", b = " + a[2] + "\n" );

// Copy r/g/b values into an object

obj = PS.unmakeRGB ( PS.COLOR_ORANGE, {} );

PS.debug( "r = " + obj.r + ", g = " + obj.g +
", b = " + obj.b + "\n" );

Return value

PS.unmakeRGB() returns the array or object passed in the colors parameter, modified as explained above.

PS.ERROR is returned if an error occurs.

PS.applyRect ( left, top, width, height, exec, ... )

The PS.applyRect() command applies a specified function to every bead within a specified rectangular region of the grid.

The required left, top, width and height parameters specify the zero-based dimensions of a rectangular region inside the grid.

If left is less than zero (0) or PS.DEFAULT, the value zero (0) is used. If left equals or exceeds the grid width, nothing happens.

If top is less than zero (0) or PS.DEFAULT, the value zero (0) is used. If top equals or exceeds the grid height, nothing happens.

If width is less than 1, nothing happens. If (left + width) is greater than the grid width or PS.DEFAULT, the value (grid_width - left) is used.

If height is less than 1, nothing happens. If (top + height) is greater than the grid height or PS.DEFAULT, the value (grid_height - top) is used.

The required exec parameter should be a reference to a JavaScript function that accepts at least two arguments specifying the zero-based x and y coordinates of a bead on the grid, respectively.

Any parameters supplied to PS.applyRect() after the exec parameter are passed as additional arguments to the exec function.

The exec function can return any value. If the function fails, it should return PS.ERROR.

Usage notes

1. PS.applyRect() is easily used with any of Perlenspiel's bead commands. Just specify the name of the command for the exec parameter, followed by the same parameters you would normally pass to the command following the x and y parameters.

2. You can also use PS.applyRect() with bead functions you write yourself. The first two arguments of your function must specify the zero-based x and y position of the bead of the grid, respectively. Any number of additional arguments can be used.

Demonstration

This demo creates a 16x16 white grid. Touch any bead to draw a randomly-colored 3x3 square of beads, centered at the position touched.

PS.init = function( system, options ) {
PS.gridSize( 16, 16 );
PS.statusText( "PS.applyRect() Demo" );
};

PS.touch = function( x, y, data, options ) {
var xsize, ysize, r, g, b;

// Clamp dimensions of rectangle

xsize = 3;
if ( x < 1 ) {
xsize = 2;
}

ysize = 3;
if ( y < 1 ) {
ysize = 2;
}

r = PS.random( 256 ) - 1;
g = PS.random( 256 ) - 1;
b = PS.random( 256 ) - 1;

PS.applyRect( x - 1, y - 1, xsize, ysize,
PS.color, r, b, g );
};

Return value

PS.applyRect() returns the result of applying the exec function to the bead in the last column and row of the specified rectangle.

If top equals or exceeds the grid height, left equals or exceeds the grid width, or either width or height are less than one (1), nothing happens and the value PS.DONE is returned.

PS.ERROR is returned if an error occurs.

PS.hex ( value, padding )

The PS.hex() function converts a number to a hexadecimal string, with optional padding.

The required value parameter can be any number. Non-integral values are floored.

The optional padding parameter should be a integer greater than or equal to one (1) indicating the minimum number of hexadecimal digits desired in the string. Values less than one are clamped. Non-integral values are floored.

If padding is PS.DEFAULT or not supplied, a minimum padding of two (2) is applied.

// EXAMPLE:
// Display the hex value of a bead's color

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

hex = PS.hex ( PS.color( x, y ), 6 );
PS.statusText( "RGB = " + hex );
};

Return value

PS.hex() returns a string representing the absolute value of value as a hexadecimal number in all upper-case characters, with a 0x prefix.

PS.ERROR is returned if an error occurs.

PS.keyRepeat ( repeat, init, delay )

The PS.keyRepeat() command lets you change the auto-repeat behavior of keyboard events.

The optional repeat parameter enables or disables key repeating. If repeat is true, any non-zero number, PS.DEFAULT or not supplied, key repeating is enabled. If repeat is false or zero (0), key repeating is disabled. If repeat is PS.CURRENT, the repeat behavior is not changed.

The optional init parameter specifies the initial time delay before key repeating begins, expressed in 1/60ths of a second. It should be an integer greater than or equal to one (1). Values less than one are clamped. Non-integral values are floored.

If init is PS.DEFAULT or not supplied, the default value (30, or 1/2 second) is used. If init is PS.CURRENT, the initial delay is not changed.

The optional delay parameter specifies the time delay between successive key repeats, expressed in 1/60ths of a second. It should be an integer greater than or equal to one (1). Values less than one are clamped. Non-integral values are floored.

If delay is PS.DEFAULT or not supplied, the default value (6, or 1/10 second) is used. If delay is PS.CURRENT, the delay is not changed.

// EXAMPLES
// Disable auto-repeat

PS.keyRepeat( false );

// Increase initial delay to 1 second

PS.keyRepeat( true, 60 );

// Increase initial delay to 2 seconds
// and repeat delay to 1/2 second

PS.keyRepeat( true, 120, 30 );

Usage notes

1. The default values of init and delay are similar to typical OS values, and should not be changed unless a specific effect is needed.

2. Specifying an init value less than the delay value is not recommended.

Return value

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

.repeat : boolean
.init : integer
.delay : integer

The .repeat property is true if key repeating is enabled, else false.

The .init and .delay properties are integers specifying the initial and successive key repeat delays, respectively, expressed in 1/60ths of a second.

PS.ERROR is returned if an error occurs.

Terms to know