Reference | Beads

These functions control the appearance and behavior of individual beads in the grid.

PS.BeadColor ( x, y, color )

PS.BeadColor() lets you change and/or check the color of beads.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) color, one of:
    • rgb : integer (a single multiplexed rgb value)
    • r, g, b: integer (separate r, g and b values)
    • [ r, g, b: integer ] (a single r, g, b array)
    • { r, g, b: integer } (a single r, g, b table)
    • PS.EMPTY
    • PS.DEFAULT
    • PS.CURRENT

Returns: integer

Default: PS.EMPTY

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional color parameter(s) specify the color to be assigned to the specified bead(s). It can be supplied in any of four parameter formats:

These examples show how to use the different color parameter formats. They all specify exactly the same color (warm orange).

// a multiplexed rgb value

PS.BeadColor( x, y, 0xFFC040 );

// separate red, green and blue values

PS.BeadColor( x y, 255, 192, 64 );

// three-element array

PS.BeadColor( x, y, [ 255, 192, 64 ] );

// table with named r, g and b elements

PS.BeadColor( x, y, { r: 255, g: 192, b: 64 } );

If PS.EMPTY or PS.DEFAULT is specified for the color, the bead becomes “empty” (unassigned) and assumes the color of the grid background. This is the default state of all beads.

If PS.CURRENT is specified, or no color parameter is supplied, the bead color is unchanged, and the return value is the current color of the bead or the value PS.EMPTY if unassigned.

If flashing is enabled on the specified bead, the bead automatically animates from its flash color to the specified color. Otherwise the bead changes to the specified color instantly.

If the specified bead is not active, the color of the bead is changed with no visible effect.

If a color parameter error is detected, the bead color is not changed and the value PS.ERROR is returned.

If the x and y parameters specify a specific bead, the return value is the resulting color of the bead, or the value PS.EMPTY if unassigned.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is changed according to the rgb parameter, and the return value is the color of the last bead in column y.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is changed, and the return value is the resulting color of the last bead in row x.

If both the x and y parameters are set to PS.ALL, every bead on the grid is changed, and the return value is the resulting color of the bead in the last row and column of the grid.

PS.BeadAlpha ( x, y, alpha )

PS.BeadColor() lets you change and/or check the alpha transparency of beads.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) alpha : integer

Returns: integer

Default: 100 (fully opaque)

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional alpha parameter specifies the transparency to be assigned to the specified bead(s). It must be a number in the range 0 (completely transparent) to 100 (fully opaque) inclusive. An error occurs (and the value -1 is returned) if the alpha parameter is invalid.

If flashing is enabled on the specified bead, the bead automatically animates from its flash color to its default color with the new transparency applied. Otherwise the bead color changes to the specified transparency instantly.

If the a bead is inactive or “empty” (that is, set to the color PS.EMPTY), changing the alpha has no immediate visible effect, but will become effective if the bead is subsequently activated or set to a non-empty color.

If PS.DEFAULT is specified for the alpha parameter, the default transparency (100, fully opaque) is applied to the specified bead. If PS.CURRENT is specified, or no alpha parameter is supplied, the transparency is unchanged, and the return value is the current transparency of the bead.

If the x and y parameters specify a specific bead, the return value is the resulting transparency of the bead.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is changed according to the alpha parameter, and the return value is the transparency of the last bead in column y.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is changed, and the return value is the resulting transparency of the last bead in row x.

If both the x and y parameters are set to PS.ALL, every bead on the grid is changed, and the return value is the resulting transparency of the bead in the last row and column of the grid.

PS.BeadBorderWidth ( x, y, width )

PS.BeadBorderWidth() lets you control the width of a bead's border.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) width : integer

Returns: integer

Default: 1

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

If the optional width parameter is zero or less, the bead border immediately disappears. Otherwise the width of the border is changed to the specified number of pixels.

The maximum width of the border is based on the current dimensions of the grid, calculated to ensure that the area of the bead visible inside the border is at least 8x8 pixels.

If PS.DEFAULT is specified for the width parameter, the default border width (1) is applied to the specified bead(s). If PS.CURRENT is specified, or no width parameter is supplied, the border width is unchanged, and the return value is the current border width of the bead.

If the x parameter is set to PS.ALL, the width of every bead border in the row specified by the y parameter is changed according to the width parameter, and the return value is the width of the last bead border in column y.

Similarly, if the y parameter is set to PS.ALL, the width of every bead border in the column specified by x is changed, and the return value is the width of the last bead border in row x.

If both the x and y parameters are set to PS.ALL, the width of every bead border on the grid is changed, and the return value is the width of the bead border in the last row and column of the grid.

PS.BeadBorderColor ( x, y, color )

