Perlenspiel 3.3 | Learning 08

Multiple bead assignment

All of Perlenspiel's bead-related commands use x and y parameters to specify the bead you want to control.

The constant PS.ALL can be used to modify all of the beads in a given row or column, or every bead on the grid, with a single command call.

If x is specified as PS.ALL, every bead in row y is modified, and the return value is the status of the last bead in row y.

Similarly, if y is PS.ALL, every bead in column x is modified, and the return value is the status the last bead in column x.

If both x and y are PS.ALL, every bead on the grid is modified, and the return value is the status of the bead in the last column and row of the grid.

// EXAMPLES:
// Change all beads in row 2 to red

PS.color( PS.ALL, 2, PS.COLOR_RED );

// Change all beads in column 3 to green

PS.color( 3, PS.ALL, PS.COLOR_GREEN );

// Change every bead in the grid to blue

PS.color( PS.ALL, PS.ALL, PS.COLOR_BLUE );

PS.color ( x, y, color )

By default, beads are plain white. The PS.color() command lets you specify any color for any bead in the grid.

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs if either parameter is negative, or exceeds the dimensions of the grid. Multiple bead assignment is supported using PS.ALL.

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_WHITE) is applied. If color is PS.CURRENT or not supplied, the bead color is not changed.

Demonstration

This demo generates a 16x16 grid, and randomly changes the color of any bead you click or touch.

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

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

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, r, g, b ); // set bead color

// Report bead color in status line

PS.statusText( "r = " + r + ", g = " + g +
", b = " + b + "\n" );
};

Return value

PS.color() returns an RGB triplet integer indicating the current color of the bead.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Inspecting the color of the bead at coordinates 4, 5
// PS.unmakeRGB() is used to extract the r, g & b values
// from the RGB triplet returned by PS.color()

var result = PS.unmakeRGB( PS.color( 4, 5 ), {} );
PS.debug( "r = " + result.r + ", g = " + result.g +
", b = " + result.b + "\n" );

PS.alpha ( x, y, alpha )

Alpha transparency (or just alpha) refers to the opacity of a color against its background. Alpha values are expressed using the same 0-255 range used by RGB color components, with 0 corresponding to full transparency, and 255 complete opacity.

[Alpha levels]

In the above diagram, the leftmost square is completely opaque, with subsequent squares becoming more transparent. The alpha value assigned to each square is shown beneath.

By default, beads are opaque, with an alpha value of 255. The PS.alpha() command lets you specify any level of alpha transparency for any bead in the grid.

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs if either parameter is negative, or exceeds the dimensions of the grid. Multiple bead assignment is supported using PS.ALL.

The optional alpha parameter specifies the alpha transparency of the bead. It should be an integer between 0 (completely transparent) and 255 (fully opaque) inclusive. Values outside this range are clamped. Non-integral values are floored.

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

Demonstration

This demo generates a black grid with white beads. A random alpha value is assigned to each bead when you click or touch it.

PS.init = function( system, options ) {
PS.gridSize( 8, 8 ); // set initial size
PS.gridColor( PS.COLOR_BLACK );
PS.color( PS.ALL, PS.ALL, PS.COLOR_WHITE );
PS.statusColor( PS.COLOR_WHITE ); // make readable!
PS.statusText( "PS.alpha() Demo" );
};

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

a = PS.random(256) - 1; // select random alpha value
PS.alpha( x, y, a ); // apply to bead

// Report alpha in status line

PS.statusText( "alpha = " + a + "\n" );
};

Return value

PS.alpha() returns an integer in the range 0-255 inclusive indicating the current alpha transparency of the bead.

PS.ERROR is returned if an error occurs.

PS.scale ( x, y, scale )

By default, beads fill the entire area assigned to them on the grid. PS.scale() lets you control the relative scale of any bead on the grid.

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs if either parameter is negative, or exceeds the dimensions of the grid. Multiple bead assignment is supported using PS.ALL.

The optional scale parameter specifies the bead scaling. It should be an integer in the range 50 to 100 inclusive, indicating a percentage of the full-size bead width. Values outside this range are clamped. Non-integral values are floored.

If scale is PS.DEFAULT, the default scaling (100) is assigned to the bead. If scale is PS.CURRENT or not supplied, the bead scaling is not changed.

