X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fobject%2Fproperty-value.h;h=fa66e05bd8cfe9493d3599f5e8dbaf14eeeec9c5;hb=649ec06daecb510fb84fe4642a6af957f127e7ab;hp=f096d7b14f914422a184fadd8865d42532175cd4;hpb=e3f5c847860180b52536947454c8e53c5bd3e1d5;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/object/property-value.h b/dali/public-api/object/property-value.h index f096d7b..fa66e05 100644 --- a/dali/public-api/object/property-value.h +++ b/dali/public-api/object/property-value.h @@ -2,7 +2,7 @@ #define __DALI_PROPERTY_VALUE_H__ /* - * Copyright (c) 2015 Samsung Electronics Co., Ltd. + * Copyright (c) 2018 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. @@ -27,6 +27,10 @@ namespace Dali { +/** + * @addtogroup dali_core_object + * @{ + */ struct AngleAxis; class Quaternion; @@ -35,11 +39,13 @@ struct Vector3; struct Vector4; class Matrix3; class Matrix; +struct Extents; /** * @brief A value-type representing a property value. + * @SINCE_1_0.0 */ -class DALI_IMPORT_API Property::Value +class DALI_CORE_API Property::Value { public: @@ -47,325 +53,364 @@ public: * @brief Default constructor. * * This creates a property with type Property::NONE. + * @SINCE_1_0.0 */ Value(); /** - * @brief Create a boolean property value. + * @brief Creates a boolean property value. * - * @param [in] boolValue A boolean value. + * @SINCE_1_0.0 + * @param[in] boolValue A boolean value */ Value( bool boolValue ); /** - * @brief Create an integer property value. + * @brief Creates an integer property value. * - * @param [in] integerValue An integer value. + * @SINCE_1_0.0 + * @param[in] integerValue An integer value */ Value( int integerValue ); /** - * @brief Create an unsigned integer property value. + * @brief Creates a float property value. * - * @param [in] unsignedIntegerValue An unsigned integer value. - */ - Value( unsigned int unsignedIntegerValue ); - - /** - * @brief Create a float property value. - * - * @param [in] floatValue A floating-point value. + * @SINCE_1_0.0 + * @param[in] floatValue A floating-point value */ Value( float floatValue ); /** - * @brief Create a Vector2 property value. + * @brief Creates a Vector2 property value. * - * @param [in] vectorValue A vector of 2 floating-point values. + * @SINCE_1_0.0 + * @param[in] vectorValue A vector of 2 floating-point values */ Value( const Vector2& vectorValue ); /** - * @brief Create a Vector3 property value. + * @brief Creates a Vector3 property value. * - * @param [in] vectorValue A vector of 3 floating-point values. + * @SINCE_1_0.0 + * @param[in] vectorValue A vector of 3 floating-point values */ Value( const Vector3& vectorValue ); /** - * @brief Create a Vector4 property value. + * @brief Creates a Vector4 property value. * - * @param [in] vectorValue A vector of 4 floating-point values. + * @SINCE_1_0.0 + * @param[in] vectorValue A vector of 4 floating-point values */ Value( const Vector4& vectorValue ); /** - * @brief Create a Matrix3 property value. + * @brief Creates a Matrix3 property value. * - * @param [in] matrixValue A matrix of 3x3 floating-point values. + * @SINCE_1_0.0 + * @param[in] matrixValue A matrix of 3x3 floating-point values */ Value( const Matrix3& matrixValue ); /** - * @brief Create a Matrix property value. + * @brief Creates a Matrix property value. * - * @param [in] matrixValue A matrix of 4x4 floating-point values. + * @SINCE_1_0.0 + * @param[in] matrixValue A matrix of 4x4 floating-point values */ Value( const Matrix& matrixValue ); /** - * @brief Create a Vector4 property value. + * @brief Creates a Vector4 property value. * - * @param [in] vectorValue A vector of 4 integer values. + * @SINCE_1_0.0 + * @param[in] vectorValue A vector of 4 integer values */ Value( const Rect& vectorValue ); /** - * @brief Create an orientation property value. + * @brief Creates an orientation property value. * - * @param [in] angleAxis An angle-axis representing the rotation. + * @SINCE_1_0.0 + * @param[in] angleAxis An angle-axis representing the rotation */ Value( const AngleAxis& angleAxis ); /** - * @brief Create an orientation property value. + * @brief Creates an orientation property value. * - * @param [in] quaternion A quaternion representing the rotation. + * @SINCE_1_0.0 + * @param[in] quaternion A quaternion representing the rotation */ Value( const Quaternion& quaternion ); /** - * @brief Create an string property value. + * @brief Creates an string property value. * - * @param [in] stringValue A string. + * @SINCE_1_0.0 + * @param[in] stringValue A string */ Value( const std::string& stringValue ); /** - * @brief Create an string property value. + * @brief Creates a string property value. * - * @param [in] stringValue A string. + * @SINCE_1_0.0 + * @param[in] stringValue A string */ Value( const char* stringValue ); /** - * @brief Copy a property value. + * @brief Creates an array property value. * - * @param [in] value The property value to copy. + * @SINCE_1_0.0 + * @param[in] arrayValue An array */ - Value( const Value& value ); + Value( Property::Array& arrayValue ); /** - * @brief Create an array property value. + * @brief Creates a map property value. * - * @param [in] arrayValue An array + * @SINCE_1_0.0 + * @param[in] mapValue An array */ - Value( Property::Array& arrayValue ); + Value( Property::Map& mapValue ); /** - * @brief Create a map property value. + * @brief Creates an extents property value. * - * @param [in] mapValue An array + * @SINCE_1_2.62 + * @param[in] extentsValue A collection of 4 uint16_t values */ - Value( Property::Map& mapValue ); + Value( const Extents& extentsValue ); /** - * @brief Explicitly set a type and initialize it. + * @brief Explicitly sets a type and initialize it. * - * @param [in] type The property value type. + * @SINCE_1_0.0 + * @param[in] type The property value type */ explicit Value( Type type ); /** - * @brief Assign a property value. + * @brief Copy constructor. + * + * @SINCE_1_0.0 + * @param[in] value The property value to copy + */ + Value( const Value& value ); + + /** + * @brief Assigns a property value. * - * @param [in] value The property value to assign from. + * @SINCE_1_0.0 + * @param[in] value The property value to assign from * @return a reference to this */ Value& operator=( const Value& value ); /** * @brief Non-virtual destructor. + * + * This class is not a base class. + * @SINCE_1_0.0 */ ~Value(); /** - * @brief Query the type of this property value. + * @brief Queries the type of this property value. * - * @return The type ID. + * @SINCE_1_0.0 + * @return The type ID */ Type GetType() const; /** - * @brief Retrieve a specific value. + * @brief Retrieves a specific value. * - * @pre GetType() returns the Property::Type for type T. - * @return A value of type T. + * Works on a best-effort approach; if value type is not convertible returns a default value of the type. + * + * @SINCE_1_0.0 + * @return A value of type T */ template T DALI_INTERNAL Get() const { - T temp; - Get(temp); + T temp = T(); // value (zero) initialize + Get( temp ); return temp; } /** - * @brief Retrieve a boolean value. - * - * @pre GetType() returns Property::BOOLEAN. - * @param [out] boolValue On return, a boolean value. - */ - void Get( bool& boolValue ) const; - - /** - * @brief Retrieve a floating-point value. + * @brief Retrieves a boolean value. * - * @pre GetType() returns Property::FLOAT. - * @param [out] floatValue On return, a floating-point value. + * @SINCE_1_0.0 + * @param[out] boolValue On return, a boolean value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to bool. */ - void Get( float& floatValue ) const; + bool Get( bool& boolValue ) const; /** - * @brief Retrieve an integer value. + * @brief Retrieves a floating-point value. * - * @pre GetType() returns Property::INTEGER. - * @param [out] integerValue On return, an integer value. + * @SINCE_1_0.0 + * @param[out] floatValue On return, a floating-point value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to float. */ - void Get( int& integerValue ) const; + bool Get( float& floatValue ) const; /** - * @brief Retrieve an unsigned integer value. + * @brief Retrieves an integer value. * - * @pre GetType() returns Property::UNSIGNED_INTEGER. - * @param [out] unsignedIntegerValue On return, an unsigned integer value. + * @SINCE_1_0.0 + * @param[out] integerValue On return, an integer value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to int. */ - void Get( unsigned int& unsignedIntegerValue ) const; + bool Get( int& integerValue ) const; /** - * @brief Retrieve an integer rectangle. + * @brief Retrieves an integer rectangle. * - * @pre GetType() returns Property::RECTANGLE. - * @param [out] rect On return, an integer rectangle. + * @SINCE_1_0.0 + * @param[out] rect On return, an integer rectangle + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to Rect. */ - void Get( Rect& rect ) const; + bool Get( Rect& rect ) const; /** - * @brief Retrieve a vector value. + * @brief Retrieves a vector value. * - * @pre GetType() returns Property::VECTOR2. - * @param [out] vectorValue On return, a vector value. + * @SINCE_1_0.0 + * @param[out] vectorValue On return, a vector value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to Vector2. */ - void Get( Vector2& vectorValue ) const; + bool Get( Vector2& vectorValue ) const; /** - * @brief Retrieve a vector value. + * @brief Retrieves a vector value. * - * @pre GetType() returns Property::VECTOR3. - * @param [out] vectorValue On return, a vector value. + * @SINCE_1_0.0 + * @param[out] vectorValue On return, a vector value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to Vector3. */ - void Get( Vector3& vectorValue ) const; + bool Get( Vector3& vectorValue ) const; /** - * @brief Retrieve a vector value. + * @brief Retrieves a vector value. * - * @pre GetType() returns Property::VECTOR4. - * @param [out] vectorValue On return, a vector value. + * @SINCE_1_0.0 + * @param[out] vectorValue On return, a vector value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to Vector4. */ - void Get( Vector4& vectorValue ) const; + bool Get( Vector4& vectorValue ) const; /** - * @brief Retrieve a matrix3 value. + * @brief Retrieves a matrix3 value. * - * @pre GetType() returns Property::MATRIX3. - * @param [out] matrixValue On return, a matrix3 value. + * @SINCE_1_0.0 + * @param[out] matrixValue On return, a matrix3 value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to Matrix3. */ - void Get( Matrix3& matrixValue ) const; + bool Get( Matrix3& matrixValue ) const; /** - * @brief Retrieve a matrix value. + * @brief Retrieves a matrix value. * - * @pre GetType() returns Property::MATRIX. - * @param [out] matrixValue On return, a matrix value. + * @SINCE_1_0.0 + * @param[out] matrixValue On return, a matrix value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to Matrix. */ - void Get( Matrix& matrixValue ) const; + bool Get( Matrix& matrixValue ) const; /** - * @brief Retrieve an angle-axis value. + * @brief Retrieves an angle-axis value. * - * @pre GetType() returns Property::ROTATION. - * @param [out] angleAxisValue On return, a angle-axis value. + * @SINCE_1_0.0 + * @param[out] angleAxisValue On return, a angle-axis value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to AngleAxis. */ - void Get( AngleAxis& angleAxisValue ) const; + bool Get( AngleAxis& angleAxisValue ) const; /** - * @brief Retrieve a quaternion value. + * @brief Retrieves a quaternion value. * - * @pre GetType() returns Property::ROTATION. - * @param [out] quaternionValue On return, a quaternion value. + * @SINCE_1_0.0 + * @param[out] quaternionValue On return, a quaternion value + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to Quaternion. */ - void Get( Quaternion& quaternionValue ) const; + bool Get( Quaternion& quaternionValue ) const; /** - * @brief Retrieve an string property value. + * @brief Retrieves an string property value. * - * @pre GetType() returns Property::STRING. - * @param [out] stringValue A string. + * @SINCE_1_0.0 + * @param[out] stringValue A string + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to string. */ - void Get( std::string& stringValue ) const; + bool Get( std::string& stringValue ) const; /** - * @brief Retrieve an array property value. + * @brief Retrieves an array property value. * + * @SINCE_1_0.0 + * @param[out] arrayValue The array as a vector Property Values + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible * @pre GetType() returns Property::ARRAY. - * @param [out] arrayValue The array as a vector Property Values */ - void Get( Property::Array& arrayValue ) const; + bool Get( Property::Array& arrayValue ) const; /** - * @brief Retrieve an map property value. + * @brief Retrieves an map property value. * + * @SINCE_1_0.0 + * @param[out] mapValue The map as vector of string and Property Value pairs + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible * @pre GetType() returns Property::MAP. - * @param [out] mapValue The map as vector of string and Property Value pairs */ - void Get( Property::Map& mapValue ) const; + bool Get( Property::Map& mapValue ) const; /** - * @brief return true if this property is a Property::MAP. + * @brief Retrieves the Array API of the Property::Value without copying the contents of the map. * - * @return return true if this property is a Property::MAP + * @SINCE_1_0.0 + * @return The Array API of the Property::Value or NULL if not a Property::Array */ - bool IsMap() const - { - return GetMap() != NULL; - } + Property::Array* GetArray() const; /** - * @brief Retrieve the Map API of the Property::Value without copying the contents of the map + * @brief Retrieves the Map API of the Property::Value without copying the contents of the map. * - * @return the Map API of the Property::Value or NULL if not a Property::Map + * @SINCE_1_0.0 + * @return The Map API of the Property::Value or NULL if not a Property::Map */ Property::Map* GetMap() const; /** - * @brief return true if this property is a Property::ARRAY. + * @brief Retrieves an extents. * - * @return return true if this property is a Property::ARRAY + * @SINCE_1_2.62 + * @param[out] extentsValue Extents, a collection of 4 uint16_t + * @return @c true if the value is successfully retrieved, @c false if the type is not convertible + * @pre GetType() is a type convertible to Extents. */ - bool IsArray() const - { - return GetArray() != NULL; - } - - /** - * @brief Retrieve the Array API of the Property::Value without copying the contents of the map - * - * @return the Array API of the Property::Value or NULL if not a Property::Array - */ - Property::Array* GetArray() const; + bool Get( Extents& extentsValue ) const; /** - * output to stream + * @brief Output to stream. + * @SINCE_1_0.0 */ friend std::ostream& operator<<( std::ostream& ouputStream, const Property::Value& value ); @@ -377,14 +422,18 @@ private: }; /** - * @brief Convert the value of the property into a string and append to an output stream. + * @brief Converts the value of the property into a string and append to an output stream. * - * @param [in] ouputStream The output stream operator. - * @param [in] value The value to insert - * @return The output stream operator. + * @SINCE_1_0.0 + * @param[in] ouputStream The output stream operator + * @param[in] value The value to insert + * @return The output stream operator */ -DALI_IMPORT_API std::ostream& operator<<( std::ostream& ouputStream, const Property::Value& value ); +DALI_CORE_API std::ostream& operator<<( std::ostream& ouputStream, const Property::Value& value ); +/** + * @} + */ } // namespace Dali #endif // __DALI_PROPERTY_VALUE_H__