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 struct StringEnum
  44 {
  45   const char* string; ///< The string representation
  46   const int value;    ///< The enumeration value wrapped in int
  47 };
  48
  49 /**
  50  * @brief Find the given enum index from the table
  51  *
  52  * @param[in]  value       The string equivalent (case-insensitive).
  53  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
  54  * @param[in]  tableCount  Number of items in the array.
  55  * @return The index of the enumeration. If enumeration is not found, logs an error and returns tableCount.
  56  */
  57 DALI_IMPORT_API unsigned int FindEnumIndex( const char* value, const StringEnum* table, unsigned int tableCount );
  58
  59 /**
  60  * @brief Chooses the appropriate enumeration for the provided string from the given table.
  61  *
  62  * @param[in]  value       The string equivalent (case-insensitive).
  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] result      The enum value
  66  *
  67  * @return True if the value was found from the table
  68  */
  69 template< typename T >
  70 bool GetEnumeration( const char* value, const StringEnum* table, unsigned int tableCount, T& result )
  71 {
  72   bool retVal( false );
  73   if( table )
  74   {
  75     unsigned int index = FindEnumIndex( value, table, tableCount );
  76     // check to avoid crash, not asserting on purpose, error is logged instead
  77     if( index < tableCount )
  78     {
  79       result = static_cast<T>( table[ index ].value );
  80       retVal = true;
  81     }
  82   }
  83   return retVal;
  84 }
  85
  86 /**
  87  * @brief Chooses the appropriate string for the provided enumeration from the given table.
  88  *
  89  * @param[in]  value       The enumeration.
  90  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
  91  * @param[in]  tableCount  Number of items in the array.
  92  *
  93  * @return The equivalent enumeration for the given string. Will return NULL if the value does not exist
  94  *
  95  * @note The caller is NOT responsible for cleaning up the returned pointer as it is statically allocated.
  96  */
  97 template< typename T >
  98 const char* GetEnumerationName( T value, const StringEnum* table, unsigned int tableCount )
  99 {
 100   if( table )
 101   {
 102     for ( unsigned int i = 0; i < tableCount; ++i )
 103     {
 104       if ( value == T(table[ i ].value) )
 105       {
 106         return table[ i ].string;
 107       }
 108     }
 109   }
 110   return NULL;
 111 }
 112
 113 /**
 114  * @brief Chooses the appropriate string for the provided enumeration from the given table.
 115  * This is an optimised version that handles enumerations that start at 0 and are linear only.
 116  *
 117  * @param[in]  value       The enumeration.
 118  * @param[in]  table       A pointer to an array with the enumeration to string equivalents.
 119  * @param[in]  tableCount  Number of items in the array.
 120  *
 121  * @return The equivalent enumeration for the given string. Will return NULL if the value does not exist
 122  *
 123  * @note The caller is NOT responsible for cleaning up the returned pointer as it is statically allocated.
 124  */
 125 template< typename T >
 126 const char * GetLinearEnumerationName( T value, const StringEnum* table, unsigned int tableCount )
 127 {
 128   if ( table && ( value > 0 || value <= (int)tableCount ) )
 129   {
 130     return table[value].string;
 131   }
 132   return NULL;
 133 }
 134
 135 /**
 136  * @brief Takes a string and returns the appropriate color mode.
 137  *
 138  * @param[in] value The input string
 139  * @return The corresponding color-mode.
 140  */
 141 DALI_IMPORT_API ColorMode GetColorMode( const std::string& value );
 142
 143 /**
 144  * @brief Takes a color mode and returns the appropriate string equivalent.
 145  *
 146  * @param[in] value The color mode
 147  * @return The corresponding string.
 148  */
 149 DALI_IMPORT_API std::string GetColorMode( ColorMode value );
 150
 151 /**
 152  * @brief Takes a string and returns the appropriate position inheritance mode.
 153  *
 154  * @param[in] value The input string
 155  * @return The corresponding position-inheritance-mode.
 156  */
 157 DALI_IMPORT_API PositionInheritanceMode GetPositionInheritanceMode( const std::string& value );
 158
 159 /**
 160  * @brief Takes a position inheritance mode and returns the string equivalent.
 161  *
 162  * @param[in] value The position-inheritance-mode.
 163  * @return The corresponding string.
 164  */
 165 DALI_IMPORT_API std::string GetPositionInheritanceMode( PositionInheritanceMode value );
 166
 167 /**
 168  * @brief Takes a string and returns the appropriate draw mode.
 169  *
 170  * @param[in] value The input string
 171  * @return The corresponding draw-mode.
 172  */
 173 DALI_IMPORT_API DrawMode::Type GetDrawMode( const std::string& value );
 174
 175 /**
 176  * @brief Takes a draw-mode and returns the string equivalent.
 177  *
 178  * @param[in] value The draw-mode.
 179  * @return The corresponding string.
 180  */
 181 DALI_IMPORT_API std::string GetDrawMode( DrawMode::Type value );
 182
 183 /**
 184  * @brief Takes a string and returns the appropriate anchor-point or parent-origin constant.
 185  *
 186  * @param[in] value The input string
 187  * @return The corresponding anchor-point or parent-origin constant.
 188  */
 189 DALI_IMPORT_API Vector3 GetAnchorConstant( const std::string& value );
 190
 191 /**
 192  * @brief Creates object with data from the property value map.
 193  *
 194  * @param[in] property The property value map with the following valid fields:
 195  * @code
 196  * "filename":       type std::string
 197  * "load-policy"     type std::string (enum)
 198  * "release-policy"  type std::string (enum)
 199  * "width"           type float
 200  * "height"          type float
 201  * "pixel-format"    type std::string (enum)
 202  * "fitting-mode"    type std::string (enum)
 203  * "sampling-mode"   type std::string (enum)
 204  * "orientation"     type bool
 205  * "type"            type std::string (FrameBufferImage|BufferImage|ResourceImage(default))
 206  * @endcode
 207  * Some fields are optional and some only pertain to a specific type.
 208  *
 209  * @return a pointer to a newly created object.
 210  */
 211 DALI_IMPORT_API Image NewImage( const Property::Value& property );
 212
 213 /**
 214  * @brief Creates object with data from the property value map.
 215  *
 216  * @param[in] property The property value map with the following valid fields:
 217  * @code
 218  * // a program can be specified as string or a filename.
 219  * // some fields may be ignored depending on the geometry-type
 220  * "program":        type Map
 221  * {
 222  *   "vertex":                   type std::string
 223  *   "fragment":                 type std::string
 224  *   "vertex-prefix":            type std::string
 225  *   "fragment-prefix":          type std::string
 226  *   "text-vertex":              type std::string
 227  *   "text-fragment":            type std::string
 228  *   "vertex-filename":          type std::string
 229  *   "fragment-filename":        type std::string
 230  *   "vertex-prefix-filename":   type std::string
 231  *   "fragment-prefix-filename": type std::string
 232  *   "text-vertex-filename":     type std::string
 233  *   "text-fragment-filename":   type std::string
 234  *   "geometry-type":            type std::string (enum)
 235  *   "geometry-hints":           type std::string (enum)
 236  * }
 237  * // uniforms must be specified to be registered
 238  * "uUniform1":       type float,
 239  * "uUniform2":       type float, etc
 240  * @endcode
 241  *
 242  * @return a pointer to a newly created object.
 243  */
 244 DALI_IMPORT_API ShaderEffect NewShaderEffect( const Property::Value& property );
 245
 246 /**
 247  * @brief Creates an actor with the date from the property value map.
 248  *
 249  * @param[in] map The property value map with the properties (and hierarchy) of the actor required
 250  *                 For example:
 251  * @code
 252  * {
 253  *   "type": "ImageActor",
 254  *   "image":
 255  *   {
 256  *     "filename":"my-image-path.png"
 257  *   },
 258  *   "actors":
 259  *   [
 260  *     {
 261  *       "type":"Actor",
 262  *       "position":[0,0,0]
 263  *     }
 264  *   ]
 265  * }
 266  * @endcode
 267  *
 268  * @return Handle to the newly created actor.
 269  */
 270 DALI_IMPORT_API Actor NewActor( const Property::Map& map );
 271
 272 /**
 273  * @brief Creates a Property::Map from the actor provided.
 274  *
 275  * @param[in] actor The base-actor from which a Property::Map should be created
 276  * @param[out] map This map is cleared and a property map of actor and its children is filled in
 277  */
 278 DALI_IMPORT_API void CreatePropertyMap( Actor actor, Property::Map& map );
 279
 280 /**
 281  * @brief Creates a Property::Map from the image provided.
 282  *
 283  * @param[in] image The image from which a Property::Map should be created
 284  * @param[out] map This map is cleared and a property map of the image is filled in
 285  */
 286 DALI_IMPORT_API void CreatePropertyMap( Image image, Property::Map& map );
 287
 288 }
 289
 290 } // namespace Dali
 291
 292 #endif // __DALI_SCRIPTING_H__