1 #ifndef DALI_SCRIPTING_H
2 #define DALI_SCRIPTING_H
5 * Copyright (c) 2016 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/actors/actor-enumerations.h>
23 #include <dali/public-api/actors/draw-mode.h>
24 #include <dali/devel-api/animation/animation-data.h>
25 #include <dali/public-api/images/image.h>
26 #include <dali/public-api/shader-effects/shader-effect.h>
27 #include <dali/public-api/object/property-map.h>
28 #include <dali/public-api/object/property-value.h>
36 * @brief Utilities for scripting support.
42 * @brief Structure which stores an enumeration and its string equivalent.
46 const char* string; ///< The string representation
47 const int value; ///< The enumeration value wrapped in int
51 * @brief Find the given enum index from the table
53 * @param[in] value The string equivalent (case-insensitive).
54 * @param[in] table A pointer to an array with the enumeration to string equivalents.
55 * @param[in] tableCount Number of items in the array.
56 * @return The index of the enumeration. If enumeration is not found, logs an error and returns tableCount.
58 DALI_IMPORT_API unsigned int FindEnumIndex( const char* value, const StringEnum* table, unsigned int tableCount );
61 * @brief Find the enum as an integer from the table
65 * @param[in] value The string equivalent (case-insensitive, comma separate to OR values).
66 * @param[in] table A pointer to an array with the enumeration to string equivalents.
67 * @param[in] tableCount Number of items in the array.
68 * @param[out] integerEnum The value of the enum.
69 * @return true if one or more enums in value.
71 DALI_IMPORT_API bool EnumStringToInteger( const char* const value, const StringEnum* const table, unsigned int tableCount, int& integerEnum );
74 * @brief Chooses the appropriate enumeration for the provided string from the given table.
76 * @param[in] value The string equivalent (case-insensitive, comma separate to OR values).
77 * @param[in] table A pointer to an array with the enumeration to string equivalents.
78 * @param[in] tableCount Number of items in the array.
79 * @param[out] result The enum value
81 * @return True if the value was found from the table
83 template< typename T >
84 bool GetEnumeration( const char* value, const StringEnum* table, unsigned int tableCount, T& result )
90 // check to avoid crash, not asserting on purpose, error is logged instead
91 if( EnumStringToInteger( value, table, tableCount, integerEnum ) )
93 result = static_cast<T>( integerEnum );
101 * @brief Gets the enumeration value from an enumeration property.
102 * An enumeration property is a property that can be set with either an INTEGER or STRING.
104 * @param[in] PropertyValue The property containing the int or string value.
105 * @param[in] table A pointer to an array with the enumeration to string equivalents.
106 * @param[in] tableCount Number of items in the array.
107 * @param[out] result The enum value. This is not modified if the enumeration could not be converted.
108 * @return True if the value was found successfully AND the value has changed. This is to allow the caller to do nothing if there is no change.
110 template< typename T >
111 bool GetEnumerationProperty( const Property::Value& PropertyValue, const StringEnum* table, unsigned int tableCount, T& result )
115 Property::Type type = PropertyValue.GetType();
117 if( type == Property::INTEGER )
119 // Attempt to fetch the property as an INTEGER type.
120 if( PropertyValue.Get( newValue ) )
126 else if( type == Property::STRING )
128 // Attempt to fetch the property as an STRING type, and convert it from string to enumeration value.
129 std::string propertyString;
130 if( table && PropertyValue.Get( propertyString ) && EnumStringToInteger( propertyString.c_str(), table, tableCount, newValue ) )
137 // If the property was converted OK, AND the value has changed, update the result and return true.
138 if( set && ( result != static_cast<T>( newValue ) ) )
140 result = static_cast<T>( newValue );
149 * @brief Chooses the appropriate string for the provided enumeration from the given table.
151 * @param[in] value The enumeration.
152 * @param[in] table A pointer to an array with the enumeration to string equivalents.
153 * @param[in] tableCount Number of items in the array.
155 * @return The equivalent enumeration for the given string. Will return NULL if the value does not exist
157 * @note The caller is NOT responsible for cleaning up the returned pointer as it is statically allocated.
159 template< typename T >
160 const char* GetEnumerationName( T value, const StringEnum* table, unsigned int tableCount )
164 for ( unsigned int i = 0; i < tableCount; ++i )
166 if ( value == T(table[ i ].value) )
168 return table[ i ].string;
176 * @brief Chooses the appropriate string for the provided enumeration from the given table.
177 * This is an optimised version that handles enumerations that start at 0 and are linear only.
179 * @param[in] value The enumeration.
180 * @param[in] table A pointer to an array with the enumeration to string equivalents.
181 * @param[in] tableCount Number of items in the array.
183 * @return The equivalent enumeration for the given string. Will return NULL if the value does not exist
185 * @note The caller is NOT responsible for cleaning up the returned pointer as it is statically allocated.
187 template< typename T >
188 const char * GetLinearEnumerationName( T value, const StringEnum* table, unsigned int tableCount )
190 if ( table && ( value > 0 || value <= (int)tableCount ) )
192 return table[value].string;
198 * @brief Creates object with data from the property value map.
200 * @param[in] property The property value map with the following valid fields:
202 * "filename": type std::string
203 * "loadPolicy" type std::string (enum)
204 * "releasePolicy" type std::string (enum)
206 * "height" type float
207 * "pixelFormat" type std::string (enum)
208 * "fittingMode" type std::string (enum)
209 * "samplingMode" type std::string (enum)
210 * "orientation" type bool
211 * "type" type std::string (FrameBufferImage|BufferImage|ResourceImage(default))
213 * Some fields are optional and some only pertain to a specific type.
215 * @return A pointer to a newly created object.
217 DALI_IMPORT_API Image NewImage( const Property::Value& property );
220 * @brief Creates an actor with the date from the property value map.
222 * @param[in] map The property value map with the properties (and hierarchy) of the actor required
226 * "type": "ImageActor",
229 * "filename":"my-image-path.png"
241 * @return A handle to the newly created actor.
243 DALI_IMPORT_API Actor NewActor( const Property::Map& map );
246 * @brief Creates a Property::Map from the actor provided.
248 * @param[in] actor The base-actor from which a Property::Map should be created
249 * @param[out] map This map is cleared and a property map of actor and its children is filled in
251 DALI_IMPORT_API void CreatePropertyMap( Actor actor, Property::Map& map );
254 * @brief Creates a Property::Map from the image provided.
256 * @param[in] image The image from which a Property::Map should be created
257 * @param[out] map This map is cleared and a property map of the image is filled in
259 DALI_IMPORT_API void CreatePropertyMap( Image image, Property::Map& map );
262 * @brief Creates description data required to create an Animation object from a property map.
264 * @param[in] map The property value map containing the animation description
265 * @param[out] outputAnimationData Resultant data retrieved from the property map is written here
267 DALI_IMPORT_API void NewAnimation( const Property::Map& map, Dali::AnimationData& outputAnimationData );
269 } // namespace Scripting
273 #endif // DALI_SCRIPTING_H