X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fdevel-api%2Fvisual-factory%2Fvisual-base.h;h=4e2e0f529a4af4c0a55f2c0aaad02240a4ad09e6;hp=40864e5af1d59a16200ce10d7f3856e8c1610253;hb=7f0a28e0f0da67178997e5a647bdc471e8dcb652;hpb=11ed6421771d05113ae1a6510167d8c2557ac20e diff --git a/dali-toolkit/devel-api/visual-factory/visual-base.h b/dali-toolkit/devel-api/visual-factory/visual-base.h index 40864e5..4e2e0f5 100644 --- a/dali-toolkit/devel-api/visual-factory/visual-base.h +++ b/dali-toolkit/devel-api/visual-factory/visual-base.h @@ -1,7 +1,7 @@ #ifndef DALI_TOOLKIT_VISUAL_BASE_H #define DALI_TOOLKIT_VISUAL_BASE_H /* - * Copyright (c) 2016 Samsung Electronics Co., Ltd. + * Copyright (c) 2017 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -38,11 +38,43 @@ 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 | + * | offsetPolicy | VECTOR2 | No | ( RELATIVE, RELATIVE ) | @sa Dali::Toolkit::DevelVisual::Transform::Policy | + * | sizePolicy | VECTOR2 | No | ( RELATIVE, RELATIVE ) | @sa Dali::Toolkit::DevelVisual::Transform::Policy | + * + * 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 { @@ -76,72 +108,76 @@ public: Base& operator=( const Base& handle ); /** - * @brief Set the size of the painting area. + * @brief Set the name of the visual * - * @param[in] size The size of the painting area. + * Used by the styling system to animate properties + * @param[in] name The name to give the visual */ - void SetSize( const Vector2& size ); + void SetName( const std::string& name ); /** - * @brief Get the size of the painting area. + * @brief Get the name of the visual * - * @return The size of the visual's painting area. + * Used by the styling system to animate properties + * @return The name of the visual */ - const Vector2& GetSize() const; + const std::string& GetName(); /** - * @brief Return the natural size of the visual. + * @brief Sets the transform and the control size * - * Deriving classes stipulate the natural size and by default a visual has a ZERO natural size. - * - * @param[out] naturalSize The visual's natural size + * @param[in] transform A property map describing the transform + * @param[in] controlSize The size of the parent control for visuals that need to scale internally. */ - void GetNaturalSize( Vector2& naturalSize ) const; + void SetTransformAndSize( const Dali::Property::Map& transform, Size controlSize ); /** - * @brief Set the depth index of this visual. + * @brief Returns the height for a given width. * - * Depth-index controls draw-order for overlapping visuals. - * Visuals with higher depth indices are rendered in front of other visual with smaller values + * @param[in] width Width to use. * - * @param[in] index The depth index of this visual. + * @return The height based on the width. */ - void SetDepthIndex( float index ); + float GetHeightForWidth( float width ); /** - * @brief Get the depth index of this visual + * @brief Returns the width for a given height. * - * @return The depth index of this visual. + * @param[in] height Height to use. + * + * @return The width based on the height. */ - float GetDepthIndex() const; + float GetWidthForHeight( float height ); /** - * @brief Visual needs to know when when the control is put on to the stage to add the renderer. + * @brief Return the natural size of the visual. * - * This function should be called when the control is put on to the stage. + * Deriving classes stipulate the natural size and by default a + * visual has a ZERO natural size. * - * @param[in] actor The actor using this visual. - * @post SetOffStage should be called with the same actor when the control is put off stage otherwise memory will be leaked + * @note A visual may not actually have a natural size until it has + * been placed on stage and acquired all it's resources. + * + * @param[out] naturalSize The visual's natural size */ - void SetOnStage( Actor& actor ); + void GetNaturalSize( Vector2& naturalSize ); /** - * @brief Visual needs to know when when the control is removed from the stage to remove the renderer. + * @brief Set the depth index of this visual. * - * This function should be called when the control is removed from the stage + * Depth-index controls draw-order for overlapping visuals. + * Visuals with higher depth indices are rendered in front of other visual with smaller values * - * @param[in] actor The actor using this visual. + * @param[in] index The depth index of this visual. */ - void SetOffStage( Actor& actor ); + void SetDepthIndex( float index ); /** - * @brief Remove the renderer from the actor and reset the visual self. - * - * This function can be called with an empty handle. If the visual is empty, this is a no-op. + * @brief Get the depth index of this visual * - * @param[in] actor The actor to be set off stage. + * @return The depth index of this visual. */ - void RemoveAndReset( Actor& actor ); + float GetDepthIndex() const; /** * @brief Create the property map representing this visual.