CrossBrowdy API documentation

Class: CB_Canvas

CB_Canvas

Class to manage a canvas. For clients which do not support native canvas, it provides Adobe Flash (formerly Macromedia Flash) emulation with FlashCanvas, Microsoft Silverlight emulation with SLCanvas, VML emulation with ExplorerCanvas (reinforced with canvas-text) and DHTML (DOM elements) emulation with CanBox.
NOTE:
To make the VML emulation work without errors (using ExplorerCanvas), it is recommended to always load FlashCanvas (which already includes ExplorerCanvas) in your HTML code (without using lazy-load, as ExplorerCanvas does not support it). This is recommended even when we are not going to use Adobe Flash (formerly Macromedia Flash) emulation with FlashCanvas.
This is an example (should be placed before loading the main "CrossBrowdy" script):
<!-- Loads FlashCanvas (Flash emulation) before CrossBrowdy. Needed also to use ExplorerCanvas (VML emulation) without problems: -->
<script type="text/javascript" src="CrossBrowdy/CrossBase/audiovisual/image/canvas/FlashCanvas/pro/bin/flashcanvas.js"></script><!-- FlashCanvas/ExplorerCanvas do not support lazy load. -->

new CB_Canvas(canvasId [, contextType] [, canvasWidth] [, canvasHeight] [, onLoad] [, onError] [, canvasParent] [, alternativeCanvasEmulationPreferredOrder] [, forceFirstEmulationMethod] [, addOtherMethods] [, allowFlashCanvasLocally]) → {CB_Canvas}

Class to manage a canvas.

Parameters:
Name Type Argument Default Description
canvasId string

The desired ID for the canvas.
contextType '2d' | 'webgl' | 'experimental-webgl' | 'webgl2' | 'experimental-webgl2' | 'bitmaprenderer' <optional>
 '2d'

The contextType desired by default. More information: HTMLCanvasElement.getContext. Note that most emulation methods will only support "2d".
canvasWidth integer <optional>
 CB_Canvas.WIDTH_DEFAULT

The desired width (horizontal size) in pixels for the canvas.
canvasHeight integer <optional>
 CB_Canvas.HEIGHT_DEFAULT

The desired height (vertical size) in pixels for the canvas.
onLoad function <optional>

Callback function that will be called when the canvas is finally loaded. It will not receive parameters, being "this" the CB_Canvas object itself.
onError function <optional>

Callback function that will be called when there is an error creating or loading the canvas. Being "this" the CB_Canvas object itself, the unique parameter received will be a string describing the error (if it could be determined).
canvasParent Element <optional>
 document.body

The parent element desired to adopt the canvas.
alternativeCanvasEmulationPreferredOrder array <optional>
 CB_Configuration.CrossBase.CB_Canvas_PREFERRED_EMULATION_METHODS

Numeric array listing the desired alternative emulation methods for rendering the canvas, in order of preference. Supported emulation methods: "FLASH", "VML", "DHTML" and "SILVERLIGHT".
forceFirstEmulationMethod boolean <optional>
 false

If set to true, it will force to use the first alternative emulation method desired (even when this alternative emulation method could be not supported and even when native canvas support could be supported).
addOtherMethods boolean <optional>
 true

If set to true, it will add other alternative methods (if any is missing) at the end of the desired alternative emulation methods so they will also be checked and used if the previous ones are not finally used. The order they will be added will be the one used in the CB_Configuration.CrossBase.CB_Canvas_PREFERRED_EMULATION_METHODS constant.
allowFlashCanvasLocally boolean <optional>
 CB_Configuration.CrossBase.FLASHCANVAS_ALLOW_RUN_LOCALLY_DEFAULT

If set to true, it will allow to use Adobe Flash (formerly Macromedia Flash) emulation (if needed) even when it is running locally. Uses the CB_Client.isRunningLocally function internally.
Source:
Returns:

Returns a new CB_Canvas object.

Type
CB_Canvas

Members

<static, constant> HEIGHT_DEFAULT :integer

Default canvas height in pixels.

Type:
  • integer
Default Value:
  • 240
Source:

<static, constant> WIDTH_DEFAULT :integer

Default canvas width in pixels.

Type:
  • integer
Default Value:
  • 320
Source:

Methods

clear( [keepTransform] [, backgroundFillStyle]) → {boolean}

Clear the canvas entirely.

Parameters:
Name Type Argument Default Description
keepTransform boolean <optional>
 false

If set to true, it will save and restore the current transformation.
backgroundFillStyle string <optional>

The style used (color, gradient, pattern...) to fill the canvas background. If defined, it will be used as the value for the fillStyle property of the context object, internally.
Source:
Returns:

Returns true if the action could be performed or false otherwise.

Type
boolean

clearCanvas()

Alias for CB_Canvas#clear.

Source:
See:

disableAntiAliasing( [performTranslate]) → {boolean}

Disables anti-aliasing. Useful to work with image sprites (to avoid problems showing adjacent ones), for example.

