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