API | Beads

These commands let you change the appearance and behavior of beads.

Bead commands

Border commands

Glyph commands

Multiple bead assignment

Bead commands use x and y parameters to specify the bead you want to control.

The Perlenspiel 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 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.

The handy PS.applyRect() utility lets you apply any function to a specific rectangular region of the grid.

 

PS.color ( x, y, color )

PS.color() changes and inspects the color of beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) color : color expression, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.COLOR_WHITE

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 Perlenspiel’s four 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.

Return value

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

PS.ERROR is returned if an error occurs.

// EXAMPLES:
// Using different formats to change bead colors

// Set bead to orange using explicit RGB parameters

PS.color( x, y, 255, 192, 64 );
PS.color( x, y, 0xFF, 0xC0, 0x40 ); // hex notation

// Set bead to orange using an RGB triplet

PS.color( x, y, 0xFFC040 );
PS.color( x, y, PS.COLOR_ORANGE );

// Change only the green component of bead's color

PS.color( x, y, PS.CURRENT, 32, PS.CURRENT );

// Report the color components of a bead

var color = PS.unmakeRGB( PS.color( x , y ), {} );

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

 

PS.alpha ( x, y, alpha )

PS.alpha() changes and inspects the alpha transparency assigned to beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) alpha : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.ALPHA_OPAQUE

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.

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.fade ( x, y, rate, options )

PS.fade() changes or inspects the color fade effect of beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) rate : integer, PS.CURRENT or PS.DEFAULT
  4. (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.color() and PS.alpha() commands change the color of a bead instantly. You can make the color fade smoothly from one hue to the next by using PS.fade().

Once a color fade effect is assigned to a bead with PS.fade(), all subsequent calls to PS.color() and PS.alpha() will smoothly fade from the current color (or an optionally specified color) to the new color.

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 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 bead's 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 triplet 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 bead 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 triplet 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.fade() returns an object with the following properties:

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

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

// EXAMPLE
// Fade bead 0, 0 to a random color
// when any bead on the grid is clicked.
// Status line reports when fade is complete.

PS.init = function ( system, options ) {
 // set up a 10 x 10 grid

 PS.gridSize( 10, 10 );

 // set 2-sec fade rate and onEnd function
 // on bead 0, 0

 PS.fade( 0, 0, 120, { onEnd : fadeReporter } );

 // additional init code goes here
};

// onEnd function for end-of-fade report

function fadeReporter () {
 PS.statusText( "Fade complete" );
};

PS.touch = function ( x, y, data, options ) {
 // Erase status line

 PS.statusText( "" );

 // Change bead 0, 0 to random color

 PS.color( 0, 0, PS._random( 0xFFFFFF ) );
};

 

PS.scale ( x, y, scale )

PS.scale() changes and inspects the scaling of beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) scale : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : 100 (full size)

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

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 )

PS.radius() changes and inspects the corner radius of beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) radius : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : 0 (perfect square)

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.

Return value

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

PS.ERROR is returned if an error occurs.

 

PS.minimum ( x, y, minimum )

PS.minimum() changes and inspects the minimum pixel size of beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) minimum : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : 8

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 minimum parameter specifies the minimum size of the bead in pixels. It should be an integer in the range 0 to 512 inclusive. Values outside this range are clamped. Non-integral values are floored.

If minimum is PS.DEFAULT, the default minimum size (8 pixels) is assigned to the bead. If minimum is PS.CURRENT or not supplied, the minimum bead size is not changed.

Usage notes

1. Changing the minimum size of a bead also changes its maximum border size. If the value specified by minimum exceeds the effective maximum size of the bead (based on the current grid dimensions and bead scaling), the minimum size is clamped to the effective maximum, and the maximum border size becomes zero (0), thereby disabling the display of any borders.

Return value

PS.minimum() returns an integer indicating the current minimum size of the bead in pixels.

PS.ERROR is returned if an error occurs.

 

PS.bgColor ( x, y, color )

PS.bgColor() changes and inspects the background color of scaled and/or non-square beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) color : color expression, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.COLOR_WHITE

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.

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.

// EXAMPLE:
// Set the background color of a scaled, circular bead
// to a opaque color different from the grid color

PS.gridColor( PS.COLOR_BLUE ); // blue grid
PS.scale( 0, 0, 75 ); // 75% scaling
PS.radius( 0, 0, 50 ); // circular
PS.bgAlpha( 0, 0, PS.ALPHA_OPAQUE ); // opaque
PS.bgColor( 0, 0, PS.COLOR_RED ); // red background

 

PS.bgAlpha ( x, y, alpha )

PS.bgAlpha() changes and inspects the background alpha transparency of scaled and/or non-square beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) alpha : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.ALPHA_TRANSPARENT

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

Usage notes

1. By default, the background color of beads is transparent, allowing the grid color to show through. To see the results of a call to PS.bgColor(), you must use PS.bgAlpha() to increase the opacity.

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

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.

 

