dali/devel-api/object/handle-devel.h

   1 #ifndef DALI_HANDLE_DEVEL_H
   2 #define DALI_HANDLE_DEVEL_H
   3
   4 /*
   5  * Copyright (c) 2017 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/object/handle.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace DevelHandle
  28 {
  29
  30 /**
  31  * @brief Query the index of a custom property matching the given key.
  32  *
  33  * Returns the first custom property that matches the given integer key. This is
  34  * useful for other classes that know the key but not the name. Requires the property
  35  * to have been registered with the associated key.
  36  *
  37  * @note This key is not the same as the Property enum found in
  38  * objects such as Actor (which is a preset index).
  39  *
  40  * @param[in] handle The handle from where to retrieve the property index.
  41  * @param[in] key The integer key of the property
  42  *
  43  * @return The index of the property, or Property::INVALID_INDEX if no property exists with the given key.
  44  *
  45  * @note The key is not the same as the returned index, though it has the same type.
  46  */
  47 DALI_IMPORT_API Property::Index GetPropertyIndex( const Handle& handle, Property::Index key );
  48
  49 /**
  50  * @brief Query the index of a property using the given key from a Property::Map
  51  *
  52  * @param[in] handle The handle from where to retrieve the property index.
  53  * @param[in] key The key of the property to search for.
  54  *
  55  * @return the matching property index of either the string key or the matching
  56  * custom property index of the index key, or Property::INVALID_INDEX if no
  57  * property matches the given key.
  58  *
  59  * @note See also, GetPropertyIndex(Property::Index) and GetPropertyIndex(const std::string&)
  60  */
  61 DALI_IMPORT_API Property::Index GetPropertyIndex( const Handle& handle, Property::Key key );
  62
  63 /**
  64  * @brief Register a new animatable property with an integer key.
  65  *
  66  * @param[in] handle The handle where to register the property.
  67  * @param[in] key  The integer key of the property.
  68  * @param[in] name The text key of the property.
  69  * @param[in] propertyValue The new value of the property.
  70  *
  71  * @return The index of the property or Property::INVALID_INDEX if registration failed
  72  *
  73  * @pre The object supports dynamic properties i.e. Supports(Handle::DYNAMIC_PROPERTIES) returns true.
  74  * Property names and keys are expected to be unique, but this is not enforced.
  75  * Property indices are unique to each registered custom property in a given object.
  76  *
  77  * @note Returns Property::INVALID_INDEX if registration failed. This can happen if you try to register
  78  * animatable property on an object that does not have scene graph object.
  79  *
  80  * @note The returned property index is not the same as the integer key (though it shares a type)
  81  *
  82  * This version of RegisterProperty associates both an integer key
  83  * and the text key with the property, allowing for lookup of the
  84  * property index by either key or name ( which is useful when other
  85  * classes know the key but not the name )
  86  *
  87  * @note Only the following types can be animated:
  88  *       - Property::BOOLEAN
  89  *       - Property::FLOAT
  90  *       - Property::INTEGER
  91  *       - Property::VECTOR2
  92  *       - Property::VECTOR3
  93  *       - Property::VECTOR4
  94  *       - Property::MATRIX3
  95  *       - Property::MATRIX
  96  *       - Property::ROTATION
  97  * @note If a property with the desired name already exists, then the value given is just set.
  98  */
  99 DALI_IMPORT_API Property::Index RegisterProperty( Handle handle, Property::Index key, const std::string& name, const Property::Value& propertyValue );
 100
 101 /**
 102  * @brief Set the type-info that the object is created by.
 103  *
 104  * @note This is particularly useful to link C# custom control with its correct type-info in the native side
 105  *
 106  * @param[in] handle The handle created by this TypeInfo.
 107  * @param[in] typeInfo The TypeInfo that creates the handle.
 108  */
 109 DALI_IMPORT_API void SetTypeInfo( Handle& handle, const TypeInfo& typeInfo );
 110
 111 /**
 112  * @brief Retrieves the latest value of the property from the scene-graph.
 113  *
 114  * @param[in] handle The handle whose current property value is required
 115  * @param[in] index The index of the property
 116  * @return The property value
 117  */
 118 DALI_IMPORT_API Property::Value GetCurrentProperty( Handle handle, Property::Index index );
 119
 120 /**
 121  * @brief Convenience function for obtaining the current value of a property of a known type.
 122  *
 123  * @param[in] handle The handle whose current property value is required
 124  * @param[in] index The index of the property
 125  * @return The property value
 126  * @pre The property types match i.e. PropertyTypes::Get<T>() is equal to GetPropertyType(index).
 127  */
 128 template <typename T>
 129 T GetCurrentProperty( Handle handle, Property::Index index )
 130 {
 131   Property::Value value = GetCurrentProperty( handle, index );
 132
 133   return T( value.Get<T>() );
 134 }
 135
 136 } // namespace DevelHandle
 137
 138 } // namespace Dali
 139
 140 #endif // DALI_HANDLE_DEVEL_H