Perlenspiel 3.3 | Learning 15

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

By default, the PS.color() and PS.alpha() commands change the color of beads instantly. The PS.fade() command lets you change the color of beads gradually, with several options for controlling the speed and parameters of the effect.

Once a 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 initial 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.

// EXAMPLE
// Set bead 0, 0 to gray

PS.color( 0, 0, PS.COLOR_GRAY );

// Enable 1-second fader on bead 0, 0

PS.fade( 0, 0, 60 );

// Subsequent color changes on bead 0, 0
// will dissolve over one second

PS.color( 0, 0, PS.COLOR_GREEN );

// Turn off fader to resume instant color changing

PS.fade( 0, 0, 0 );

Demonstration 1

This demo creates a 7x7 grid of borderless gray beads. Touch any bead to make it dissolve smoothly to a random color over one second.

PS.init = function( system, options ) {
PS.gridSize( 7, 7 );
PS.border( PS.ALL, PS.ALL, 0 ); // no borders

// Set initial bead colors

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

// Enable 1-second fader on all beads

PS.fade( PS.ALL, PS.ALL, 60 );

PS.statusText( "PS.fade() Demo 1" );
};

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
};

Fader options

The PS.fade() command's options parameter let you specify additional fade options. It should be an object with one or more of the following properties:

.rgb : RGB triplet, PS.CURRENT or PS.DEFAULT
.onStep : function, PS.CURRENT or PS.DEFAULT
.onEnd : function, PS.CURRENT or PS.DEFAULT
.params : array, PS.CURRENT or PS.DEFAULT

The most common option to use is .rgb, which 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.

Demonstration 2

This demo creates another 7x7 grid of borderless gray beads. Touch any bead to make it dissolve smoothly from white to a random color over one second.

PS.init = function( system, options ) {
PS.gridSize( 7, 7 );
PS.border( PS.ALL, PS.ALL, 0 ); // no borders

// Set initial bead colors

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

// Enable 1-second fader on all beads
// with initial fade color of white

PS.fade( PS.ALL, PS.ALL, 60, { rgb : PS.COLOR_WHITE } );

PS.statusText( "PS.fade() Demo 2" );
};

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
};

Demonstration 3

Another useful fader option is .onEnd, which lets you specify a function that will be called automatically when a fade effect ends.

This demo creates a grid with a single gray bead. Touch the bead to make it dissolve smoothly to a random color over two seconds. The conclusion of the fade is reported in the status line.

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

PS.gridSize( 1, 1 );
PS.border( 0, 0, 0 ); // no borders

// Set initial bead color

PS.color( 0, 0, PS.COLOR_GRAY );

// Define function to call when fade ends

func = function () {
PS.statusText( "Fade effect ended" );
};

// Enable 2-second fader
// with alert when fade is complete

PS.fade( PS.ALL, PS.ALL, 120, { onEnd : func } );

PS.statusText( "PS.fade() Demo 3" );
};

PS.fade() has other options that can be useful in advanced applications. Refer to the API documentation for details.

Return value

Refer to the API documentation for a complete decription of the object returned by the PS.fade() command.

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

By default, the PS.borderColor() and PS.borderAlpha() commands change the color of bead borders instantly. The PS.borderFade() command lets you change the color of borders gradually, with several options for controlling the speed and parameters of the effect.

