dali/devel-api/scripting/scripting.h

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