Parameters:
Name Type Argument Default Description
performTranslate boolean <optional>
 false

If set to true, it will also call the transform method.
Source:
Returns:

Returns true if the action could be performed or false otherwise.

Type
boolean

get() → {Element|null}

Returns the canvas element (if any).

Source:
Returns:

Returns the canvas element (if any). If not found, null will be returned.

Type
Element | null

getContext( [contextType]) → {RenderingContext|Object}

Defines and returns the canvas context. It could call the CB_Canvas#prepareContext method internally.

Parameters:
Name Type Argument Default Description
contextType '2d' | 'webgl' | 'experimental-webgl' | 'webgl2' | 'experimental-webgl2' | 'bitmaprenderer' <optional>
 CB_Canvas#._contextType|'2d'

The context type desired. More information: HTMLCanvasElement.getContext. Note that most emulation methods will only support "2d".
Source:
Returns:

Returns the canvas context (different type if a canvas emulation method is being used).

Type
RenderingContext | Object

getContextType() → {string}

Tells the current canvas context type used. Internally, it returns the value of the CB_Canvas#._contextType property.

Source:
Returns:

Tells the current canvas context type used. More information: HTMLCanvasElement.getContext.

Type
string

getHeight() → {number}

Tells the canvas height (vertical size) being used in pixels.

Source:
Returns:

Returns the canvas height (vertical size) being used in pixels. It could return zero (0) if cannot be calculated.

Type
number

getId() → {string}

Returns the identifier (ID) of the canvas element.

Source:
Returns:

Returns the identifier (ID) of the canvas element.

Type
string

getMode() → {'NONE'|'NORMAL'|'FLASH'|'SILVERLIGHT'|'VML'|'DHTML'}

Tells the mode used to create the canvas.

Source:
Returns:

Returns the mode used to create the canvas. Returns "NONE" if no method is used yet (possible when no method is supported at all or when it is still loading). Returns "NORMAL" if native canvas is used (no canvas emulation method).

Type
'NONE' | 'NORMAL' | 'FLASH' | 'SILVERLIGHT' | 'VML' | 'DHTML'

getWidth() → {number}

Tells the canvas width (horizontal size) being used in pixels.

Source:
Returns:

Returns the canvas width (horizontal size) being used in pixels. It could return zero (0) if cannot be calculated.

Type
number

isLoading() → {boolean}

Tells whether the canvas is loading or not. Some canvas emulation methods can take some time until they finish loading.

Source:
Returns:

Returns whether the canvas is loading or not.

Type
boolean

isReady() → {boolean}

Tells whether the canvas is ready to be used or not. Some canvas emulation methods can take some time until they are ready to be used.

Source:
Returns:

Returns whether the canvas is ready to be used or not.

Type
boolean

isSupported() → {boolean}

Tells whether the canvas works or not. The internal test used could be not totally reliable.

Source:
Returns:

Returns whether the canvas works or not. The internal test used could be not totally reliable.

Type
boolean

normalizeContext()

Alias for CB_Canvas#prepareContext.

Source:
See:

prepareContext( ) → {RenderingContext|Object}

Provides the canvas context with some methods and properties, in case it needs it (as some canvas emulation methods lack of some methods and properties). Since this method is called by the CB_Canvas#set method already (and this one is called by the constructor automatically), it is not needed to be called again normally.

Parameters:
Name Type Argument Default Description
context RenderingContext | Object <optional>
 CB_Canvas#getContext()

The context object that we want to prepare (different type if a canvas emulation method is being used). If not defined, calls the CB_Canvas#getContext method internally.
Source:
To Do:
  • Add more methods and properties needed by some emulation methods.
Returns:

Returns the canvas context (different type if a canvas emulation method is being used).

Type
RenderingContext | Object

set(canvasId [, canvasWidth] [, canvasHeight] [, onLoad] [, onError] [, alternativeCanvasEmulation] [, forceEmulation])

Defines the canvas element. Since this method is called by the constructor already, it is not needed to be called unless the canvas element wants to be defined again.

Parameters:
Name Type Argument Default Description
canvasId string

The desired ID for the canvas.
canvasWidth integer <optional>
 CB_Canvas.WIDTH_DEFAULT

The desired width (horizontal size) in pixels for the canvas.
canvasHeight integer <optional>
 CB_Canvas.HEIGHT_DEFAULT

The desired height (vertical size) in pixels for the canvas.
onLoad function <optional>

Callback function that will be called when the canvas is finally loaded. It will not receive parameters, being "this" the CB_Canvas object itself.
onError function <optional>

Callback function that will be called when there is an error creating or loading the canvas. Being "this" the CB_Canvas object itself, the unique parameter received will be a string describing the error (if it could be determined).
alternativeCanvasEmulation string <optional>
 CB_Canvas.bestEmulation()