Usage notes

1. Reducing the scale of a bead also reduces the active area of the bead. Mouse clicks and/or touches outside the perimeter of the bead will not generate any event calls, even if the click or touch was inside the area of the grid assigned to the bead.

2. PS.scale() changes the size of a bead, but not the size of its glyph. Use PS.glyphScale() to change the size of a bead's glyph.

3. Scaling a bead to less than 60% may allow some glyphs to interfere with the bead border, depending on the glyph design and scaling, border width and bead shape.

4. Changing the scale of a bead also alters the maximum border width of that bead. The maximum value depends on the scaling factor, the dimensions of the grid, whether or not a glyph is currently being displayed in the bead, and the scaling of the glyph. If a glyph is visible, the border width is clamped to avoid obscuring the glyph. If no glyph is visible, the width is clamped to ensure that the area of the bead visible inside the border is at least 8 pixels wide.

Demonstration

This demo generates a grid of black beads. A random scale factor from 50 to 100 inclusive (stepped at multiples of 10 for more obvious visibility) is applied when you click or touch any bead.

PS.init = function( system, options ) {
PS.gridSize( 8, 8 ); // set initial size
PS.color( PS.ALL, PS.ALL, PS.COLOR_BLACK );
PS.statusText( "PS.scale() Demo" );
};

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

// Randomly generate a value from 50 to 100
// at multiples of 10

s = PS.random(6) - 1; // random 0 to 5
s = ( s * 10 ) + 50;
PS.scale( x, y, s );

// Report scale on status line

PS.statusText( "scale = " + s + "\n ");
};

Return value

PS.scale() returns an integer indicating the current scaling of the bead.

PS.ERROR is returned if an error occurs.

PS.radius ( x, y, radius )

By default, all beads are square, with a corner radius of zero (0). PS.radius() lets you change the shape of any bead from perfectly square to perfectly round

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs if either parameter is negative, or exceeds the dimensions of the grid. Multiple bead assignment is supported using PS.ALL.

The optional radius parameter specifies the corner radius of the bead. It should be an integer in the range 0 (perfect square) to 50 (perfect circle) inclusive. Values outside this range are clamped. Non-integral values are floored.

[Radii]

If radius is PS.DEFAULT, the default radius (0, square) is assigned to the bead. If radius is PS.CURRENT or not supplied, the radius is not changed.

Usage notes

1. Only square beads (radius = 0) are allowed to have unequal border widths. If you change the radius of a bead to a value greater than zero (0), any unequal border sides are automatically changed to the width of the widest existing border.

Demonstration

This demo generates a 4x4 grid of gray beads, scaled to 80%. A random radius 0 to 50 inclusive (stepped at multiples of 10 for more obvious visibility) is applied when you click or touch any bead.

PS.init = function( system, options ) {
PS.gridSize( 4, 4 ); // set initial size
PS.color( PS.ALL, PS.ALL, PS.COLOR_GRAY );
PS.scale( PS.ALL, PS.ALL, 90 ); // scale down a bit
PS.statusText( "PS.radius() Demo" );
};

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

// Randomly generate a value from 0 to 50
// at multiples of 10

r = PS.random(6) - 1; // random 0 to 5
r *= 10;
PS.radius( x, y, r );

// Report radius on status line

PS.statusText( "radius = " + r + "\n ");
};

Return value

PS.radius() returns an integer indicating the current radius of the bead.

PS.ERROR is returned if an error occurs.

PS.bgColor ( x, y, color )

When a bead is scaled to less than 100%, or to a corner radius of greater than zero (0). part of the area assigned to the bead in the grid may become visible around the bead's perimeter. By default, this exposed area is plain white with an alpha transparency of 0 (fully transparent), allowing the grid's background color to appear.

PS.bgColor() lets you change the background color of any bead in the grid.

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs if either parameter is negative, or exceeds the dimensions of the grid. Multiple bead assignment is supported using PS.ALL.

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_WHITE) is applied. If color is PS.CURRENT or not supplied, the color is not changed.

Usage notes

1. The background color of a bead is only exposed if the bead is scaled to less than 100%, or if the bead is non-square (that is, its radius is greater than 0).

