Perlenspiel 3.3 | Learning 10

PS.glyph ( x, y, glyph )

By default, beads do not display a glyph. The PS.glyph() command lets you specify a glyph character 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 glyph parameter specifies the glyph to be displayed by the specified bead(s). The parameter can be either an integer specifying an ASCII or 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.

// EXAMPLES:
// Assign the glyph A to bead 0, 0

PS.glyph( 0, 0, "A" ); // using a string
PS.glyph( 0, 0, "Apple"); // only first char is used
PS.glyph( 0, 0, 65 ); // using decimal ASCII value
PS.glyph( 0, 0 0x0041 ); using hex Unicode value

Identifying ASCII/Unicode glyphs

A table of ASCII character values is available here.

Unicode Glyph Inspector is a handy tool that lets you view the entire ASCII/Unicode character set of 65,536 glyphs available in the official Perlenspiel font (Droid Sans by Steve Matteson), together with their associated hex values. You can copy and paste the hex values into your code.

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.

Demonstration

This demo creates an 8x8 grid. Click or touch any bead to assign a random alphanumeric glyph to that bead.

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

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

c = PS.random(93) + 32; // limit to visible ASCII
PS.glyph( x, y, c );
};

Return value

PS.glyph() returns an integer indicating the ASCII/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 )

By default, bead glyphs are displayed in black. The PS.glyphColor() command lets you specify any color for any bead glyph 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 glyph color (PS.COLOR_BLACK) is applied. If color is PS.CURRENT or not supplied, the color is not changed.

Demonstration

This demo creates a black 8x8 grid, randomly populated with gray astrological symbols (Unicode characters 0x263C-0x2653). Click or touch any bead to assign a random color to that bead's glyph.

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

PS.gridSize( 8, 8 ); // set initial size
PS.gridColor( PS.COLOR_BLACK );
PS.color( PS.ALL, PS.ALL, PS.COLOR_BLACK );
PS.glyphColor( PS.ALL, PS.ALL, PS.COLOR_GRAY );

// Assign a random astrological symbol
// to each bead

for ( y = 0; y < 8; y += 1 ) {
for ( x = 0; x < 8; x += 1 ) {
c = PS.random(24) + 0x263B;
PS.glyph( x, y, c );
}
}

PS.statusText( "PS.glyphColor() Demo" );
PS.statusColor( PS.COLOR_WHITE ); // make visible!
};

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

// Report color in status line

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

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 )

By default, bead glyphs are completely opaque (alpha = 255). The PS.glyphAlpha() command lets you specify any alpha transparency for any bead glyph 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 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.

Demonstration

This demo creates a 4x2 grid of round beads of various colors, consecutively numbered with circular numerals (Unicode characters 0x2776-0x277D). Click or touch any bead to assign a random alpha transparency to that bead's glyph.

PS.init = function( system, options ) {
var hues, x, y, c, h;

// Table of colors for beads

hues = [
PS.COLOR_RED, PS.COLOR_GREEN,
PS.COLOR_BLUE, PS.COLOR_BLACK,
PS.COLOR_CYAN, PS.COLOR_MAGENTA,
PS.COLOR_YELLOW, PS.COLOR_GRAY
];

PS.gridSize( 4, 2 ); // set initial size
PS.scale( PS.ALL, PS.ALL, 90 ); // scale down
PS.radius( PS.ALL, PS.ALL, 50 ); // circular
PS.border( PS.ALL, PS.ALL, 0 ); // no borders
PS.glyphColor( PS.ALL, PS.ALL, PS.COLOR_WHITE );

// Assign consecutive circular number glyphs
// and colors to each bead

c = 0x2776; // first circular number glyph
h = 0; // first hue index
for ( y = 0; y < 2; y += 1 ) {
for ( x = 0; x < 4; x += 1 ) {
PS.glyph( x, y, c ); // set glyph
c += 1;
PS.color( x, y, hues[ h ] ); // set bead color
h += 1;
}
}

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

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

a = PS.random(256) - 1; // random alpha
PS.glyphAlpha( x, y, a ); // set glyph color

// Report alpha in status line

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

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 )

By default, bead glyphs are scaled to occupy about half of the total bead width. The PS.glyphScale() command lets you specify a scale for any bead glyph 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 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.

Demonstration

This demo creates a grid with a single mighty bead, displaying an infinity glyph (Unicode character 0x221E). Click or touch the bead to assign a random scale to the glyph.

PS.init = function( system, options ) {
PS.gridSize( 1, 1 ); // one giant bead!
PS.glyph( 0, 0, 0x221E ); // Unicode infinity
PS.statusText( "PS.glyphScale() Demo" );
};

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

s = ( PS.random(51) - 1 ) + 50; // random 50-100
PS.glyphScale( x, y, s );

// Report value in status line

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

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.

Terms to know