namespace Dali
{
/**
- * @internal
* @addtogroup dali_core_actors
* @{
*/
}
/**
- * @deprecated Use ImageView instead.
* @brief An actor for displaying images.
*
* Allows the developer to add an actor to stage which displays the content of an Image object.
*
* If an ImageActor is created without setting size, then the actor takes the size of the image -
* this is the natural size.
- * Setting a size on the ImageActor, e.g through the SetSize api or through an animation will
+ * Setting a size on the ImageActor, e.g through the @ref Actor::SetSize api or through an animation will
* stop the natural size being used.
*
- * If a pixel area is set on an ImageActor with natural size, the actor size will change
- * to match the pixel area. If a pixel area is set on an ImageActor that has had it's size set,
- * then the size doesn't change, and the partial image will be stretched to fill the set size.
- *
- * Clearing the pixel area on an Image actor with natural size will cause the actor to show the
- * whole image again, and will change size back to that of the image.
- *
- * Clearing the pixel area on an Image actor with a set size will cause the actor to show the
- * whole image again, but will not change the image size.
* @since_tizen 2.4
+ * @remarks Use of ImageActor should be avoided unless shader effects need to be applied.
+ * For general purpose, use Toolkit::ImageView which has much better performance.
+ * @see Toolkit::ImageView
*/
class DALI_IMPORT_API ImageActor : public Actor
{
/**
* @brief An enumeration of properties belonging to the ImageActor class.
- * Properties additional to RenderableActor.
* @since_tizen 2.4
*/
struct Property
{
enum
{
- PIXEL_AREA = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "pixel-area", type Rect<int>
- STYLE, ///< name "style", type std::string
- BORDER, ///< name "border", type Vector4
- IMAGE, ///< name "image", type Map {"filename":"", "load-policy":...}
+ /**
+ * @brief name "pixel-area", type Rect<int>
+ * @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
+ */
+ PIXEL_AREA = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX,
+ /**
+ * @brief name "style", type std::string
+ * @since_tizen 2.4
+ */
+ STYLE,
+ /**
+ * @brief name "border", type Vector4
+ * @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
+ */
+ BORDER,
+ /**
+ * @brief name "image", type Map {"filename":"", "load-policy":...}
+ * @since_tizen 2.4
+ */
+ IMAGE,
};
};
/**
* @brief Style determines how the Image is rendered.
- *
- * @code
- * STYLE_QUAD:
- *
- * 0---------2 0-----------------2
- * | /| | /|
- * | A / | | A / |
- * | / | | / |
- * | / | SCALE (X) | / |
- * | / | --------> | / |
- * | / | | / |
- * | / | | / |
- * | / B | | / B |
- * |/ | |/ |
- * 1---------3 1-----------------3
- *
- * Image is rendered as a textured rectangle. The texture
- * is scaled uniformly as the quad is resized.
- *
- * STYLE_NINE_PATCH:
- *
- * |---|---------------|---| |---|-----------------------------|---|
- * | 1 | 2 | 3 | | 1 | 2 | 3 |
- * |---|---------------|---| |---|-----------------------------|---|
- * | | | | | | | |
- * | | | | | | | |
- * | 4 | 5 | 6 | SCALE | | | |
- * | | | | ----> | | | |
- * | | | | | 4 | 5 | 6 |
- * |-------------------|---| | | | |
- * | 7 | 8 | 9 | | | | |
- * |---|---------------|---| | | | |
- * |---------------------------------|---|
- * | 7 | 8 | 9 |
- * |---|-----------------------------|---|
- *
- * Image is rendered as a textured rectangle. The texture
- * is scaled differently over each of the 9 sections.
- *
- * STYLE_NINE_PATCH_NO_CENTER:
- *
- * Image is rendered in the same way as STYLE_NINE_PATCH,
- * but the Center Section (5) is not rendered.
- * @endcode
- *
- * Visualise a Picture Frame:
- *
- * - Corner sections (1,3,7,9) are not scaled, regardless
- * of how big the Image is.
- * - Horizontal edge sections (2,8) are scaled only in the
- * X axis as the image increases in width.
- * - Vertical edge sections (4,6) are scaled only in the
- * Y axis as the image increases in height.
- * - Center section (5) is scaled in both X and Y axes as
- * the image increases in width and/or height.
- *
- * Note: If GRID hints are enabled (via a Shader that requires it),
- * the above geometry will be further subdivided into rectangles of
- * approx. 40x40 in size. STYLE_NINE_PATCH_NO_CENTER is not supported
- * yet when GRID hints are enabled.
* @since_tizen 2.4
*/
enum Style
{
- STYLE_QUAD, ///< As a simple quad.
- STYLE_NINE_PATCH, ///< As a nine-patch.
- STYLE_NINE_PATCH_NO_CENTER ///< As a nine-patch without center section being rendered.
+ /**
+ * @brief As a simple quad.
+ * @since_tizen 2.4
+ */
+ STYLE_QUAD,
+ /**
+ * @brief As a nine-patch.
+ * @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
+ */
+ STYLE_NINE_PATCH,
+ /**
+ * @brief As a nine-patch without center section being rendered.
+ * @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
+ */
+ STYLE_NINE_PATCH_NO_CENTER
};
/**
* @brief Pixel area is relative to the top-left (0,0) of the image.
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
*/
typedef Rect<int> PixelArea;
/**
* @brief Create an uninitialized ImageActor handle.
*
- * This can be initialized with ImageActor::New(...)
- * Calling member functions with an uninitialized Dali::Object is not allowed.
+ * This can be initialized with ImageActor::New(...).
+ * Calling member functions with an unintialized ImageActor handle is not allowed.
* @since_tizen 2.4
*/
ImageActor();
static ImageActor New(Image image, PixelArea pixelArea);
/**
- * @brief Downcast an Object handle to ImageActor.
+ * @brief Downcast a handle to ImageActor handle.
*
*
* If handle points to a ImageActor the downcast produces valid
* handle. If not the returned handle is left uninitialized.
*
* @since_tizen 2.4
- * @param[in] handle to An object
- * @return handle to a ImageActor or an uninitialized handle
+ * @param[in] handle Handle to an object
+ * @return Handle to a ImageActor or an uninitialized handle
*/
static ImageActor DownCast( BaseHandle handle );
*
* @since_tizen 2.4
* @param [in] rhs The actor to copy.
+ * @return A reference to this
*/
ImageActor& operator=(const ImageActor& rhs);
/**
* @brief Set the image rendered by the actor.
+ *
* Set the image rendered by the actor.
* If actor was already displaying a different image, the old image is dropped and actor may
* temporarily display nothing. Setting an empty image (handle) causes the current image to be
* dropped and actor displays nothing.
* The actor will take the image's natural size unless a custom size
- * is chosen, e.g. via Actor:SetSize()
+ * is chosen, e.g. via Actor::SetSize()
*
* @since_tizen 2.4
* @param [in] image The image to display.
* @brief Set a region of the image to display, in pixels.
*
* When the image is loaded the actor's size will be reset to the pixelArea,
- * unless a custom size was chosen, e.g. via Actor:SetSize().
- * Note! PixelArea should be inside the image data size. It gets clamped by GL
+ * unless a custom size was chosen, e.g. via Actor::SetSize().
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param [in] pixelArea The area of the image to display.
* This in pixels, relative to the top-left (0,0) of the image.
- * @pre image must be initialized.
+ * @pre Image must be initialized.
+ * @note PixelArea should be inside the image data size. It gets clamped by GL
*/
void SetPixelArea(const PixelArea& pixelArea);
* @brief Retrieve the region of the image to display, in pixels.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @return The pixel area, or a default-constructed area if none was set.
- * @pre image must be initialized.
+ * @pre Image must be initialized.
*/
PixelArea GetPixelArea() const;
*
* @since_tizen 2.4
* @param [in] style The new style.
- * @pre image must be initialized.
+ * @pre Image must be initialized.
*/
void SetStyle(Style style);
*
* @since_tizen 2.4
* @return The rendering style.
- * @pre image must be initialized.
+ * @pre Image must be initialized.
*/
Style GetStyle() const;
/**
- * @brief Set the border used with STYLE_NINE_PATCH.
+ * @brief Set the border used with ImageActor::STYLE_NINE_PATCH.
*
* The values are in pixels from the left, top, right, and bottom of the image respectively.
- * i.e. SetNinePatchBorder( Vector4(1,2,3,4) ) sets the left-border to 1, top-border to 2, right-border to 3, and bottom-border to 4 pixels.
+ * i.e. ImageActor::SetNinePatchBorder( Vector4(1,2,3,4) ) sets the left-border to 1, top-border to 2, right-border to 3, and bottom-border to 4 pixels.
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param [in] border The new nine-patch border.
*/
void SetNinePatchBorder(const Vector4& border);
/**
- * @brief Retrieve the border used with STYLE_NINE_PATCH.
+ * @brief Retrieve the border used with ImageActor::STYLE_NINE_PATCH.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @return The nine-patch border.
*/
Vector4 GetNinePatchBorder() const;
*
* The offset can be altered for each coplanar actor hence allowing an order of painting.
* @since_tizen 2.4
- * @param [in] depthOffset the offset to be given to the actor. Positive values pushing it further back.
+ * @remarks Avoid using this method as it's a legacy code. Rendering order of actors on the same z position should be
+ * determined by the depth level in the scene graph tree, not by this method
+ * @param [in] depthOffset The offset to be given to the actor. Positive values pushing it further back.
* @pre The Actor has been initialized.
+ * @see Layer::Behavior
*/
void SetSortModifier(float depthOffset);
*
* The offset can be altered for each coplanar actor hence allowing an order of painting.
* @since_tizen 2.4
- * @return the offset that has been given to the actor. Positive values pushing it further back.
+ * @remarks Avoid using this method as it's a legacy code. Rendering order of actors on the same z position should be
+ * determined by the depth level in the scene graph tree, not by this method
+ * @return The offset that has been given to the actor. Positive values pushing it further back.
* @pre The Actor has been initialized.
+ * @see Layer::Behavior
*/
float GetSortModifier() const;
* </ul>
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[in] mode The blending mode.
*/
void SetBlendMode( BlendingMode::Type mode );
* @brief Retrieves the blending mode.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @return The blending mode, one of BlendingMode::OFF, BlendingMode::AUTO or BlendingMode::ON.
*/
BlendingMode::Type GetBlendMode() const;
* @brief Specify the pixel arithmetic used when the actor is blended.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[in] srcFactorRgba Specifies how the red, green, blue, and alpha source blending factors are computed.
- * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
- * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
- * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
*
* @param[in] destFactorRgba Specifies how the red, green, blue, and alpha destination blending factors are computed.
- * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
- * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
- * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
*/
void SetBlendFunc( BlendingFactor::Type srcFactorRgba, BlendingFactor::Type destFactorRgba );
* @brief Specify the pixel arithmetic used when the actor is blended.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[in] srcFactorRgb Specifies how the red, green, and blue source blending factors are computed.
- * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
- * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
- * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
*
* @param[in] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
- * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
- * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
- * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
*
* @param[in] srcFactorAlpha Specifies how the alpha source blending factor is computed.
- * The options are the same as for srcFactorRgb.
*
* @param[in] destFactorAlpha Specifies how the alpha source blending factor is computed.
- * The options are the same as for destFactorRgb.
*/
void SetBlendFunc( BlendingFactor::Type srcFactorRgb, BlendingFactor::Type destFactorRgb,
BlendingFactor::Type srcFactorAlpha, BlendingFactor::Type destFactorAlpha );
* @brief Query the pixel arithmetic used when the actor is blended.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[out] srcFactorRgb Specifies how the red, green, blue, and alpha source blending factors are computed.
* @param[out] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
* @param[out] srcFactorAlpha Specifies how the red, green, blue, and alpha source blending factors are computed.
/**
* @brief Specify the equation used when the actor is blended.
*
- * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT.
+ * The options are BlendingEquation::ADD, BlendingEquation::SUBTRACT, or BlendingEquation::REVERSE_SUBTRACT.
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[in] equationRgba The equation used for combining red, green, blue, and alpha components.
*/
void SetBlendEquation( BlendingEquation::Type equationRgba );
* @brief Specify the equation used when the actor is blended.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[in] equationRgb The equation used for combining red, green, and blue components.
* @param[in] equationAlpha The equation used for combining the alpha component.
- * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT.
+ * The options are BlendingEquation::ADD, BlendingEquation::SUBTRACT, or BlendingEquation::REVERSE_SUBTRACT.
*/
void SetBlendEquation( BlendingEquation::Type equationRgb, BlendingEquation::Type equationAlpha );
* @brief Query the equation used when the actor is blended.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[out] equationRgb The equation used for combining red, green, and blue components.
* @param[out] equationAlpha The equation used for combining the alpha component.
*/
* @brief Specify the color used when the actor is blended; the default is Vector4::ZERO.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[in] color The blend color.
*/
void SetBlendColor( const Vector4& color );
* @brief Query the color used when the actor is blended.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @return The blend color.
*/
const Vector4& GetBlendColor() const;
* </ul>
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[in] minFilter The minification filtering mode.
* @param[in] magFilter The magnification filtering mode.
*/
* @brief Retrieves the filtering mode.
*
* @since_tizen 2.4
+ * @remarks This is an experimental feature and might not be supported in the next release.
+ * We do recommend not to use it.
* @param[out] minFilter The return minification value
* @param[out] magFilter The return magnification value
*/
void GetFilterMode( FilterMode::Type& minFilter, FilterMode::Type& magFilter) const;
/**
- * @brief Sets the shader effect for the RenderableActor.
+ * @brief Sets the shader effect for the ImageActor.
*
* Shader effects provide special effects like ripple and bend.
- * Setting a shader effect removes any shader effect previously set by SetShaderEffect.
+ * Setting a shader effect removes any shader effect previously set by @ref ImageActor::SetShaderEffect.
* @since_tizen 2.4
* @param [in] effect The shader effect.
* @pre The actor has been initialized.
- * @pre effect has been initialized.
+ * @pre Effect has been initialized.
*/
void SetShaderEffect( ShaderEffect effect );
/**
- * @brief Retrieve the custom shader effect for the RenderableActor.
+ * @brief Retrieve the custom shader effect for the ImageActor.
+ *
* If default shader is used an empty handle is returned.
*
* @since_tizen 2.4
* @brief Sets the shader effect for all ImageActors in a tree of Actors.
*
* @since_tizen 2.4
- * @param [in] actor root of a tree of actors.
+ * @param [in] actor Root of a tree of actors.
* @param [in] effect The shader effect.
* @see ImageActor::SetShaderEffect
*
*/
-DALI_IMPORT_API void SetShaderEffectRecursively( Actor actor, ShaderEffect effect );
+DALI_IMPORT_API void SetShaderEffectRecursively( Dali::Actor actor, Dali::ShaderEffect effect );
/**
* @brief Removes the shader effect from all ImageActors in a tree of Actors.
*
* @since_tizen 2.4
- * @param [in] actor root of a tree of actors.
+ * @param [in] actor Root of a tree of actors.
* @see ImageActor::RemoveShaderEffect
*
*/
-DALI_IMPORT_API void RemoveShaderEffectRecursively( Actor actor );
+DALI_IMPORT_API void RemoveShaderEffectRecursively( Dali::Actor actor );
/**
* @}
projects / framework / graphics / dali.git / blobdiff