Perlenspiel 3.3 | Learning 09

PS.border ( x, y, width )

By default, beads are enclosed in a border one (1) pixel wide. The PS.border() command lets you specify the width for any bead border 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.

If width is an integer, the top, left, bottom and right borders of the bead are changed to width pixels, up to the current maximum border width. A width of less than one (1) completely removes the border.

If width is PS.DEFAULT, the default width (1 pixel) is applied to all borders. If width is PS.CURRENT or not supplied, the width is not changed.

Individual border control

If a bead is square (radius = 0) and has no glyph assigned, you can control the width of the top, left, bottom and right borders individually.

To do this, specify width as an object with one or more of the following properties:

.top : integer, PS.CURRENT or PS.DEFAULT
.left : integer, PS.CURRENT or PS.DEFAULT
.bottom : integer, PS.CURRENT or PS.DEFAULT
.right : integer, PS.CURRENT or PS.DEFAULT

If any property is specified as an integer, the width of the corresponding border is changed to integer pixels. The value is clamped/floored to ensure that the area of the bead visible inside the border is at least 8 pixels wide.

A value of less than one (1) hides the corresponding border.

If any property is PS.DEFAULT, the default width (1 pixel) is applied to the corresponding border. If any property is PS.CURRENT or not supplied, the width of the corresponding border is not changed.

Usage notes

1. Only square beads are allowed to have unequal border widths.

2. If you attempt to apply unequal borders to a non-square bead (radius > 0), the four borders are all changed to the width of the widest border specified.

3. The maximum border width allowed by PS.border() for each bead depends on the dimensions of the grid, the scaling of the bead, and whether or not a glyph is currently being displayed. 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 creates two rows of four beads, squares on top and circles below, all scaled to 90%. Clicking on or touching any square assigns a random width (0-32 pixels) to the top, left, bottom and right bead borders individually. Clicking on or touching any circle assigns as random width (0-32 pixels) to the entire border.

PS.init = function( system, options ) {
var x;

PS.gridSize( 4, 2 ); // set initial size
PS.scale( PS.ALL, PS.ALL, 90 );

// Change second row to circles

for ( x = 0; x < 4; x += 1 ) {
PS.radius( x, 1, 50 );
}

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

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

if ( y > 0 ) {
w = PS.random( 33 ) - 1;
PS.border( x, y, w );
PS.statusText( "width = " + w + "\n" );
}
else {
w = {
top : PS.random( 33 ) - 1,
left : PS.random( 33 ) - 1,
bottom : PS.random( 33 ) - 1,
right : PS.random( 33 ) - 1
};
PS.border( x, y, w );
PS.statusText( "top = " + w.top +
", left = " + w.left +
", bottom = " + w.bottom +
", right = " + w.right + "\n" );
}
};

Return value

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

.top : integer
.left : integer
.bottom : integer
.right : integer
.equal : boolean
.width : integer

The .top, .left, .bottom and .right properties indicate the width of the corresponding bead border, or zero (0) if the border is hidden.

If all borders are of equal width, the .equal property is set to true, and the .width property indicates the common width, or zero (0) if all borders are hidden.

If the borders are unequal, the .equal property is set to false, and the .width property indicates the width of the widest border.

PS.ERROR is returned if an error occurs.

PS.borderColor ( x, y, color )

By default, bead borders are medium gray. The PS.borderColor() command lets you specify any color for any bead border 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 border color (PS.COLOR_GRAY) is applied. If color is PS.CURRENT or not supplied, the color is not changed.

Demonstration

This demo creates an 8x8 grid of square white beads, all with 16-pixel borders. Clicking on or touching any bead assigns a random color to its border.

PS.init = function( system, options ) {
PS.gridSize( 8, 8 ); // set initial size
PS.border( PS.ALL, PS.ALL, 16 );
PS.statusText( "PS.borderColor() 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.borderColor( x, y, r, g, b ); // set border color

// Report border color in status line

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

Return value

PS.borderColor() returns a RGB triplet integer indicating the current border color of the bead.

PS.ERROR is returned if an error occurs.

PS.borderAlpha ( x, y, alpha )

By default, bead borders are completely opaque (alpha = 255). The PS.borderAlpha() command lets you specify any alpha transparency for any bead border 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's border. 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 creates an 8x8 grid of square blue beads, all with 16-pixel borders. Clicking on or touching any bead assigns a random alpha transparency to its border.

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

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

a = PS.random(256) - 1; // random 0-255
PS.borderAlpha( x, y, a ); // set border alpha

// Report border alpha in status line

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

Return value

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

PS.ERROR is returned if an error occurs.

Terms to know