.. _stdlib_ui_canvas_component:

========
UICanvas
========


++++++++++++
Enumerations
++++++++++++

.. _enum-public_components-RenderMode:

.. das:attribute:: RenderMode

:Values: * **ScreenSpaceOverlay** = 0 - Render canvas as overlay

         * **ScreenSpaceCamera** = 1 - Render ui elements in screen space, but performing depth test against the 3D scene(WIP)

         * **WorldSpace** = 2 - Render ui elements in world space(WIP)


.. _enum-public_components-ScreenMode:

.. das:attribute:: ScreenMode

Define the mode used to scale the canvas when the screen size changes.


:Values: * **Custom** = 0 - Canvas size and scale completely controlled by the user.

         * **Fit** = 1 - Scale canvas to fit the screen and keep aspect ratio.

         * **FitExtend** = 2 - Scale canvas to fit the smallest screen dimension and another dimension is extended to fill the screen. Don't keep aspect ratio. Default mode.

         * **Fullscreen** = 3 - Canvas size is set to the screen size. Don't scale canvas and don't keep aspect ratio.


+++++++
Classes
+++++++

.. _struct-ui_canvas_component-UICanvas:

.. das:attribute:: UICanvas : NativeComponent

.. note:: ``UIFrame``  component is automatically added to the node if it is not already present

This component is used to enable rendering of UI children.

Example::

    let canvas = create_node(NodeData())
    add_component(canvas, new UICanvas())

    let textNode = create_node(NodeData(
        parent = canvas,
        position = float3(0.0, 0.0, 0.0)
    ))
    add_component(textNode, new UIText(
        text = "Hello, World!",
        fontSize = 48.0
    ))

    let imageNode = create_node(NodeData(
        parent = canvas,
        position = float3(0.0, 200.0, 0.0)
    ))
    add_component(imageNode, new UIImage(
        textureId = request_texture("image.png"),
        size = float2(300., 300.)
    ))

    // Need any camera for UI to be seen
    add_component(create_node(NodeData()), new Camera())


:Fields: * **initialSize** : float2 = float2(-1f,-1f) - Initial size of the canvas. Automatically calculated from the size of the canvas. Will be used to calculate aspect ratio.


.. _function-ui_canvas_component_UICanvas_rq_on_initialize_UICanvas:

.. das:function:: UICanvas.on_initialize()



.. _function-ui_canvas_component_UICanvas_rq_on_destroy_UICanvas:

.. das:function:: UICanvas.on_destroy()



:Properties:

.. _function-ui_canvas_component__dot__rq_renderMode_UICanvas:

.. das:operator:: UICanvas.renderMode() : RenderMode



.. _function-ui_canvas_component__dot__rq_renderMode_rq_clone_UICanvas_RenderMode:

.. das:operator:: UICanvas.renderMode =(value: RenderMode)

The render mode of the canvas. Default is ScreenSpaceOverlay

:Arguments: * **value** :  :ref:`RenderMode <enum-public_components-RenderMode>` 

.. _function-ui_canvas_component__dot__rq_localPosition2D_UICanvas:

.. das:operator:: UICanvas.localPosition2D() : float2



.. _function-ui_canvas_component__dot__rq_localPosition2D_rq_clone_UICanvas_float2:

.. das:operator:: UICanvas.localPosition2D =(value: float2)

Local position of the canvas. Default is (0, 0).

:Arguments: * **value** : float2

.. _function-ui_canvas_component__dot__rq_size_UICanvas:

.. das:operator:: UICanvas.size() : float2



.. _function-ui_canvas_component__dot__rq_size_rq_clone_UICanvas_float2:

.. das:operator:: UICanvas.size =(value: float2)

Size of the image. This field can only be accessed in code. The same effect can be achieved by changing ``UIFrame.size`` property.

To change the value in editor use ``UIFrame.size`` of the node.

:Arguments: * **value** : float2

.. _function-ui_canvas_component__dot__rq_pivot_UICanvas:

.. das:operator:: UICanvas.pivot() : float2



.. _function-ui_canvas_component__dot__rq_pivot_rq_clone_UICanvas_float2:

.. das:operator:: UICanvas.pivot =(value: float2)

Node's origin relative to it's content. Left-top of the content is (0,0), right-bottom is (1,1). Default is (0.5, 0.5).

:Arguments: * **value** : float2

.. _function-ui_canvas_component__dot__rq_screenMode_UICanvas:

.. das:operator:: UICanvas.screenMode() : ScreenMode



.. _function-ui_canvas_component__dot__rq_screenMode_rq_clone_UICanvas_ScreenMode:

.. das:operator:: UICanvas.screenMode =(value: ScreenMode)

Indicates whether the UI canvas component should be displayed in fullscreen mode. Works only in ScreenSpaceOverlay mode.

:Arguments: * **value** :  :ref:`ScreenMode <enum-public_components-ScreenMode>`