View Class

Extends EventTarget

Module: cc Parent Module: cc

cc.view is the singleton object which represents the game window.
It's main task include:

• Apply the design resolution policy
  
• Provide interaction with the window, like resize event on web, retina display support, etc...
  
• Manage the game view port which can be different with the window
  
• Manage the content scale and translation
  
  Since the cc.view is a singleton, you don't need to call any constructor or create functions,
  the standard way to use it is by calling:
  
• cc.view.methodName();
  

Index

Methods

• setTargetDensityDPI Sets view's target-densitydpi for android mobile browser.
• getTargetDensityDPI Returns the current target-densitydpi value of cc.view.
• resizeWithBrowserSize Sets whether resize canvas automatically when browser's size changed....
• setResizeCallback Sets the callback function for cc.view's resize action,...
• setOrientation Sets the orientation of the game, it can be landscape, portrait or auto.
• adjustViewportMeta Sets whether the engine modify the "viewport" meta in your web page....
• enableRetina Retina support is enabled by default for Apple device but disabled for other devices,...
• isRetinaEnabled Check whether retina display is enabled....
• enableAntiAlias Whether to Enable on anti-alias
• isAntiAliasEnabled Returns whether the current enable on anti-alias
• enableAutoFullScreen If enabled, the application will try automatically to enter full screen mode on mobile devices...
• isAutoFullScreenEnabled Check whether auto full screen is enabled....
• getCanvasSize Returns the canvas size of the view....
• getFrameSize Returns the frame size of the view....
• setFrameSize On native, it sets the frame size of view....
• getVisibleSize Returns the visible area size of the view port.
• getVisibleSizeInPixel Returns the visible area size of the view port.
• getVisibleOrigin Returns the visible origin of the view port.
• getVisibleOriginInPixel Returns the visible origin of the view port.
• getResolutionPolicy Returns the current resolution policy
• setResolutionPolicy Sets the current resolution policy
• setDesignResolutionSize Sets the resolution policy with designed view size in points....
• getDesignResolutionSize Returns the designed size for the view.
• setRealPixelResolution Sets the container to desired pixel resolution and fit the game content to it.
• setViewportInPoints Sets view port rectangle with points.
• setScissorInPoints Sets Scissor rectangle with points.
• isScissorEnabled Returns whether GL_SCISSOR_TEST is enable
• getScissorRect Returns the current scissor rectangle
• getViewportRect Returns the view port rectangle.
• getScaleX Returns scale factor of the horizontal direction (X axis).
• getScaleY Returns scale factor of the vertical direction (Y axis).
• getDevicePixelRatio Returns device pixel ratio for retina display.
• convertToLocationInView Returns the real location in view for a translation based on a related position
• hasEventListener Checks whether the EventTarget object has any callback registered for a specific type of event.
• on Register an callback of a specific event type on the EventTarget.
• off Removes the listeners previously registered with the same type, callback, target and or useCapture,...
• targetOff Removes all callbacks previously registered with the same target (passed as parameter).
• once Register an callback of a specific event type on the EventTarget,...
• dispatchEvent Send an event with the event object.
• removeAll Removes all callbacks registered in a certain event type or all callbacks registered with a certain target
• emit Trigger an event directly with the event name and necessary arguments.

Events

• design-resolution-changed Emit when design resolution changed.
• canvas-resize Emit when canvas resize.

Details

Methods

setTargetDensityDPI

Sets view's target-densitydpi for android mobile browser. it can be set to:

1. cc.macro.DENSITYDPI_DEVICE, value is "device-dpi"
   
2. cc.macro.DENSITYDPI_HIGH, value is "high-dpi" (default value)
   
