dali/devel-api/scripting/scripting.h

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