PS.data ( x, y, data )

PS.data() changes and inspects the data associated with beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) data : any value, PS.CURRENT or PS.DEFAULT

Returns : value or PS.ERROR

Default : 0

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 data parameter specifies a data value to be assigned to the specified bead(s). It can be any value (number, string, function, array or object) that can be assigned to a JavaScript variable. This value will subsequently be passed through the data parameter of all subsequent PS.touch(), PS.release(), PS.enter() and PS.exit() event calls involving that bead.

If data is PS.DEFAULT, a data value of zero (0) is applied to the bead. If data is PS.CURRENT or not supplied, the bead data is not changed.

Return value

PS.data() returns the data value currently assigned to the bead.

If no data has been assigned, the value zero (0) is returned.

PS.ERROR is returned if an error occurs.

 

PS.exec ( x, y, exec )

PS.exec() changes and inspects the functions assigned to beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) exec : function

Returns : function, null or PS.ERROR

Default : null (no function)

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 exec parameter specifies the bead function. It should be a reference to a valid JavaScript function that accepts the same three parameters as the PS.touch() event handler, namely:

  1. x : integer
  2. y : integer
  3. data : any value

The exec function is subsequently called whenever the bead is clicked or touched, with the x and y parameters set to the zero-based coordinates of the bead, and the data parameter set to the bead's current data value. This call occurs immediately before the usual system call to PS.touch().

The function specified by exec doesn't need to return anything. Any returned values are ignored.

If PS.DEFAULT or null is specified for exec, any previous function assignment is removed from the bead. If PS.CURRENT is specified, or no exec is supplied, the bead function is not changed.

Return value

PS.exec() returns the function currently assigned to the bead.

If no function is assigned, the value null is returned.

PS.ERROR is returned if an error occurs.

 

PS.visible ( x, y, show )

PS.visible() lets you toggle the visibility of beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. show : boolean, PS.CURRENT or PS.DEFAULT

Returns : boolean or PS.ERROR

Default : true

The required x and y parameters indicate the zero-based row and column 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 the optional show parameter is false or the number zero (0), the specified bead becomes invisible:

If show is true or any nonzero number, the bead becomes visible again. If no visual attributes were changed while it was invisible, it assumes its previous state.

Calling PS.visible( x, y, true ) on a visible bead has no effect. Similarly, calling PS.visible( x , y, false ) on an invisible bead has no effect.

If show is PS.DEFAULT, the default visibility (true, visible) is assigned to the bead. If show is PS.CURRENT or not supplied, the visibility is not changed.

Usage notes

1. An invisible bead retains all of its attributes. Its state prior to being made invisible can determined by inspecting the return value of any bead command.

2. Invisible beads continue to produce the usual PS.touch(), PS.release(), PS.enter() and PS.exit() events.

3. If a function has been assigned to an invisible bead with a previous call to PS.exec(), that function is still executed when the bead is clicked or touched.

Return value

PS.visible() returns true if the specified bead is visible, else false.

PS.ERROR is returned if an error occurs.

 

PS.active ( x, y, active )

PS.active() lets you toggle the responsiveness of beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. active : boolean, PS.CURRENT or PS.DEFAULT

Returns : boolean or PS.ERROR

Default : true

The required x and y parameters indicate the zero-based row and column 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 the optional active parameter is false or zero (0), the specified bead is immediately deactivated:

If active is true or any nonzero number, the bead is reactivated and assumes the behavior it exhibited before deactivation.

Calling PS.active( x, y, true ) on an active bead has no effect. Similarly, calling PS.active( x, y, false ) on a deactivated bead has no effect.

If active is PS.DEFAULT, the default activation status (true, active) is assigned to the bead. If active is PS.CURRENT or not supplied, the activation status is not changed.

Notes

1. Deactivating a bead has no visual effect. If you want to give an inactive bead a particular appearance, make the changes before calling PS.active( false ).

2. A deactivated bead retains all of its attributes. Its state prior to deactivation can determined by inspecting the return value of any bead command.

Return value

PS.active() returns true if the specified bead is active, else false.

PS.ERROR is returned if an error occurs.

 

PS.border ( x, y, width )

PS.border() changes and inspects the width of bead borders.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) width : one of
    • integer
    • object
    • PS.CURRENT
    • PS.DEFAULT

Returns : object or PS.ERROR

Default : { top : 1, left : 1, bottom : 1, right : 1, equal : true, width : 1 }

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. The maximum value 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.

A width of less than one (1) hides 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, 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:

If any property is specified as an integer, the width of the corresponding border is changed to integer pixels. The value is clamped 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.

Only square beads are allowed to have unequal border widths.

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.

Return value

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

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.

// EXAMPLES
// Set bead border to 4 pixels

PS.border( x, y, 4 );

