dali/devel-api/scripting/scripting.h

   1 #ifndef __DALI_SCRIPTING_H__
   2 #define __DALI_SCRIPTING_H__
   3
   4 /*
   5  * Copyright (c) 2015 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/public-api/images/image.h>
  25 #include <dali/public-api/shader-effects/shader-effect.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
  32 class Actor;
  33
  34 /**
  35  * @brief Utilities for scripting support.
  36  */
  37 namespace Scripting
  38 {
  39
  40 /**
  41  * @brief Template structure which stores an enumeration and its string equivalent.
  42  */
  43 template< typename T >
  44 struct StringEnum
  45 {
  46   const char* string; ///< The string representation
  47   const T value;      ///< The actual enumeration
  48 };
  49
  50 /**
  51  * @brief Permissive comparison for string enums.
  52  *
  53  * Case insensitive and ignores '_', '-' in either string when comparing.
  54  *
  55  * @note If both strings are empty return true;
  56  *
  57  * @param[in] a The first string
  58  * @param[in] b The string to compare
  59  * @return true if the strings are equal as defined above. If both empty, then return true.
  60  */
  61 DALI_IMPORT_API bool CompareEnums( const char * a, const char * b );
  62
  63 /**
  64  * @brief Set the value if strings pass a permissive compare.
  65  *
  66  * @param[in] a The input string
  67  * @param[in] b The string to compare
  68  * @param[in] set The variable to set
  69  * @param[in] value The value to set
  70  * @return true if the strings pass the permissive compare
  71  */
  72 template <typename T>
  73 bool SetIfEqual(const char * a, const char * b, T& set, const T& value)
  74 {
  75   if( CompareEnums( a, b ) )
  76   {
  77     set = value;
  78     return true;
  79   }
  80
  81   return false;
  82 }
  83
  84 /**
  85  * @brief Chooses the appropriate enumeration for the provided string from the given table.
  86  *
  87  * @param[in]  value       The string equivalent (case-insensitive).
  88  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
  89  * @param[in]  tableCount  Number of items in the array.
  90  *
  91  * @return The equivalent enumeration for the given string.
  92  */
  93 template< typename T >
  94 T GetEnumeration( const char * value, const StringEnum< T >* table, unsigned int tableCount )
  95 {
  96   T retVal( table->value );
  97   bool set( false );
  98
  99   for ( unsigned int i = 0; ( i < tableCount ) && ( !set ); ++i )
 100   {
 101     set = SetIfEqual( value, table->string, retVal, table->value );
 102     ++table;
 103   }
 104
 105   if ( !set )
 106   {
 107     DALI_ASSERT_ALWAYS( !"Unknown enumeration string" );
 108   }
 109
 110   return retVal;
 111 }
 112
 113 /**
 114  * @brief Chooses the appropriate string for the provided enumeration from the given table.
 115  *
 116  * @param[in]  value       The enumeration.
 117  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
 118  * @param[in]  tableCount  Number of items in the array.
 119  *
 120  * @return The equivalent enumeration for the given string. Will return NULL if the value does not exist
 121  *
 122  * @note The caller is NOT responsible for cleaning up the returned pointer as it is statically allocated.
 123  */
 124 template< typename T >
 125 const char * GetEnumerationName( T value, const StringEnum< T >* table, unsigned int tableCount )
 126 {
 127   for ( unsigned int i = 0; i < tableCount; ++i )
 128   {
 129     if ( value == table[ i ].value )
 130     {
 131       return table[ i ].string;
 132     }
 133   }
 134
 135   return NULL;
 136 }
 137
 138 /**
 139  * @brief Chooses the appropriate string for the provided enumeration from the given table.
 140  * This is an optimised version that handles enumerations that start at 0 and are linear only.
 141  *
 142  * @param[in]  value       The enumeration.
 143  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
 144  * @param[in]  tableCount  Number of items in the array.
 145  *
 146  * @return The equivalent enumeration for the given string. Will return NULL if the value does not exist
 147  *
 148  * @note The caller is NOT responsible for cleaning up the returned pointer as it is statically allocated.
 149  */
 150 template< typename T >
 151 const char * GetLinearEnumerationName( T value, const StringEnum< T >* table, unsigned int tableCount )
 152 {
 153   if ( value < 0 || value >= (int)tableCount )
 154   {
 155     return NULL;
 156   }
 157
 158   return table[value].string;
 159 }
 160
 161 /**
 162  * @brief Takes a string and returns the appropriate color mode.
 163  *
 164  * @param[in] value The input string
 165  * @return The corresponding color-mode.
 166  */
 167 DALI_IMPORT_API ColorMode GetColorMode( const std::string& value );
 168
 169 /**
 170  * @brief Takes a color mode and returns the appropriate string equivalent.
 171  *
 172  * @param[in] value The color mode
 173  * @return The corresponding string.
 174  */
 175 DALI_IMPORT_API std::string GetColorMode( ColorMode value );
 176
 177 /**
 178  * @brief Takes a string and returns the appropriate position inheritance mode.
 179  *
 180  * @param[in] value The input string
 181  * @return The corresponding position-inheritance-mode.
 182  */
 183 DALI_IMPORT_API PositionInheritanceMode GetPositionInheritanceMode( const std::string& value );
 184
 185 /**
 186  * @brief Takes a position inheritance mode and returns the string equivalent.
 187  *
 188  * @param[in] value The position-inheritance-mode.
 189  * @return The corresponding string.
 190  */
 191 DALI_IMPORT_API std::string GetPositionInheritanceMode( PositionInheritanceMode value );
 192
 193 /**
 194  * @brief Takes a string and returns the appropriate draw mode.
 195  *
 196  * @param[in] value The input string
 197  * @return The corresponding draw-mode.
 198  */
 199 DALI_IMPORT_API DrawMode::Type GetDrawMode( const std::string& value );
 200
 201 /**
 202  * @brief Takes a draw-mode and returns the string equivalent.
 203  *
 204  * @param[in] value The draw-mode.
 205  * @return The corresponding string.
 206  */
 207 DALI_IMPORT_API std::string GetDrawMode( DrawMode::Type value );
 208
 209 /**
 210  * @brief Takes a string and returns the appropriate anchor-point or parent-origin constant.
 211  *
 212  * @param[in] value The input string
 213  * @return The corresponding anchor-point or parent-origin constant.
 214  */
 215 DALI_IMPORT_API Vector3 GetAnchorConstant( const std::string& value );
 216
 217 /**
 218  * @brief Creates object with data from the property value map.
 219  *
 220  * @param[in] map The property value map with the following valid fields:
 221  * @code
 222  * "filename":       type std::string
 223  * "load-policy"     type std::string (enum)
 224  * "release-policy"  type std::string (enum)
 225  * "width"           type float
 226  * "height"          type float
 227  * "pixel-format"    type std::string (enum)
 228  * "fitting-mode"    type std::string (enum)
 229  * "sampling-mode"   type std::string (enum)
 230  * "orientation"     type bool
 231  * "type"            type std::string (FrameBufferImage|BufferImage|ResourceImage(default))
 232  * @endcode
 233  * Some fields are optional and some only pertain to a specific type.
 234  *
 235  * @return a pointer to a newly created object.
 236  */
 237 DALI_IMPORT_API Image NewImage( const Property::Value& map );
 238
 239 /**
 240  * @brief Creates object with data from the property value map.
 241  *
 242  * @param[in] map The property value map with the following valid fields:
 243  * @code
 244  * // a program can be specified as string or a filename.
 245  * // some fields may be ignored depending on the geometry-type
 246  * "program":        type Map
 247  * {
 248  *   "vertex":                   type std::string
 249  *   "fragment":                 type std::string
 250  *   "vertex-prefix":            type std::string
 251  *   "fragment-prefix":          type std::string
 252  *   "text-vertex":              type std::string
 253  *   "text-fragment":            type std::string
 254  *   "vertex-filename":          type std::string
 255  *   "fragment-filename":        type std::string
 256  *   "vertex-prefix-filename":   type std::string
 257  *   "fragment-prefix-filename": type std::string
 258  *   "text-vertex-filename":     type std::string
 259  *   "text-fragment-filename":   type std::string
 260  *   "geometry-type":            type std::string (enum)
 261  *   "geometry-hints":           type std::string (enum)
 262  * }
 263  * // uniforms must be specified to be registered
 264  * "uUniform1":       type float,
 265  * "uUniform2":       type float, etc
 266  * @endcode
 267  *
 268  * @return a pointer to a newly created object.
 269  */
 270 DALI_IMPORT_API ShaderEffect NewShaderEffect( const Property::Value& map );
 271
 272 /**
 273  * @brief Creates an actor with the date from the property value map.
 274  *
 275  * @param[in] map The property value map with the properties (and hierarchy) of the actor required
 276  *                 For example:
 277  * @code
 278  * {
 279  *   "type": "ImageActor",
 280  *   "image":
 281  *   {
 282  *     "filename":"my-image-path.png"
 283  *   },
 284  *   "actors":
 285  *   [
 286  *     {
 287  *       "type":"Actor",
 288  *       "position":[0,0,0]
 289  *     }
 290  *   ]
 291  * }
 292  * @endcode
 293  *
 294  * @return Handle to the newly created actor.
 295  */
 296 DALI_IMPORT_API Actor NewActor( const Property::Map& map );
 297
 298 /**
 299  * @brief Creates a Property::Map from the actor provided.
 300  *
 301  * @param[in] actor The base-actor from which a Property::Map should be created
 302  * @param[out] map This map is cleared and a property map of actor and its children is filled in
 303  */
 304 DALI_IMPORT_API void CreatePropertyMap( Actor actor, Property::Map& map );
 305
 306 /**
 307  * @brief Creates a Property::Map from the image provided.
 308  *
 309  * @param[in] image The image from which a Property::Map should be created
 310  * @param[out] map This map is cleared and a property map of the image is filled in
 311  */
 312 DALI_IMPORT_API void CreatePropertyMap( Image image, Property::Map& map );
 313
 314 /**
 315  * @brief Sets a quaterion rotation from a script provided value (quaternion,euler vector3,quaternion vector4)
 316  *
 317  * @param[in] value Propery value
 318  * @param[out] quaternion Output Rotation
 319  * @return true if quaternion was set
 320  */
 321 DALI_IMPORT_API bool SetRotation( const Property::Value& value, Quaternion& quaternion );
 322
 323 }
 324
 325 } // namespace Dali
 326
 327 #endif // __DALI_SCRIPTING_H__