dali/devel-api/scripting/scripting.h

   1 #ifndef DALI_SCRIPTING_H
   2 #define DALI_SCRIPTING_H
   3
   4 /*
   5  * Copyright (c) 2016 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/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/devel-api/shader-effects/shader-effect.h>
  27 #include <dali/public-api/object/property-array.h>
  28 #include <dali/public-api/object/property-map.h>
  29 #include <dali/public-api/object/property-value.h>
  30
  31 namespace Dali
  32 {
  33
  34 class Actor;
  35
  36 /**
  37  * @brief Utilities for scripting support.
  38  */
  39 namespace Scripting
  40 {
  41
  42 /**
  43  * @brief Structure which stores an enumeration and its string equivalent.
  44  */
  45 struct StringEnum
  46 {
  47   const char* string; ///< The string representation
  48   const int value;    ///< The enumeration value wrapped in int
  49 };
  50
  51 /**
  52  * @brief Find the given enum index from the table
  53  *
  54  * @param[in]  value       The string equivalent (case-insensitive).
  55  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
  56  * @param[in]  tableCount  Number of items in the array.
  57  * @return     The index of the enumeration. If enumeration is not found, logs an error and returns tableCount.
  58  */
  59 DALI_IMPORT_API unsigned int FindEnumIndex( const char* value, const StringEnum* table, unsigned int tableCount );
  60
  61 /**
  62  * @brief Find the enum as an integer from the table
  63  *
  64  * @SINCE_1_1.12
  65  *
  66  * @param[in]  value       The string equivalent (case-insensitive, comma separate to OR values).
  67  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
  68  * @param[in]  tableCount  Number of items in the array.
  69  * @param[out] integerEnum The value of the enum.
  70  * @return     true if one or more enums in value.
  71  */
  72 DALI_IMPORT_API bool EnumStringToInteger( const char* const value, const StringEnum* const table, unsigned int tableCount, int& integerEnum );
  73
  74 /**
  75  * @brief Chooses the appropriate enumeration for the provided string from the given table.
  76  *
  77  * @param[in]  value       The string equivalent (case-insensitive, comma separate to OR values).
  78  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
  79  * @param[in]  tableCount  Number of items in the array.
  80  * @param[out] result      The enum value
  81  *
  82  * @return     True if the value was found from the table
  83  */
  84 template< typename T >
  85 bool GetEnumeration( const char* value, const StringEnum* table, unsigned int tableCount, T& result )
  86 {
  87   bool retVal( false );
  88   if( table )
  89   {
  90     int integerEnum = 0;
  91     // check to avoid crash, not asserting on purpose, error is logged instead
  92     if( EnumStringToInteger( value, table, tableCount, integerEnum ) )
  93     {
  94       result = static_cast<T>( integerEnum );
  95       retVal = true;
  96     }
  97   }
  98   return retVal;
  99 }
 100
 101 /**
 102  * @brief Gets the enumeration value from an enumeration property.
 103  * An enumeration property is a property that can be set with either an INTEGER or STRING.
 104  *
 105  * @param[in]  propertyValue The property containing the int or string value.
 106  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
 107  * @param[in]  tableCount  Number of items in the array.
 108  * @param[out] result      The enum value. This is not modified if the enumeration could not be converted.
 109  * @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  */
 111 template< typename T >
 112 bool GetEnumerationProperty( const Property::Value& propertyValue, const StringEnum* table, unsigned int tableCount, T& result )
 113 {
 114   int newValue;
 115   bool set = false;
 116   Property::Type type = propertyValue.GetType();
 117
 118   if( type == Property::INTEGER )
 119   {
 120     // Attempt to fetch the property as an INTEGER type.
 121     if( propertyValue.Get( newValue ) )
 122     {
 123       // Success.
 124       set = true;
 125     }
 126   }
 127   else if( type == Property::STRING )
 128   {
 129     // Attempt to fetch the property as an STRING type, and convert it from string to enumeration value.
 130     std::string propertyString;
 131     if( table && propertyValue.Get( propertyString ) && EnumStringToInteger( propertyString.c_str(), table, tableCount, newValue ) )
 132     {
 133       // Success.
 134       set = true;
 135     }
 136   }
 137
 138   // If the property was converted OK, AND the value has changed, update the result and return true.
 139   if( set && ( result != static_cast<T>( newValue ) ) )
 140   {
 141     result = static_cast<T>( newValue );
 142     return true;
 143   }
 144
 145   // No change.
 146   return false;
 147 }
 148
 149 /**
 150  * @brief Gets the enumeration value from a bitmask enumeration property.
 151  * An enumeration property is a property that can be set with either an INTEGER, STRING or an ARRAY of STRING.
 152  *
 153  * @param[in]  propertyValue The property containing the int, string or and array of string values.
 154  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
 155  * @param[in]  tableCount  Number of items in the array.
 156  * @param[out] result      The enum value. This is not modified if the enumeration could not be converted.
 157  * @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.
 158  */
 159 template< typename T >
 160 bool GetBitmaskEnumerationProperty( const Property::Value& propertyValue, const Scripting::StringEnum* table, unsigned int tableCount, T& result )
 161 {
 162   bool returnValue = true;
 163
 164   // Evaluate as a single INTEGER or STRING first.
 165   if( !GetEnumerationProperty( propertyValue, table, tableCount, result ) )
 166   {
 167     // If not, then check if it's an ARRAY
 168     if ( propertyValue.GetType() == Property::ARRAY )
 169     {
 170       int newValue = 0;
 171       Property::Array array;
 172       propertyValue.Get( array );
 173       for( Property::Array::SizeType i = 0; i < array.Count(); ++i )
 174       {
 175         Property::Value currentValue = array[ i ];
 176         // Use an initial value of -1 so any successful property conversion
 177         // causes a change (and true to be returned).
 178         T current = static_cast< T >( -1 );
 179         if( GetEnumerationProperty( currentValue, table, tableCount, current ) )
 180         {
 181           newValue |= current;
 182         }
 183         else
 184         {
 185           // We hit an invalid type.
 186           returnValue = false;
 187           break;
 188         }
 189       }
 190
 191       // If we didn't hit an invalid type and the value has changed, update the result.
 192       if( returnValue && ( result != static_cast<T>( newValue ) ) )
 193       {
 194         result = static_cast<T>( newValue );
 195       }
 196     }
 197     else
 198     {
 199       // Property type was not ARRAY, and the single property evaluation also failed.
 200       returnValue = false;
 201     }
 202   }
 203
 204   return returnValue;
 205 }
 206
 207 /**
 208  * @brief Chooses the appropriate string for the provided enumeration from the given table.
 209  *
 210  * @param[in]  value       The enumeration.
 211  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
 212  * @param[in]  tableCount  Number of items in the array.
 213  *
 214  * @return     The equivalent enumeration for the given string. Will return NULL if the value does not exist
 215  *
 216  * @note The caller is NOT responsible for cleaning up the returned pointer as it is statically allocated.
 217  */
 218 template< typename T >
 219 const char* GetEnumerationName( T value, const StringEnum* table, unsigned int tableCount )
 220 {
 221   if( table )
 222   {
 223     for ( unsigned int i = 0; i < tableCount; ++i )
 224     {
 225       if ( value == T(table[ i ].value) )
 226       {
 227         return table[ i ].string;
 228       }
 229     }
 230   }
 231   return NULL;
 232 }
 233
 234 /**
 235  * @brief Chooses the appropriate string for the provided enumeration from the given table.
 236  * This is an optimised version that handles enumerations that start at 0 and are linear only.
 237  *
 238  * @param[in]  value       The enumeration.
 239  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
 240  * @param[in]  tableCount  Number of items in the array.
 241  *
 242  * @return     The equivalent enumeration for the given string. Will return NULL if the value does not exist
 243  *
 244  * @note The caller is NOT responsible for cleaning up the returned pointer as it is statically allocated.
 245  */
 246 template< typename T >
 247 const char * GetLinearEnumerationName( T value, const StringEnum* table, unsigned int tableCount )
 248 {
 249   if ( table && ( value > 0 || value <= (int)tableCount ) )
 250   {
 251     return table[value].string;
 252   }
 253   return NULL;
 254 }
 255
 256 /**
 257  * @brief Creates object with data from the property value map.
 258  *
 259  * @param[in] property The property value map with the following valid fields:
 260  * @code
 261  * "filename":      type std::string
 262  * "loadPolicy"     type std::string (enum)
 263  * "releasePolicy"  type std::string (enum)
 264  * "width"          type float
 265  * "height"         type float
 266  * "pixelFormat"    type std::string (enum)
 267  * "fittingMode"    type std::string (enum)
 268  * "samplingMode"   type std::string (enum)
 269  * "orientation"    type bool
 270  * "type"           type std::string (FrameBufferImage|BufferImage|ResourceImage(default))
 271  * @endcode
 272  * Some fields are optional and some only pertain to a specific type.
 273  *
 274  * @return A pointer to a newly created object.
 275  */
 276 DALI_IMPORT_API Image NewImage( const Property::Value& property );
 277
 278 /**
 279  * @brief Creates an actor with the date from the property value map.
 280  *
 281  * @param[in] map The property value map with the properties (and hierarchy) of the actor required
 282  *                 For example:
 283  * @code
 284  * {
 285  *   "type": "ImageActor",
 286  *   "image":
 287  *   {
 288  *     "filename":"my-image-path.png"
 289  *   },
 290  *   "actors":
 291  *   [
 292  *     {
 293  *       "type":"Actor",
 294  *       "position":[0,0,0]
 295  *     }
 296  *   ]
 297  * }
 298  * @endcode
 299  *
 300  * @return A handle to the newly created actor.
 301  */
 302 DALI_IMPORT_API Actor NewActor( const Property::Map& map );
 303
 304 /**
 305  * @brief Creates a Property::Map from the actor provided.
 306  *
 307  * @param[in]  actor The base-actor from which a Property::Map should be created
 308  * @param[out] map This map is cleared and a property map of actor and its children is filled in
 309  */
 310 DALI_IMPORT_API void CreatePropertyMap( Actor actor, Property::Map& map );
 311
 312 /**
 313  * @brief Creates a Property::Map from the image provided.
 314  *
 315  * @param[in]  image The image from which a Property::Map should be created
 316  * @param[out] map This map is cleared and a property map of the image is filled in
 317  */
 318 DALI_IMPORT_API void CreatePropertyMap( Image image, Property::Map& map );
 319
 320 /**
 321  * @brief Creates description data required to create an Animation object from a property map.
 322  *
 323  * @param[in]  map The property value map containing the animation description
 324  * @param[out] outputAnimationData Resultant data retrieved from the property map is written here
 325  */
 326 DALI_IMPORT_API void NewAnimation( const Property::Map& map, Dali::AnimationData& outputAnimationData );
 327
 328 } // namespace Scripting
 329
 330 } // namespace Dali
 331
 332 #endif // DALI_SCRIPTING_H