// Hide all bead borders

PS.border( x, y, 0 );

// Set each border to a different width
// Make sure bead is square!

PS.radius( x, y, 0 ); // set to square
PS.border( x, y, {
 top : 2,
 left : 4,
 bottom : 6,
 right : 8
} );

// Report the border widths of a bead

var result = PS.border( x, y );

PS.debug( "top = " + result.top +
 ", left = " + result.left +
 ", bottom = " + result.bottom +
 ", right = " + result.right + "\n" );

 

PS.borderColor ( x, y, color )

PS.borderColor() changes and inspects the color of bead borders.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) color : color expression, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.COLOR_GRAY

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

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 )

PS.borderAlpha() changes and inspects the alpha transparency assigned to bead borders.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) alpha : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.ALPHA_OPAQUE

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.

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.

 

PS.borderFade ( x, y, rate, options )

PS.borderFade() changes or inspects the color fade effect of bead borders.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) rate : integer, PS.CURRENT or PS.DEFAULT
  4. (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.borderColor() and PS.borderAlpha() commands change the color of a bead border instantly. You can make the color fade smoothly from one hue to the next by using PS.borderFade().

Once a border fade effect is assigned to a bead with PS.borderFade(), all subsequent calls to PS.borderColor() and PS.borderAlpha() will smoothly fade from the current color (or an optionally specified color) to the new color.

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 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 border 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 triplet 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 border 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 triplet 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.borderFade() returns an object with the following properties:

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

The .rgb property is an RGB triplet 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.glyph ( x, y, glyph )

PS.glyph() changes and inspects the glyphs assigned to beads.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) glyph : integer or string

Returns : integer or PS.ERROR

Default : 0 (no glyph)

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 glyph parameter specifies the glyph to be displayed by the specified bead(s). The parameter can be either an integer (between 1 and 0x10FFFF inclusive) specifying a Unicode character, or a string. The first character in the string specifies the glyph. Any additional characters in the string are ignored.

Specifying zero (0) or the empty string ("") for glyph removes the glyph.

If glyph is PS.DEFAULT, the default glyph (0, none) is assigned to the specified bead. If glyph is PS.CURRENT or not supplied, the glyph is not changed.

Usage notes

1. Glyphs are normally scaled to about half of the full size of a bead, which varies depending on the dimensions of the grid. They can become difficult to read if either grid dimension exceeds 16.

2. Glyphs reduce the maximum border size of a bead. If you add a glyph to a bead with a wide border, the border width may be automatically reduced as necessary to avoid obscuring the glyph.

Return value

PS.glyph() returns an integer indicating the Unicode representation of the glyph currently assigned to the bead.

If no glyph is assigned, the value zero (0) is returned.

PS.ERROR is returned if an error occurs.

 

PS.glyphColor ( x, y, color )

PS.glyphColor() changes and inspects the color of bead glyphs.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) color : color expression, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.COLOR_BLACK

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

Return value

PS.glyphColor() returns a RGB triplet integer indicating the current glyph color of the bead.

PS.ERROR is returned if an error occurs.

 

PS.glyphAlpha ( x, y, alpha )

PS.glyphAlpha() changes and inspects the alpha transparency assigned to bead glyphs.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) alpha : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.ALPHA_OPAQUE

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

Return value

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

PS.ERROR is returned if an error occurs.

 

PS.glyphScale ( x, y, scale )

PS.glyphScale() changes and inspects the scale of bead glyphs.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) scale : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : 100

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 scale of the bead's glyph. It should be an integer between 50 (half size) and 100 (full size) inclusive. Values outside this range are clamped. Non-integral values are floored.

If scale is PS.DEFAULT, the default glyph scale (100, full size) is applied. If scale is PS.CURRENT or not supplied, the glyph scale is not changed.

Usage notes

1. Scaled-down glyphs may become difficult to read if either grid dimension exceeds 16 beads.

Return value

PS.glyphScale() returns an integer in the range 50-100 inclusive indicating the current glyph scale of the bead.

PS.ERROR is returned if an error occurs.

 

PS.glyphFade ( x, y, rate, options )

PS.glyphFade() changes or inspects the color fade effect of bead glyphs.

Parameters:

  1. x : integer or PS.ALL
  2. y : integer or PS.ALL
  3. (optional) rate : integer, PS.CURRENT or PS.DEFAULT
  4. (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.glyphColor() and PS.glyphAlpha() commands change the color of a bead glyph instantly. You can make the color fade smoothly from one hue to the next by using PS.glyphFade().

Once a glyph fade effect is assigned to a bead with PS.glyphFade(), all subsequent calls to PS.glyphColor() and PS.glyphAlpha() will smoothly fade from the current color (or an optionally specified color) to the new color.

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 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 bead's glyph 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 triplet 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 glyph 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 triplet 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.glyphFade() returns an object with the following properties:

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

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