Once a fade effect is assigned to a bead border with PS.borderFade(), all subsequent calls to PS.borderColor() and PS.borderAlpha() will smoothly fade the border from the current color (or an optionally specified initial 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's fade effect is disabled. If rate is PS.CURRENT or not supplied, the currently assigned fade rate is not changed.

// EXAMPLE
// Set bead 0, 0 to gray border

PS.borderColor( 0, 0, PS.COLOR_GRAY );

// Enable 1-second fader on bead border 0, 0

PS.borderFade( 0, 0, 60 );

// Subsequent border color changes on bead 0, 0
// will dissolve over one second

PS.borderColor( 0, 0, PS.COLOR_RED );

// Turn off fader to resume instant color changing

PS.borderFade( 0, 0, 0 );

Demonstration

Thsi demo creates a 3x3 grid of black beads with wide gray borders. Touch any bead to make its border dissolve smoothly to a random color over one second.

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

PS.gridSize( 3, 3 );

// Set wide borders on all beads

PS.border( PS.ALL, PS.ALL, 32 );

// Set initial bead & border colors

PS.color( PS.ALL, PS.ALL, PS.COLOR_BLACK );
PS.borderColor( PS.ALL, PS.ALL, PS.COLOR_GRAY );

// Enable 1-second border fader

PS.borderFade( PS.ALL, PS.ALL, 60 );

PS.statusText( "PS.borderFade() 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
};

PS.borderFade() provides the same optional parameters as PS.fade(), as described above. Refer to the API documentation for details.

Return value

Refer to the API documentation for a complete description of the object returned by the PS.borderFade() command.

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

By default, the PS.glyphColor() and PS.glyphAlpha() commands change the color of bead glyphs instantly. The PS.glyphFade() command lets you change the color of glyphs gradually, with several options for controlling the speed and parameters of the effect.

Once a fade effect is assigned to a bead glyph with PS.glyphFade(), all subsequent calls to PS.glyphColor() and PS.glyphAlpha() will smoothly fade the glyph from the current color (or an optionally specified initial 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 glyph's fade effect is disabled. If rate is PS.CURRENT or not supplied, the currently assigned fade rate is not changed.

// EXAMPLE
// Set bead 0, 0 to gray glyph

PS.glyphColor( 0, 0, PS.COLOR_GRAY );

// Enable 1-second fader on bead glyph 0, 0

PS.glyphFade( 0, 0, 60 );

// Subsequent glyph color changes on bead 0, 0
// will dissolve over one second

PS.glyphColor( 0, 0, PS.COLOR_BLUE );

// Turn off fader to resume instant color changing

PS.glyphFade( 0, 0, 0 );

Demonstration

This demo creates a 3x3 grid of black beads with gray triangle glyphs. Touch any bead to make its glyph dissolve smoothly to a random color over one second.

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

PS.gridSize( 3, 3 );
PS.color( PS.ALL, PS.ALL, PS.COLOR_BLACK );
PS.border( PS.ALL, PS.ALL, 0 ); // no borders
PS.glyph( PS.ALL, PS.ALL, 0x25B2 ); // triangle

// Set initial glyph color (gray)

PS.glyphColor( PS.ALL, PS.ALL, PS.COLOR_GRAY );

// Enable 1-second glyph faders on all beads

PS.glyphFade( PS.ALL, PS.ALL, 60 );
PS.statusText( "PS.glyphFade() 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.glyphColor( x, y, r, g, b ); // set glyph color
};

PS.glyphFade() provides the same optional parameters as PS.fade(), as described above. Refer to the API documentation for details.

Return value

Refer to the API documentation for a complete description of the object returned by the PS.glyphFade() command.

PS.statusFade ( rate, options )

By default, the PS.statusColor() command changes the color of the status line instantly. The PS.statusFade() command lets you change the color of the status line gradually, with several options for controlling the speed and parameters of the effect.

Once a fade effect is assigned to the status line with PS.statusFade(), all subsequent calls to PS.statusColor() will smoothly fade the status line from the current color (or an optionally specified initial color) to the new color.

The optional rate parameter specifies the rate of the fade effect in 60ths of a second. If rate is less than 1 or PS.DEFAULT, the status line's fade effect is disabled. If rate is PS.CURRENT or not supplied, the currently assigned fade rate is not changed.

// EXAMPLE
// Set status line to gray

PS.statusColor( PS.COLOR_GRAY );

// Enable 1-second fader on status line

PS.statusFade( 60 );

// Subsequent color changes on status line
// will dissolve over one second

PS.statusColor( PS.COLOR_GREEN );

// Turn off fader to resume instant color changing

PS.statusFade( 0 );

Demonstration

This demo creates a black grid with a single, ominous gray bead. Touch the bead to make the status line dissolve smoothly to a random color over two seconds.

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

PS.gridSize( 1, 1 );
PS.gridColor( PS.COLOR_BLACK );
PS.border( 0, 0, 0 ); // no borders
PS.color( 0, 0, PS.COLOR_GRAY );
PS.glyph( 0, 0, 0x2620 ); // skull & crossbones!
PS.glyphColor( 0, 0, PS.COLOR_WHITE );
PS.statusColor( PS.COLOR_GRAY );
PS.statusFade( 120 );
PS.statusText( "PS.statusFade() 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.statusColor( r, g, b ); // set status color
};

PS.statusFade() provides the same optional parameters as PS.fade(), as described above. Refer to the API documentation for details.

Return value

Refer to the API documentation for a complete description of the object returned by the PS.statusFade() command.

PS.gridFade ( rate, options )

By default, the PS.gridColor() command changes the grid's background color instantly. The PS.gridFade() command lets you change the background of the grid gradually, with several options for controlling the speed and parameters of the effect.

Once a fade effect is assigned to the grid background with PS.gridFade(), all subsequent calls to PS.gridColor() will smoothly fade the grid from the current color (or an optionally specified initial color) to the new color.

The optional rate parameter specifies the rate of the fade effect in 60ths of a second. If rate is less than 1 or PS.DEFAULT, the grid's fade effect is disabled. If rate is PS.CURRENT or not supplied, the currently assigned fade rate is not changed.

// EXAMPLE
// Set grid line to gray

PS.gridColor( PS.COLOR_GRAY );

// Enable 1-second fader on grid

PS.gridFade( 60 );

// Subsequent color changes on grid
// will dissolve over one second

PS.gridColor( PS.COLOR_RED );

// Turn off fader to resume instant color changing

PS.gridFade( 0 );

Demonstration

This demo creates a gray grid with a single royal bead. Touch the bead to make the grid dissolve smoothly to a random color over two seconds.

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

PS.gridSize( 1, 1 );
PS.gridColor( PS.COLOR_GRAY );
PS.border( 0, 0, 0 ); // no borders
PS.color( 0, 0, PS.COLOR_BLACK );
PS.glyph( 0, 0, 0x265A ); // king
PS.glyphColor( 0, 0, PS.COLOR_YELLOW );
PS.statusColor( PS.COLOR_WHITE );
PS.gridFade( 120 );
PS.statusText( "PS.gridFade() 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.gridColor( r, g, b ); // set status color
};

PS.gridFade() provides the same optional parameters as PS.fade(), as described above. Refer to the API documentation for details.

Return value

Refer to the API documentation for a complete description of the object returned by the PS.gridFade() command.

Terms to know