3. cc.macro.DENSITYDPI_MEDIUM, value is "medium-dpi" (browser's default value)
   
4. cc.macro.DENSITYDPI_LOW, value is "low-dpi"
   
5. Custom value, e.g: "480"
   

Parameters

• densityDPI String

getTargetDensityDPI

Returns the current target-densitydpi value of cc.view.

resizeWithBrowserSize

Sets whether resize canvas automatically when browser's size changed.
Useful only on web.

Parameters

• enabled Boolean Whether enable automatic resize with browser's resize event

setResizeCallback

Sets the callback function for cc.view's resize action,
this callback will be invoked before applying resolution policy,
so you can do any additional modifications within the callback.
Useful only on web.

Parameters

• callback Function | Null The callback function

setOrientation

Sets the orientation of the game, it can be landscape, portrait or auto. When set it to landscape or portrait, and screen w/h ratio doesn't fit, cc.view will automatically rotate the game canvas using CSS. Note that this function doesn't have any effect in native, in native, you need to set the application orientation in native project settings

Parameters

• orientation Number Possible values: cc.macro.ORIENTATION_LANDSCAPE | cc.macro.ORIENTATION_PORTRAIT | cc.macro.ORIENTATION_AUTO

adjustViewportMeta

Sets whether the engine modify the "viewport" meta in your web page.
It's enabled by default, we strongly suggest you not to disable it.
And even when it's enabled, you can still set your own "viewport" meta, it won't be overridden
Only useful on web

Parameters

• enabled Boolean Enable automatic modification to "viewport" meta

enableRetina

Retina support is enabled by default for Apple device but disabled for other devices,
it takes effect only when you called setDesignResolutionPolicy
Only useful on web

Parameters

• enabled Boolean Enable or disable retina display

isRetinaEnabled

Check whether retina display is enabled.
Only useful on web

enableAntiAlias

Whether to Enable on anti-alias

Parameters

• enabled Boolean Enable or not anti-alias

isAntiAliasEnabled

Returns whether the current enable on anti-alias

enableAutoFullScreen

If enabled, the application will try automatically to enter full screen mode on mobile devices
You can pass true as parameter to enable it and disable it by passing false.
Only useful on web

Parameters

• enabled Boolean Enable or disable auto full screen on mobile devices

isAutoFullScreenEnabled

Check whether auto full screen is enabled.
Only useful on web

getCanvasSize

Returns the canvas size of the view.
On native platforms, it returns the screen size since the view is a fullscreen view.
On web, it returns the size of the canvas element.

getFrameSize

Returns the frame size of the view.
On native platforms, it returns the screen size since the view is a fullscreen view.
On web, it returns the size of the canvas's outer DOM element.

setFrameSize

On native, it sets the frame size of view.
On web, it sets the size of the canvas's outer DOM element.

Parameters

• width Number
• height Number

getVisibleSize

Returns the visible area size of the view port.

getVisibleSizeInPixel

Returns the visible area size of the view port.

getVisibleOrigin

Returns the visible origin of the view port.

getVisibleOriginInPixel

Returns the visible origin of the view port.

getResolutionPolicy

Returns the current resolution policy

setResolutionPolicy

Sets the current resolution policy

Parameters

• resolutionPolicy ResolutionPolicy | Number

setDesignResolutionSize

Sets the resolution policy with designed view size in points.
The resolution policy include:
[1] ResolutionExactFit Fill screen by stretch-to-fit: if the design resolution ratio of width to height is different from the screen resolution ratio, your game view will be stretched.
[2] ResolutionNoBorder Full screen without black border: if the design resolution ratio of width to height is different from the screen resolution ratio, two areas of your game view will be cut.
[3] ResolutionShowAll Full screen with black border: if the design resolution ratio of width to height is different from the screen resolution ratio, two black borders will be shown.
[4] ResolutionFixedHeight Scale the content's height to screen's height and proportionally scale its width
[5] ResolutionFixedWidth Scale the content's width to screen's width and proportionally scale its height
[cc.ResolutionPolicy] [Web only feature] Custom resolution policy, constructed by cc.ResolutionPolicy

Parameters

• width Number Design resolution width.
• height Number Design resolution height.
• resolutionPolicy ResolutionPolicy | Number The resolution policy desired

getDesignResolutionSize

Returns the designed size for the view. Default resolution size is the same as 'getFrameSize'.

setRealPixelResolution

Sets the container to desired pixel resolution and fit the game content to it. This function is very useful for adaptation in mobile browsers. In some HD android devices, the resolution is very high, but its browser performance may not be very good. In this case, enabling retina display is very costy and not suggested, and if retina is disabled, the image may be blurry. But this API can be helpful to set a desired pixel resolution which is in between. This API will do the following:

1. Set viewport's width to the desired width in pixel
2. Set body width to the exact pixel resolution
3. The resolution policy will be reset with designed view size in points.

Parameters

• width Number Design resolution width.
• height Number Design resolution height.
• resolutionPolicy ResolutionPolicy | Number The resolution policy desired

setViewportInPoints

Sets view port rectangle with points.

Parameters

• x Number
• y Number
• w Number width
• h Number height

setScissorInPoints

Sets Scissor rectangle with points.

Parameters

• x Number
• y Number
• w Number
• h Number

isScissorEnabled

Returns whether GL_SCISSOR_TEST is enable

getScissorRect

Returns the current scissor rectangle

getViewportRect

Returns the view port rectangle.

getScaleX

Returns scale factor of the horizontal direction (X axis).

getScaleY

Returns scale factor of the vertical direction (Y axis).

getDevicePixelRatio

Returns device pixel ratio for retina display.

convertToLocationInView

Returns the real location in view for a translation based on a related position

Parameters

• tx Number The X axis translation
• ty Number The Y axis translation
• relatedPos Object The related position object including "left", "top", "width", "height" informations

hasEventListener

Checks whether the EventTarget object has any callback registered for a specific type of event.

Parameters

• type String The type of event.

on

Register an callback of a specific event type on the EventTarget. This type of event should be triggered via emit.

Parameters

• type String A string representing the event type to listen for.
• callback Function The callback that will be invoked when the event is dispatched.

                         The callback is ignored if it is a duplicate (the callbacks are unique).
  

  • arg1 Any arg1
  • arg2 Any arg2
  • arg3 Any arg3
  • arg4 Any arg4
  • arg5 Any arg5
• target Object The target (this object) to invoke the callback, can be null

Examples

eventTarget.on('fire', function () {
    cc.log("fire in the hole");
}, node);

off

Removes the listeners previously registered with the same type, callback, target and or useCapture, if only type is passed as parameter, all listeners registered with that type will be removed.

Parameters

• type String A string representing the event type being removed.
• callback Function The callback to remove.
• target Object The target (this object) to invoke the callback, if it's not given, only callback without target will be removed

Examples

// register fire eventListener
var callback = eventTarget.on('fire', function () {
    cc.log("fire in the hole");
}, target);
// remove fire event listener
eventTarget.off('fire', callback, target);
// remove all fire event listeners
eventTarget.off('fire');

targetOff

Removes all callbacks previously registered with the same target (passed as parameter). This is not for removing all listeners in the current event target, and this is not for removing all listeners the target parameter have registered. It's only for removing all listeners (callback and target couple) registered on the current event target by the target parameter.

Parameters

• target Object The target to be searched for all related listeners

once

Register an callback of a specific event type on the EventTarget, the callback will remove itself after the first time it is triggered.

Parameters

• type String A string representing the event type to listen for.
• callback Function The callback that will be invoked when the event is dispatched.

                         The callback is ignored if it is a duplicate (the callbacks are unique).
  

  • arg1 Any arg1
  • arg2 Any arg2
  • arg3 Any arg3
  • arg4 Any arg4
  • arg5 Any arg5
• target Object The target (this object) to invoke the callback, can be null

Examples

eventTarget.once('fire', function () {
    cc.log("this is the callback and will be invoked only once");
}, node);

dispatchEvent

Send an event with the event object.

Parameters

• event Event

removeAll

Removes all callbacks registered in a certain event type or all callbacks registered with a certain target

Parameters

• keyOrTarget String | Object The event key to be removed or the target to be removed

emit

Trigger an event directly with the event name and necessary arguments.

Parameters

• key String event type
• arg1 Any First argument
• arg2 Any Second argument
• arg3 Any Third argument
• arg4 Any Fourth argument
• arg5 Any Fifth argument

Examples

eventTarget.emit('fire', event);
eventTarget.emit('fire', message, emitter);

Events

design-resolution-changed Event

Module: cc Parent Module: cc

Emit when design resolution changed.

Index

Details

canvas-resize Event

Module: cc Parent Module: cc

Emit when canvas resize.

Index

Details