PS.BeadBorderColor() lets you change and/or check the border color of individual beads.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) color, one of:
    • rgb : integer (a single multiplexed rgb value)
    • r, g, b: integer (separate r, g and b values)
    • [ r, g, b: integer ] (a single r, g, b array)
    • { r, g, b: integer } (a single r, g, b table)
    • PS.DEFAULT
    • PS.CURRENT

Returns: integer

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 (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional color parameter(s) specify the color to be assigned to the border of the specified bead(s). It can be supplied in any of four parameter formats:

(Refer to the documentation for PS.BeadColor() above for examples of how to use the different color parameter formats.)

The border immediately changes to the specified color. If the specified bead is not active, or if its border is disabled or hidden for any reason, the default border color of the bead is changed with no visible effect.

If PS.DEFAULT is specified for the color parameter, the default color (PS.COLOR_GRAY) is applied to the border of the specified bead(s). If PS.CURRENT is specified, or no color parameter is supplied, the border color is unchanged, and the return value is the current border color of the bead.

If a color parameter error is detected, the border color is not changed and the value PS.ERROR is returned.

If the x and y parameters specify a specific bead, the return value is the resulting border color of the bead.

If the x parameter is set to PS.ALL, every border in the row specified by the y parameter is changed according to the rgb parameter, and the return value is the color of the last border in column y.

Similarly, if the y parameter is set to PS.ALL, every border in the column specified by x is changed, and the return value is the resulting color of the last border in row x.

If both the x and y parameters are set to PS.ALL, every border on the grid is changed, and the return value is the resulting color of the border in the last row and column of the grid.

PS.BeadBorderAlpha ( x, y, alpha )

PS.BeadBorderAlpha() lets you change and/or check the alpha transparency of the borders of individual beads.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) alpha : integer

Returns: integer

Default: 100 (fully opaque)

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional alpha parameter specifies the transparency to be assigned to the border of the specified bead(s). It must be a number in the range 0 (completely transparent) to 100 (fully opaque) inclusive. An error occurs (and the value -1 is returned) if the alpha parameter is invalid.

The border immediately changes to the specified transparency.

If the specified bead is not active, or if its border is disabled or hidden for any reason, the default transparency of the border is changed with no visible effect.

If PS.DEFAULT is specified for the alpha parameter, the default transparency (100, fully opaque) is applied to the specified border. If PS.CURRENT is specified, or no alpha parameter is supplied, the transparency is unchanged, and the return value is the current transparency of the border.

If the x and y parameters specify a specific bead, the return value is the resulting transparency of the border.

If the x parameter is set to PS.ALL, every border in the row specified by the y parameter is changed according to the alpha parameter, and the return value is the transparency of the last border in column y.

Similarly, if the y parameter is set to PS.ALL, every border in the column specified by x is changed, and the return value is the resulting transparency of the last border in row x.

If both the x and y parameters are set to PS.ALL, every border on the grid is changed, and the return value is the resulting transparency of the border in the last row and column of the grid.

PS.BeadGlyph ( x, y, glyph )

PS.BeadGlyph() lets you change and/or check the glyph displayed by a bead.

Parameters:

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

Returns: integer

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 (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional glyph parameter specifies the glyph to be displayed by the specified bead(s). The parameter can be either an integer specifying a valid Unicode character, or a string containing at least one character. The first character in the string specifies the glyph. An error occurs (and the value PS.ERROR is returned) if the glyph parameter is invalid.

Specifying zero (0) in the glyph parameter removes the glyph from the bead.

If flashing is enabled on the specified bead, the bead automatically animates from its flash color to its default color with the new glyph displayed (or no glyph, if so specified). Otherwise the glyph changes immediately.

If the specified bead is not active, its glyph is changed with no visible effect.

If PS.DEFAULT is specified for the glyph parameter, the default glyph value (0, none) is applied to the specified bead. If PS.CURRENT is specified, or no glyph parameter is supplied, the glyph is unchanged, and the return value is the current glyph, zero (0) if none.

If the x and y parameters specify a specific bead, the return value is the bead's current glyph, zero (0) if none.

If the x parameter is set to PS.ALL, every glyph in the row specified by the y parameter is changed according to the glyph parameter, and the return value is the resulting glyph of the last bead in column y.

Similarly, if the y parameter is set to PS.ALL, every glyph in the column specified by x is changed, and the return value is the resulting glyph of the last border in row x.

If both the x and y parameters are set to PS.ALL, every glyph on the grid is changed, and the return value is the resulting glyph of the bead in the last row and column of the grid.

PS.BeadGlyphColor ( x, y, color )

PS.BeadGlyphColor() lets you change and/or check the glyph color of individual beads.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) color, one of:
    • rgb : integer (a single multiplexed rgb value)
    • r, g, b: integer (separate r, g and b values)
    • [ r, g, b: integer ] (a single r, g, b array)
    • { r, g, b: integer } (a single r, g, b table)
    • PS.DEFAULT
    • PS.CURRENT

