KCL: Screen Elements

From Spheriki

The KCL (Kamatsu's Class Library) includes a set of simple objects that can be used to represent particles or screen elements. There are two major classes:

• TextElement - A screen element that is comprised of text.
• ImageElement - A screen element that is comprised of an image or a surface.

TextElement Class

Defining

Having included the KCL, you can define a new TextElement as follows:

var te = new TextElement(text,font,x,y,background);

Where:

• text (optional) - Text you wish to display. Leaving blank will result in a blank string being used.
• font (optional) - Font you wish to use. Defaults to Game.font
• x (optional) - Initial X value of the object.
• y (optional) - Initial Y value of the object.
• background (optional) - This is a KCL background property. Default is BACKGROUND_NONE. It controls what is blitted to screen before the element is blitted. can be one of the following values:
  • BACKGROUND_NONE - Nothing is blitted by the object beforehand.
  • BACKGROUND_RENDERMAP - RenderMap() is called by the object before blitting.
  • An Image or Surface to blit as a background.

Properties

• x,y (rw) - Coordinates of the object at the current time. Defaults to zero if not specified.
• background (rw) - a KCL background property. Default is BACKGROUND_NONE. It controls what is blitted to screen before the element is blitted. can be one of the following values:
  • BACKGROUND_NONE - Nothing is blitted by the object beforehand.
  • BACKGROUND_RENDERMAP - RenderMap() is called by the object before blitting.
  • An Image or Surface to blit as a background.
• text (rw) - Text to display. Default is an empty string.
• flipScreen (rw) - Whether or not to FlipScreen() with every update() call. Defaults to false.
• font (rw) - Font you wish to use. Defaults to Game.font
• opacity (rw) - Number between 0 and 255 representing the opacity to blit at.
• angle (rw) - Current polar theta (angle) being used for polar movement
• preRender (rw) - First class function (i.e, a function passed as an object) that is called before the object is drawn.
• postRender (rw) - First class function (i.e, a function passed as an object) that is called after the object is drawn.

Example of preRender and postRender

var a = new TextElement();
a.preRender = function () {
 // Do some stuff
}
a.postRender = function () {
 // Do some other stuff
}

Methods

TextElement.update()

This function performs the following:

• Call .preRender function if one is specified.
• If .background is not BACKGROUND_NONE, draw the background by a call to internal function .drawBackground.
• Blit the text at specified opacity.
• Call .postRender function if one is specified.
• If .flipScreen is true, call FlipScreen()

This function is what should be called within any display loop to make use of the element.

TextElement.getWidth()

Returns the width of the element's graphical content.

TextElement.getHeight()

Returns the height of the element's graphical content.

TextElement.go(amount)

Move forward in the direction specified by the angle property, amount pixels.

Example:

var a = new TextElement("text",false,100,100); // "false" means to use the default font
    a.flipScreen = true;
    while (!IsKeyPressed(KEY_ENTER)) {
 
        a.angle += Math.pi/180; // pi radians equals 180 degrees, so pi/180 is one degree.
 
        a.go(1); // Move forward one pixel
 
        a.update(); //as flipScreen  equals true, this effectively blits and flips for us.
 
    }

This will make the textElement a move around in a circle.

ImageElement Class

Defining

Having included the KCL, you can define a new ImageElement as follows:

var te = new ImageElement(image,x,y,background);

Where:

• Image - Image/Surface you wish to display. Leaving blank will result in an error.
• x (optional) - Initial X value of the object.
• y (optional) - Initial Y value of the object.
• background (optional) - This is a KCL background property. Default is BACKGROUND_NONE. It controls what is blitted to screen before the element is blitted. can be one of the following values:
  • BACKGROUND_NONE - Nothing is blitted by the object beforehand.
  • BACKGROUND_RENDERMAP - RenderMap() is called by the object before blitting.
  • An Image or Surface to blit as a background.

Properties

• x,y (rw) - Coordinates of the object at the current time. Defaults to zero if not specified.
• background (rw) - a KCL background property. Default is BACKGROUND_NONE. It controls what is blitted to screen before the element is blitted. can be one of the following values:
  • BACKGROUND_NONE - Nothing is blitted by the object beforehand.
  • BACKGROUND_RENDERMAP - RenderMap() is called by the object before blitting.
  • An Image or Surface to blit as a background.
• image (rw) - Image/Surface to display.
• flipScreen (rw) - Whether or not to FlipScreen() with every update() call. Defaults to false.
• opacity (rw) - Number between 0 and 255 representing the opacity to blit at.
• angle (rw) - Current polar theta (angle) being used for polar movement
• preRender (rw) - First class function (i.e, a function passed as an object) that is called before the object is drawn.
• postRender (rw) - First class function (i.e, a function passed as an object) that is called after the object is drawn.
• rotateImage (rw) - Boolean value specifying whether the image should be rotated by angle or if the image should remain at 0 orientation.

Example of preRender and postRender

var a = new ImageElement(image);
a.preRender = function () {
 // Do some stuff
}
a.postRender = function () {
 // Do some other stuff
}

Methods

ImageElement.update()

This function performs the following:

• Call .preRender function if one is specified.
• If .background is not BACKGROUND_NONE, draw the background by a call to internal function .drawBackground.
• Blit the Image at specified opacity, rotating if specified by .rotateImage by .angle
• Call .postRender function if one is specified.
• If .flipScreen is true, call FlipScreen()

This function is what should be called within any display loop to make use of the element.

ImageElement.getWidth()

Returns the width of the element's graphical content.

ImageElement.getHeight()

Returns the height of the element's graphical content.

ImageElement.go(amount)

Move forward in the direction specified by the angle property, amount pixels.

Example:

var a = new ImageElement(image,100,100);
    a.flipScreen = true;
    while (!IsKeyPressed(KEY_ENTER)) {
        if (IsKeyPressed(KEY_R)) a.rotateImage = !a.rotateImage; //Press R to toggle rotation
        a.angle += Math.pi/180; // pi radians equals 180 degrees, so pi/180 is one degree.
 
        a.go(1); // Move forward one pixel
 
        a.update(); //as flipScreen  equals true, this effectively blits and flips for us.
 
    }

This will make the ImageElement a move around in a circle, with R toggling the image rotation.