From: Adeel Kazmi Date: Fri, 28 Oct 2016 18:04:07 +0000 (+0100) Subject: (Programming Guide) Updated Custom Control Creation section X-Git-Tag: dali_1.2.14~10 X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=commitdiff_plain;h=refs%2Fchanges%2F12%2F94412%2F5 (Programming Guide) Updated Custom Control Creation section Also updated visual documentation. Change-Id: Id796aef469c0649d18c0d8974ba293d27ccb5f30 --- diff --git a/dali-toolkit/devel-api/visual-factory/visual-base.h b/dali-toolkit/devel-api/visual-factory/visual-base.h index b590484..49e8cf0 100644 --- a/dali-toolkit/devel-api/visual-factory/visual-base.h +++ b/dali-toolkit/devel-api/visual-factory/visual-base.h @@ -38,11 +38,47 @@ class Base; namespace Visual { /** - * @brief Visual provides a renderer for rendering the controls. A control may have multiple visuals. + * @brief A Visual provides a renderer for drawing a control component. A control may have multiple visuals. * - * Visuals reuses geometry, shader etc. across controls and manages the renderer and texture sets to exist only when control is on-stage. - * It also responds to actor size and color change, and provides the clipping at the renderer level. + * Visuals reuse geometry, shader etc. across controls. They ensure that the renderer and texture sets exist only when control is on-stage. + * Each visual also responds to actor size and color change, and provides clipping at the renderer level. * Note: The visual responds to the the Actor::COLOR by blending it with the 'Multiply' operator. + * + * The following properties are optional, but can be supplied in the property map to Dali::Toolkit::VisualFactory::CreateVisual(). + * + * | %Property Name | Type | + * |-------------------------|------------------| + * | customShader | MAP | + * | transform | MAP | + * + * where \b customShader is a map with at least one of the following properties: + * | %Property Name | Type | Required | Default | Description | + * |-------------------------|------------------|----------|---------|-------------| + * | vertexShader | STRING | No | "" | Vertex shader code| + * | fragmentShader | STRING | No | "" | Fragment shader code| + * | subdivideGridX | INTEGER | No | 1 | How to subdivide the grid along X | + * | subdivideGridY | INTEGER | No | 1 | How to subdivide the grid along Y | + * | shaderHints | INTEGER or ARRAY of STRING | No | NONE | Bitmask of hints @sa Dali::Shader::Hint | + * + * and \b transform is a map with the following properties: + * | %Property Name | Type | Required | Default |Description | + * |-------------------------|------------------|----------|---------|------------| + * | offset | VECTOR2 | No | (0,0) | Offset of visual from origin | + * | size | VECTOR2 | No | (1,1) | size of visual | + * | origin | INTEGER or STRING | No | CENTER | origin of the visual @sa Dali::Toolkit::Align | + * | anchorPoint | INTEGER or STRING | No | CENTER | anchor point of the visual @sa Dali::Toolkit::Align | + * | offsetSizeMode | VECTOR4 | No | (0,0,0,0) | See below | + * + * + * offsetSizeMode describes whether the offset and the size are + * relative or absolute by using 0 or 1 respectively in the corresponding + * components (offsetSizeMode.xy for offset.xy; offsetSizeMode.zw for size.xy). + * + * Relative means that the component describes a factor of the parent control size; + * size.x = 1 means full width; size.y = 0.5 means half height. + * + * Absolute means that the component describes world units (equivalent to pixels) + * */ class DALI_IMPORT_API Base : public BaseHandle { diff --git a/docs/content/images/creating-custom-controls/control-handle-body.png b/docs/content/images/creating-custom-controls/control-handle-body.png index 4349789..14cfeb2 100644 Binary files a/docs/content/images/creating-custom-controls/control-handle-body.png and b/docs/content/images/creating-custom-controls/control-handle-body.png differ diff --git a/docs/content/shared-javascript-and-cpp-documentation/creating-custom-controls.md b/docs/content/shared-javascript-and-cpp-documentation/creating-custom-controls.md index 27239b3..82345bb 100644 --- a/docs/content/shared-javascript-and-cpp-documentation/creating-custom-controls.md +++ b/docs/content/shared-javascript-and-cpp-documentation/creating-custom-controls.md @@ -13,13 +13,26 @@ Custom controls are created using the [handle/body idiom](@ref handle-body-idiom ![ ](../assets/img/creating-custom-controls/control-handle-body.png) ![ ](creating-custom-controls/control-handle-body.png) +Namespaces are important ++ The handle & body classes should have the same name but in different namespaces ++ TypeRegistry relies on this convention ++ Here our custom control requires + + MyControl + + Internal::MyControl + ### General Guidelines: + Try to avoid adding C++ APIs as they become difficult to maintain. + Use **properties** as much as possible as Controls should be data driven. + These controls will be used through JavaScript and JSON files so need to be compatible. -+ Bear in mind that the Control is required to update when the properties change, not just the first time they are set (to deal with style change). ++ Bear in mind that the Control can be updated when the properties change (e.g. style change) + + Ensure control deals with these property changes gracefully + + Not just the first time they are set ++ Use Visuals rather than creating several child Actors + + DALi rendering pipeline more efficient + Accessibility actions should be considered when designing the Control. + Consider using signals if the application needs to be react to changes in the control state. ++ Use of Gestures should be preferred over analysing raw touch events ++ Check if you need to chain up to base class if overriding certain methods ___________________________________________________________________________________________________ @@ -125,7 +138,8 @@ This should be overridden by the custom ui control. // C++ void MyUIControlImpl::OnInitialize() { - // Create visuals, register events etc. + // Create visuals using the VisualFactory, register events etc. + // Register any created visuals with Control base class } ~~~ ___________________________________________________________________________________________________ @@ -134,13 +148,14 @@ ________________________________________________________________________________ Dali::Toolkit::Internal::Control provides several behaviours which are specified through its constructor (@ref Dali::Toolkit::Internal::Control::Control()). -| Behaviour | Description | -|--------------------------------------|-------------------------------------------------------------------------| -| ACTOR_BEHAVIOUR_NONE | No behaviour required. | -| REQUIRES_HOVER_EVENTS | If our control requires [hover events](@ref creating-controls-events). | -| REQUIRES_WHEEL_EVENTS | If our control requires [wheel events](@ref creating-controls-events). | -| REQUIRES_STYLE_CHANGE_SIGNALS | True if need to monitor style change signals such as Theme/Font change. | -| REQUIRES_KEYBOARD_NAVIGATION_SUPPORT | True if need to support keyboard navigation. | +| Behaviour | Description | +|--------------------------------------|----------------------------------------------------------------------------------------------------------------| +| CONTROL_BEHAVIOUR_DEFAULT | Default behavior (size negotiation is on, style change is monitored, event callbacks are not called. | +| DISABLE_SIZE_NEGOTIATION | If our control does not need size negotiation, i.e. control will be skipped by the size negotiation algorithm. | +| REQUIRES_HOVER_EVENTS | If our control requires [hover events](@ref creating-controls-events). | +| REQUIRES_WHEEL_EVENTS | If our control requires [wheel events](@ref creating-controls-events). | +| DISABLE_STYLE_CHANGE_SIGNALS | True if control should not monitor style change signals such as Theme/Font change. | +| REQUIRES_KEYBOARD_NAVIGATION_SUPPORT | True if need to support keyboard navigation. | ___________________________________________________________________________________________________ ### Touch, Hover & Wheel Events {#creating-controls-events} @@ -373,31 +388,62 @@ void MyUIControlImpl::OnStageDisconnection() ___________________________________________________________________________________________________ -### Size {#creating-controls-size} +### Size Negotiation {#creating-controls-size-negotiation} -Methods are provided that can be overridden if notification is required when our control's size is manipulated. -An up call to the Control class is necessary if these methods are overridden. +The following methods must be overridden for size negotiation to work correctly with a custom control. ~~~{.cpp} // C++ -void MyUIControlImpl::OnSizeSet( const Vector3& targetSize ) +Vector3 MyUIControlImpl::GetNaturalSize() +{ + // Return the natural size of the control + // This depends on our layout + // If we have one visual, then we can return the natural size of that + // If we have more visuals, then we need to calculate their positions within our control and work out the overall size we would like our control to be + + // After working out the natural size of visuals that belong to this control, + // should also chain up to ensure other visuals belonging to the base class are + // also taken into account: + Vector2 baseSize = Control::GetNaturalSize(); // returns the size of the background. +} +~~~ +~~~{.cpp} +// C++ +float MyUIControlImpl::GetHeightForWidth( float width ) { - // Up call to Control - Control::OnSizeSet( targetSize ); + // Called by the size negotiation algorithm if we have a fixed width + // We should calculate the height we would like our control to be for that width + + // Should also chain up to determine the base class's preferred height: + float baseHeight = Control::GetHeightForWidth( width ); - // Do any other operations required upon size set } ~~~ ~~~{.cpp} // C++ -void MyUIControlImpl::OnSizeAnimation( Animation& animation, const Vector3& targetSize ) +float MyUIControlImpl::GetWidthForHeight( float height ) { - // Up call to Control - Control::OnSizeAnimation( animation, targetSize ); + // Called by the size negotiation algorithm if we have a fixed height + // We should calculate the width we would like our control to be for that height - // Do any other operations required upon size animation + // Should also chain up to determine the base class's preferred width: + float baseWidth = Control::GetWidth( height ); +} +~~~ +~~~{.cpp} +// C++ +void MyUIControlImpl::OnRelayout( const Vector2& size, RelayoutContainer& container ) +{ + // The size is what we have been given and what our control needs to fit into + // Here, we need to set the position and the size of our visuals + // If we have other controls/actors as children + // - Add the control/actor to the container paired with the size required + // - To ensure this works, you need to set up the control with a relayout policy of USE_ASSIGNED_SIZE + // - DO NOT CALL SetSize on this control: This will trigger another size negotiation calculation + // DO NOT chain up to base class. } ~~~ +More information on size negotiation can be found [here](@ref size-negotiation-controls). ___________________________________________________________________________________________________ diff --git a/docs/content/shared-javascript-and-cpp-documentation/visuals.md b/docs/content/shared-javascript-and-cpp-documentation/visuals.md index 3ae2c31..457d8e1 100644 --- a/docs/content/shared-javascript-and-cpp-documentation/visuals.md +++ b/docs/content/shared-javascript-and-cpp-documentation/visuals.md @@ -6,7 +6,7 @@ Visuals provide reusable rendering logic which can be used by all controls. This means that custom controls do not have to create actors, they can just reuse the existing visuals which increases performance. -Visuals reuse geometry, shaders etc. across controls and manages the renderer and material to exist only when the control is on-stage. +Visuals reuse geometry, shaders etc. across controls and manages the renderer and texture to exist only when the control is on-stage. Additionally, they respond to actor size and color change, while also providing clipping at the renderer level. DALi provides the following visuals: @@ -22,11 +22,71 @@ Controls can provide properties that allow users to specify the visual type ( vi Setting visual properties are done via a property map. The **visualType** field in the property map specifies the visual to use/create. This is required to avoid ambiguity as multiple visuals may be capable of rendering the same contents. + +Visuals have a **transform** field in the property map to allow layouting within a control. If this field is not set, then the visual defaults to filling the control. The **transform** field has a property map with the following keys: + +| Property | String | Type | Required | Description | +|-------------------------------------------------|----------|:-------:|:--------:|---------------------------| +| Dali::Toolkit::Visual::Transform::Property::OFFSET | offset | VECTOR2 | No | The offset of the visual. | +| Dali::Toolkit::Visual::Transform::Property::SIZE | size | VECTOR2 | No | The size of the visual. | +| Dali::Toolkit::Visual::Transform::Property::OFFSET_SIZE_MODE | offsetSizeMode | VECTOR4 | No | Whether the size or offset components are Relative or Absolute [More info](@ref offset-size-mode)| +| Dali::Toolkit::Visual::Transform::Property::ORIGIN | origin | INTEGER or STRING | No | The origin of the visual within the control's area. [More info](@ref align-type)] | +| Dali::Toolkit::Visual::Transform::Property::ANCHOR_POINT | anchorPoint | INTEGER or STRING | No | The anchor point of the visual. [More info](@ref align-type)| + + +## Offset & size modes {#offset-size-mode} + +The offset and size modes can be either Relative or Absolute. The offset modes are in the x and y components of the offsetSizeMode property, and map to the offset's x and y components respectively. The size modes are in the z and w components of the offsetSizeMode property, and map to the size's x and y components, respectively. + +A mode value of 0 represents a Relative mode, in which case the size or offset value represents a ratio of the control's size. A mode value of 1 represents an Absolute mode, in which case the size or offset value represents world units (pixels). + +For example, an offsetSizeMode of [0, 0, 1, 1], an offset of (0, 0.25) and a size of (20, 20) means the visual will be 20 pixels by 20 pixels in size, positioned 25% above the center of the control. + + +## Alignment {#align-type} +| Enumeration | String | Description | +|------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------| +| Dali::Toolkit::Align::TOP_BEGIN | TOP_BEGIN | Aligns to the top of the vertical axis and the beginning of the horizontal axis (The left or right edge in Left-To-Right or Right-to-Left layouts, respectively) | +| Dali::Toolkit::Align::TOP_CENTER | TOP_CENTER | Aligns to the top of the vertical axis and the center of the horizontal axis | +| Dali::Toolkit::Align::TOP_END | TOP_END | Aligns to the top of the vertical axis and end of the horizontal axis (The right or left edge in Left-To-Right or Right-to-Left layouts, respectively) | +| Dali::Toolkit::Align::CENTER_BEGIN | CENTER_BEGIN | Aligns to the center of the vertical axis and the beginning of the horizontal axis| +| Dali::Toolkit::Align::CENTER | CENTER | Aligns to the center of the control | +| Dali::Toolkit::Align::CENTER_END | CENTER_END | Aligns to the center of the vertical axis and end of the horizontal axis | +| Dali::Toolkit::Align::BOTTOM_BEGIN | BOTTOM_BEGIN | Aligns to the bottom of the vertical axis and the beginning of the horizontal axis| +| Dali::Toolkit::Align::BOTTOM_CENTER | BOTTOM_CENTER | Aligns to the bottom of the vertical axis and the center of the horizontal axis +| Dali::Toolkit::Align::BOTTOM_END | BOTTOM_END | Aligns to the bottom of the vertical axis and end of the horizontal axis | + +Visuals also have a custom **shader** property. Whilst it's possible to change the shader, please note that some visuals rely on the vertex shader to perform certain functions. For example, the NPatch visual uses the vertex shader to perform the stretching. The **shader** property is a Property::Map with the following keys: + + +| Property | String | Type | Required | Description | +|-------------------------------------------------|----------|:-------:|:--------:|---------------------------| +| Dali::Toolkit::Visual::Shader::Property::VERTEX_SHADER | vertexShader | STRING | No | The vertex shader code. | +| Dali::Toolkit::Visual::Shader::Property::FRAGMENT_SHADER | fragmentShader | STRING | No | The fragment shader code. | +| Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_X | subdivideGridX | INTEGER | No | How to subdivide the grid along the X-Axis. Defaults to 1 | +| Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_Y | subdivideGridY | INTEGER | No | How to subdivide the grid along the Y-Axis. Defaults to 1 | +| Dali::Toolkit::Visual::Shader::Property::HINTS | hints | INTEGER or ARRAY of STRING | No | Shader hints bitmask [More info](@ref shader-hints) | + +## Shader hints {#shader-hints} + +This is a bitmask giving hints to the renderer about what the shader does, in order to help the rendering system optimise it's rendering. + +The bitmask can have the following values: + +| Value | Description | +|-------------------------------------------|----------------------------------------| +| Dali::Shader::Hint::NONE | No hints | +| Dali::Shader::Hint::OUTPUT_IS_TRANSPARENT | Might generate transparent alpha from opaque inputs | +| Dali::Shader::Hint::MODIFIES_GEOMETRY | Might change the position of vertices - this disables culling optimizations | + + +See also Dali::Shader::Hint::Value enumeration. + ___________________________________________________________________________________________________ ## Color Visual {#color-visual} -Renders a solid color to the control's quad. +Renders a color to the visual's quad geometry. ![ ](../assets/img/visuals/color-visual.png) ![ ](visuals/color-visual.png) @@ -37,7 +97,7 @@ Renders a solid color to the control's quad. | Property | String | Type | Required | Description | |-------------------------------------------------|----------|:-------:|:--------:|---------------------------| -| Dali::Toolkit::ColorVisual::Property::MIX_COLOR | mixColor | VECTOR4 | Yes | The solid color required. | +| Dali::Toolkit::ColorVisual::Property::MIX_COLOR | mixColor | VECTOR4 | Yes | The color required. | ### Usage @@ -66,7 +126,7 @@ ________________________________________________________________________________ ## Gradient Visual {#gradient-visual} -Renders a smooth transition of colors to the control's quad. +Renders a smooth transition of colors to the visual's quad geometry. Both Linear and Radial gradients are supported. @@ -108,9 +168,9 @@ Indicates what happens if the gradient starts or ends inside the bounds of the t | Enumeration | String | Description | |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------| -| Dali::Toolkit::GradientVisual::SpreadMethod::PAD | PAD | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad. | -| Dali::Toolkit::GradientVisual::SpreadMethod::REFLECT | REFLECT | Reflect the gradient pattern start-to-end, end-to-start, start-to-end etc. until the quad is filled. | -| Dali::Toolkit::GradientVisual::SpreadMethod::REPEAT | REPEAT | Repeat the gradient pattern start-to-end, start-to-end, start-to-end etc. until the quad is filled. | +| Dali::Toolkit::GradientVisual::SpreadMethod::PAD | PAD | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad geometry. | +| Dali::Toolkit::GradientVisual::SpreadMethod::REFLECT | REFLECT | Reflect the gradient pattern start-to-end, end-to-start, start-to-end etc. until the quad geometry is filled. | +| Dali::Toolkit::GradientVisual::SpreadMethod::REPEAT | REPEAT | Repeat the gradient pattern start-to-end, start-to-end, start-to-end etc. until the quad geometry is filled. | ### Usage @@ -215,7 +275,7 @@ ________________________________________________________________________________ ## Image Visual {#image-visuals} -Renders an image into the control's quad. +Renders an image into the visual's geometry. Depending on the extension of the image, a different visual is provided to render the image onto the screen. @@ -227,7 +287,7 @@ ___________________________ ### Normal {#image-visual} -Renders a raster image ( jpg, png etc.) into the control's quad. +Renders a raster image ( jpg, png etc.) into the visual's quad geometry. ![ ](../assets/img/visuals/image-visual.png) ![ ](visuals/image-visual.png) @@ -271,7 +331,7 @@ ________________________________________________________________________________ ### N-Patch {#n-patch-visual} -Renders an n-patch or a 9-patch image into the control's quad. +Renders an n-patch or a 9-patch image. Uses non-quad geometry. Both geometry and texture are cached to reduce memory consumption if the same n-patch image is used elsewhere. ![ ](../assets/img/visuals/n-patch-visual.png) ![ ](visuals/n-patch-visual.png) @@ -314,7 +374,7 @@ ________________________________________________________________________________ ### SVG {#svg-visual} -Renders a svg image into the control's quad. +Renders a svg image into the visual's quad geometry. #### Features: SVG Tiny 1.2 specification @@ -384,7 +444,7 @@ ________________________________________________________________________________ ## Border Visual {#border-visual} -Renders a solid color as an internal border to the control's quad. +Renders a color as an internal border to the visual's geometry. ![ ](../assets/img/visuals/border-visual.png) ![ ](visuals/border-visual.png) @@ -611,7 +671,7 @@ ________________________________________________________________________________ ## Wireframe Visual {#wireframe-visual} -Renders a wireframe around a control's quad. +Renders a wireframe around a quad geometry. Is mainly used for debugging and is the visual that replaces all other visuals when [Visual Debug Rendering](@ref debugrendering) is turned on. ![ ](../assets/img/visuals/wireframe-visual.png)