2. By default, bead backgrounds are transparent, allowing the grid's background color to show through regardless of the background color assigned to the bead. To see the results of a call to PS.bgColor(), you must also call PS.bgAlpha() to increase the opacity.

Demonstration

This demo generates a 4x4 grid of black beads, scaled to 75% to expose the background area, with background opacity set to 255 (fully opaque). A random background color is applied when you click or touch any bead.

PS.init = function( system, options ) {
PS.gridSize( 4, 4 ); // set initial size
PS.border( PS.ALL, PS.ALL, 0 ); // no borders
PS.color( PS.ALL, PS.ALL, PS.COLOR_BLACK );
PS.scale( PS.ALL, PS.ALL, 75 ); // scale down
PS.bgAlpha( PS.ALL, PS.ALL, 255 ); // opaque
PS.statusText( "PS.bgColor() Demo" );
};

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

r = PS.random(256) - 1; // random red 0-255
g = PS.random(256) - 1; // random green
b = PS.random(256) - 1; // random blue
PS.bgColor( x, y, r, g, b ); // set bead bgColor

// Report bgColor in status line

PS.statusText( "r = " + r + ", g = " + g +
", b = " + b + "\n" );
};

Return value

PS.bgColor() returns a RGB triplet integer indicating the current background color of the bead.

PS.ERROR is returned if an error occurs.

PS.bgAlpha ( x, y, alpha )

When a bead is scaled to less than 100%, or to a corner radius of greater than zero (0). part of the area assigned to the bead in the grid may become visible around the bead's perimeter. By default, this exposed area is plain white with an alpha transparency of 0 (fully transparent), allowing the grid's background color to appear.

PS.bgAlpha() lets you change the background alpha of any bead in the grid.

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs if either parameter is negative, or exceeds the dimensions of the grid. Multiple bead assignment is supported using PS.ALL.

The optional alpha parameter specifies the alpha transparency of the bead. It should be an integer between 0 (completely transparent) and 255 (fully opaque) inclusive. Values outside this range are clamped. Non-integral values are floored.

If alpha is PS.DEFAULT, the default background alpha (PS.ALPHA_TRANSPARENT, 0) is applied. If alpha is PS.CURRENT or not supplied, the alpha is not changed.

Usage notes

1. The background color of a bead is only exposed if the bead is scaled to less than 100%, or if the bead is non-square (that is, its radius is greater than 0).

2. By default, bead backgrounds are transparent, allowing the grid's background color to show through regardless of the background color assigned to the bead. To see the results of a call to PS.bgColor(), you must also call PS.bgAlpha() to increase the opacity.

Demonstration

This demo generates a 4x4 grid of black beads, scaled to 75% to expose the background area, with background colors randomly assigned. A random background alpha is applied when you click or touch any bead.

PS.init = function( system, options ) {
var x, y, r, g, b;

PS.gridSize( 4, 4 ); // set initial size
PS.border( PS.ALL, PS.ALL, 0 ); // no borders
PS.color( PS.ALL, PS.ALL, PS.COLOR_BLACK );
PS.scale( PS.ALL, PS.ALL, 75 ); // scale down
PS.bgAlpha( PS.ALL, PS.ALL, 255 ); // start opaque

// Assign random bgColor to each bead

for ( y = 0; y < 4; y += 1 ) {
for ( x = 0; x < 4; x += 1 ) {
r = PS.random(256) - 1;
g = PS.random(256) - 1;
b = PS.random(256) - 1;
PS.bgColor( x, y, r, g, b );
}
}

PS.statusText( "PS.bgAlpha() Demo" );
};

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

a = PS.random(256) - 1; // random 0-255
PS.bgAlpha( x, y, a );

// Report alpha on status line

PS.statusText( "bgAlpha = " + a + "\n" );
};

Return value

PS.bgAlpha() returns an integer in the range 0-255 inclusive indicating the current background alpha of the bead.

PS.ERROR is returned if an error occurs.

Terms to know

Multiple bead assignment
PS.ALL
PS.color()
alpha transparency
PS.alpha()
PS.ALPHA_OPAQUE
PS.ALPHA_TRANSPARENT
PS.scale()
PS.radius()
corner radius
PS.bgColor()
PS.bgAlpha()