Emulation method we want to use in the case that the native canvas is not supported or if the "forceEmulation" parameter is set to true. Possible emulation methods: "FLASH", "VML", "DHTML" and "SILVERLIGHT".
forceEmulation boolean <optional>
 false

If set to true, it will force to use the emulation method defined in the "alternativeCanvasEmulation" parameter (even when this alternative emulation method could be not supported and even when native canvas support could be supported).
Source:

setContextType( [contextType]) → {string}

Defines the desired canvas context type. Internally, it only defines the CB_Canvas#._contextType property.

Parameters:
Name Type Argument Default Description
contextType '2d' | 'webgl' | 'experimental-webgl' | 'webgl2' | 'experimental-webgl2' | 'bitmaprenderer' <optional>
 '2d'

The [context]context type desired. More information: HTMLCanvasElement.getContext. Note that most emulation methods will only support "2d".
Source:
Returns:

Returns the context type just applied.

Type
string

setHeight( [canvasHeight]) → {number}

Defines the desired canvas height.

Parameters:
Name Type Argument Default Description
canvasHeight integer <optional>
 CB_Canvas.HEIGHT_DEFAULT

The desired height (vertical size) in pixels for the canvas.
Source:
Returns:

Returns the canvas height (vertical size) being used in pixels. It could return zero (0) if cannot be calculated.

Type
number

setId(canvasId)

Sets the desired identifier (ID) of the canvas element. Since this method is called by the constructor already, it is not needed to be called unless the canvas element wants to be defined again through the CB_Canvas#set method. Note that changing the ID after the canvas has been set could lead to some problems when using certain emulation methods so it is not recommended.

Parameters:
Name Type Description
canvasId string

Identifier (ID) for the canvas element.
Source:

setWidth( [canvasWidth]) → {number}

Defines the desired canvas width.

Parameters:
Name Type Argument Default Description
canvasWidth integer <optional>
 CB_Canvas.WIDTH_DEFAULT

The desired width (horizontal size) in pixels for the canvas.
Source:
Returns:

Returns the canvas width (horizontal size) being used in pixels. It could return zero (0) if cannot be calculated.

Type
number

<static> bestEmulation( [preferredOrder] [, forceFirstEmulationMethod] [, addOtherMethods] [, allowFlashCanvasLocally]) → {'NONE'|'FLASH'|'SILVERLIGHT'|'VML'|'DHTML'}

Calculates and returns the best alternative canvas emulation.

Parameters:
Name Type Argument Default Description
preferredOrder array | string <optional>
 CB_Configuration.CrossBase.CB_Canvas_PREFERRED_EMULATION_METHODS

Numeric array listing the desired alternative emulation methods for rendering the canvas, in order of preference. Possible emulation methods: "FLASH", "VML", "DHTML" and "SILVERLIGHT". It can also be a string with the unique desired canvas emulation method or with "NO" or "NONE" value (meaning no emulation method is desired and then the returning value will always be "NONE").
forceFirstEmulationMethod boolean <optional>
 false

If set to true, it will force to return the first alternative emulation method desired which is detected as supported without being too strict (even when this alternative emulation method could be not really supported and even when native canvas support could be supported).
addOtherMethods boolean <optional>
 true

If set to true, it will add other alternative methods (if any is missing) at the end of the desired alternative emulation methods so they will also be checked and used if the previous ones are not finally used. The order they will be added will be the one used in the CB_Configuration.CrossBase.CB_Canvas_PREFERRED_EMULATION_METHODS constant.
allowFlashCanvasLocally boolean <optional>
 CB_Configuration.CrossBase.FLASHCANVAS_ALLOW_RUN_LOCALLY_DEFAULT

If set to true, it will allow to use Adobe Flash (formerly Macromedia Flash) emulation (if needed) even when it is running locally. Uses the CB_Client.isRunningLocally function internally.
Source:
Returns:

Returns "NONE" if no canvas emulation is needed/supported (and no emulation method is forced). Otherwise, it returns the best emulation method calculated ("FLASH", "SILVERLIGHT", "VML" or "DHTML").

Type
'NONE' | 'FLASH' | 'SILVERLIGHT' | 'VML' | 'DHTML'

<static> needsEmulation() → {boolean}

Tells whether the current client needs canvas emulation or not. Uses CB_Client.supportsCanvas internally.

Source:
Returns:

Returns whether the current client needs canvas emulation or not.

Type
boolean

<static> supportsEmulationMethod(emulationMethod [, strictMode]) → {boolean}

Tells whether the current client is compatible with a given canvas emulation method or not.

Parameters:
Name Type Argument Default Description
emulationMethod string

Emulation method we want to check. Possible emulation methods: "FLASH", "VML", "DHTML" and "SILVERLIGHT".
strictMode boolean <optional>
 true

If set to true, the compatibility will be checked more carefully. If set to false (not recommended), the method could return true even when sometimes the canvas emulation method is not totally supported by the current client.
Source:
Returns:

Returns whether the current client is compatible with the given canvas emulation method or not.

Type
boolean