Returns: integer

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 (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional color parameter(s) specifies the color to be assigned to the glyph of the specified bead(s). It can be supplied in any of four parameter formats:

(Refer to the documentation for PS.BeadColor() above for examples of how to use the different color parameter formats.)

The glyph immediately changes to the specified color. If the specified bead is not active, or if its border is disabled or hidden for any reason, the default glyph color of the bead is changed with no visible effect.

If PS.DEFAULT is specified for the color parameter, the default color (PS.COLOR_WHITE) is applied to the glyph of the specified bead(s). If PS.CURRENT is specified, or no color parameter is supplied, the glyph color is unchanged, and the return value is the current glyph color of the bead.

If a color parameter error is detected, the glyph color is not changed and the value PS.ERROR is returned.

If the x and y parameters specify a specific bead, the return value is the resulting glyph color of the bead.

If the x parameter is set to PS.ALL, every glyph in the row specified by the y parameter is changed according to the rgb parameter, and the return value is the color of the last glyph in column y.

Similarly, if the y parameter is set to PS.ALL, every glyph in the column specified by x is changed, and the return value is the resulting color of the last glyph in row x.

If both the x and y parameters are set to PS.ALL, every glyph on the grid is changed, and the return value is the resulting color of the glyph in the last row and column of the grid.

PS.BeadFlash ( x, y, flag )

PS.BeadShow() lets you turn bead flashing “on” or “off,” and/or check a bead's flash status.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) flag : boolean

Returns: boolean

Default: true (flash enabled)

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

If the optional flag parameter is false, bead flashing is turned off. The resulting return value is false.

If the flag parameter is true, bead flashing is turned on. The resulting return value is true.

If the specified bead's flash status is the same as the requested status, there is no change.

If PS.DEFAULT is specified for the flag parameter, the default flash status (true, active) is applied to the specified bead(s). If PS.CURRENT is specified, or no flag parameter is supplied, the flash status is unchanged, and the return value is the current flash status of the bead.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is changed according to the flag parameter, and the return value is the flash status of the last bead in column y.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is changed, and the return value is the flash status of the last bead in row x.

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

PS.BeadFlashColor ( x, y, color )

PS.BeadFlashColor() lets you change and/or check the flash color of individual beads.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) color, one of:
    • rgb : integer (a single multiplexed rgb value)
    • r, g, b: integer (separate r, g and b values)
    • [ r, g, b: integer ] (a single r, g, b array)
    • { r, g, b: integer } (a single r, g, b table)
    • PS.DEFAULT
    • PS.CURRENT

Returns: integer

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 (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional color parameter(s) determines the flash color to be assigned to the specified bead(s). It can be supplied in one of four formats:

(Refer to the documentation for PS.BeadColor() above for examples of how to use the different color parameter formats.)

The flash color immediately changes to the specified value. If the specified bead is not active, or if its border is disabled or hidden for any reason, the default flash color of the bead is changed with no visible effect.

If PS.DEFAULT is specified for the color parameter, the default flash color (PS.COLOR_WHITE) is applied to the specified bead(s). If PS.CURRENT is specified, or no color parameter is supplied, the flash color is unchanged, and the return value is the current flash color of the bead.

If a colorspec parameter error is detected, the flash color is not changed and the value PS.ERROR is returned.

If the x and y parameters specify a specific bead, the return value is the resulting flash color of the bead.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is changed according to the rgb parameter, and the return value is the flash color of the last glyph in column y.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is changed, and the return value is the resulting flash color of the last glyph in row x.

If both the x and y parameters are set to PS.ALL, every bead on the grid is changed, and the return value is the resulting flash color of the glyph in the last row and column of the grid.

PS.BeadData ( x, y, data )

PS.BeadData() lets you set and read the data value associated with a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) data : any type

Returns: value

Default: 0

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional data parameter specifies the data value to be assigned to the specified bead(s). It can be any Javascript value type (number, string, function, array or table) that can be assigned to a variable.

The bead data immediately changes to the specified value.

If no data parameter is supplied, the bead's data value is unchanged, and the return value is the current data value of the bead.

If the x and y parameters specify a specific bead, the return value is the resulting data value of the bead.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is changed according to the data parameter, and the return value is the data value of the last glyph in column y.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is changed, and the return value is the resulting data value of the last glyph in row x.

If both the x and y parameters are set to PS.ALL, every bead on the grid is changed, and the return value is the resulting data value of the glyph in the last row and column of the grid.

PS.BeadAudio ( x, y, audio, volume )

