# 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 30

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 81

#### <static, constant> WIDTH_DEFAULT :integer

  Default canvas width in pixels.

  ##### Type:

  - integer
  Default Value:
    - 320
  Source:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 74

### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 840

  ##### Returns:

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

  Type
    boolean

#### clearCanvas()

  Alias for `CB_Canvas#clear`.

  Source:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 828
  See:
    - `CB_Canvas#clear`

#### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 889

  ##### Returns:

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

  Type
    boolean

#### get() → {Element|null}

  Returns the canvas element (if any).

  Source:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 602

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 614

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 668

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 789

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 319

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 800

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 739

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 822

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 811

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 679

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 537
  See:
    - `CB_Canvas#prepareContext`

#### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 549
  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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 336

#### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 650

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 751

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 304

#### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 701

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 142

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 127

  ##### 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:
    - CrossBase/audiovisual/image/canvas/CB_Canvas.js, line 216

  ##### Returns:

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

  Type
    boolean

#### Search results