PS.BeadAudio() lets you set and read the audio file associated with a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) audio : string
  4. (optional) volume : float

Returns: string or null

Default: null (no audio assigned)

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional audio parameter specifies the audio file to be assigned to the specified bead(s). It must be a string corresponding to the name of an audio file in the Perlenspiel audio library, or the value null if no audio is desired.

If PS.DEFAULT is specified for the audio parameter, the default audio file value (null, no file) is applied to the specified bead(s). If PS.CURRENT is specified, or no audio parameter is supplied, the audio file is unchanged, and the return value is the current audio file of the bead.

The optional volume parameter controls the level at which the sound will be played. It must be a number between 0.0 (total silence) and 1.0 (full volume). Any value outside this range is clamped. If the value PS.DEFAULT is specified, or no volume parameter is provided, the default value (0.5, 50% volume) is used.

If PS.DEFAULT is specified for the volume parameter, the default value (50, or 50% volume) is applied to the specified bead(s). If PS.CURRENT is specified, or no volume parameter is supplied, the volume is unchanged.

If a parameter error occurs, the value PS.ERROR is returned.

The bead audio file and volume immediately changes to the specified values.

If the x and y parameters specify a specific bead, the return value is the resulting audio file of the bead.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is changed according to the audio parameter, and the return value is the resulting audio file of the last bead in column y.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is changed, and the return value is the resulting audio file of the last bead in row x.

If both the x and y parameters are set to PS.ALL, every bead on the grid is changed, and the return value is the resulting audio file of the bead in the last row and column of the grid.

PS.BeadFunction ( x, y, f )

PS.BeadFunction() lets you set and read the function assigned to a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) f : function

Returns: function

Default: null (no function assigned)

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

The optional f parameter specifies the function to be assigned to the specified bead(s). The parameter must be the value null if no function is desired, otherwise a valid Javascript function that accepts the same three parameters as the PS.Click() event handler, namely:

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

The function doesn't need to return anything; returned values are ignored.

If a parameter error occurs, the value null is returned.

The bead's function immediately changes to the specified value.

If PS.DEFAULT is specified for the f parameter, the default function (null, none) is applied to the specified bead(s). If PS.CURRENT is specified, or no f parameter is supplied, the function is unchanged, and the return value is the current function of the bead.

If the x and y parameters specify a specific bead, the return value is the resulting function of the bead.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is changed according to the f parameter, and the return value is the resulting function of the last bead in column y.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is changed, and the return value is the resulting function of the last bead in row x.

If both the x and y parameters are set to PS.ALL, every bead on the grid is changed, and the return value is the resulting function of the bead in the last row and column of the grid.

PS.BeadTouch ( x, y )

PS.BeadTouch() lets you simulate the effects of clicking on or touching a bead.

Parameters:

  1. x : integer
  2. y : integer

Returns: Nothing

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.

When a bead is “touched” by PS.BeadTouch(), the following events occur in order:

  1. If the bead has an audio file associated with it, that file is played.
  2. If the bead has a function associated with it, that function is called.
  3. The PS.Click() event handler is called with the x and y parameters set to the coordinates of the bead, and the data parameter set to the bead's current data value.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is “touched” successively from left to right.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is “touched” successively from top to bottom.

If both the x and y parameters are set to PS.ALL, every bead on the grid is “touched” successively from left to right and top to bottom.

PS.BeadShow ( x, y, flag )

PS.BeadShow() lets you turn beads “on” or “off,” and/or check their display status.

Parameters:

  1. x : integer
  2. y : integer
  3. (optional) flag : boolean

Returns: boolean

Default: true (bead active)

The required x and y parameters indicate the zero-based column and row position of the bead, respectively. An error occurs (and the value PS.ERROR is returned) if either parameter is negative, or exceeds the dimensions of the grid.

If the optional flag parameter is false, the bead is turned “off.” It immediately stops responding to mouse events, and changes to the default grid background color. The resulting return value is false.

If the flag parameter is true, the bead is turned “on” and immediately begins responding to mouse events. If flashing on the bead is enabled, the bead automatically animates from its flash color to its current default color. Otherwise the bead changes to its default color instantly. The resulting return value is true.

If the specified bead's display status is the same as the requested status, there is no change.

If PS.DEFAULT is specified for the flag parameter, the default display status (true, active) is applied to the specified bead(s). If PS.CURRENT is specified, or no flag parameter is supplied, the display status is unchanged, and the return value is the current display status of the bead.

If the x parameter is set to PS.ALL, every bead in the row specified by the y parameter is changed according to the flag parameter, and the return value is the status of the last bead in column y.

Similarly, if the y parameter is set to PS.ALL, every bead in the column specified by x is changed, and the return value is the status of the last bead in row x.

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