base/dali-toolkit/public-api/styling/style-manager.h

   1 #ifndef __DALI_TOOLKIT_STYLE_MANAGER_H__
   2 #define __DALI_TOOLKIT_STYLE_MANAGER_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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 // EXTERNAL INCLUDES
  21
  22 // INTERNAL INCLUDES
  23 #include <dali/dali.h>
  24 #include <dali-toolkit/public-api/controls/control.h>
  25
  26 namespace Dali DALI_IMPORT_API
  27 {
  28
  29 namespace Toolkit
  30 {
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class StyleManager;
  35 }
  36
  37 /**
  38  * @brief StyleManager provides the following functionalities:
  39  *
  40  * Applies various styles to Controls using the properties system.
  41  * On theme change a signal is raised that controls can be configured to listen to.
  42  *
  43  * The default theme is automatically loaded and applied.
  44  *
  45  * If the application wants to customize the theme, RequestThemeChange needs to be called.
  46  * Also, the default orientation is Portrait, if the application wants to adapt to the orientation change, call SetOrientation or SetOrienationValue.
  47  * @code
  48  *   const char* CUSTOM_THEME = DALI_SCRIPT_DIR "tizen-dark-theme.json";
  49  *
  50  *   void OnInit(Application& app)
  51  *   {
  52  *      Toolkit::StyleManager::Get().RequestThemeChange( CUSTOM_THEME );
  53  *      Toolkit::StyleManager::Get().SetOrientation( app.GetOrientation() );
  54  *      ...
  55  *   }
  56  * @endcode
  57  *
  58  * Internal::Control can be configured to register for the signals that are required from StyleManager,
  59  * such as theme change.
  60  */
  61 class StyleManager : public BaseHandle
  62 {
  63 public:
  64
  65   // Signals
  66   typedef SignalV2< void ( StyleManager ) > ThemeChangeSignalType;
  67
  68   /**
  69    * @brief Create a StyleManager handle; this can be initialised with StyleManager::Get()
  70    * Calling member functions with an uninitialised handle is not allowed.
  71    */
  72   StyleManager();
  73
  74   /**
  75    * @brief Virtual destructor.
  76    */
  77   virtual ~StyleManager();
  78
  79   /**
  80    * @brief Get the singleton of StyleManager object.
  81    *
  82    * @return A handle to the StyleManager control.
  83    */
  84   static StyleManager Get();
  85
  86   /**
  87    * @brief Specify the orientation value directly for the style manager
  88    *
  89    * @param[in] orientation The orientation in degrees
  90    */
  91   void SetOrientationValue( int orientation );
  92
  93   /**
  94    * @brief Return the orientation value
  95    *
  96    * @return The orientation value
  97    */
  98   int GetOrientationValue();
  99
 100   /**
 101    * @brief Set the orientation object. This will take precedence over setting the orientation value.
 102    *
 103    * @param[in] orientation Device orientation
 104    */
 105   void SetOrientation( Orientation orientation );
 106
 107   /**
 108    * @brief Return the orientation object
 109    *
 110    * @return The orientation.
 111    */
 112   Orientation GetOrientation();
 113
 114   /**
 115    * @brief Make a request to set the theme JSON file to one that exists in the Toolkit package.
 116    *
 117    * Multiple requests per event processing cycle can be made, but only the final one will be acted
 118    * on in the event processing finished callback.
 119    *
 120    * @param[in] themeFile This is just the JSON theme file name and not the full path.
 121    */
 122   void RequestThemeChange( const std::string& themeFile );
 123
 124   /**
 125    * @brief Request a change to the default theme
 126    */
 127   void RequestDefaultTheme();
 128
 129   /**
 130    * @brief Set a constant for use when building styles
 131    *
 132    * A constant is used in JSON files e.g. "my-image":"{ROOT_PATH}/mypath/image.jpg"
 133    * where the string "{ROOT_PATH}" is substituted with the value.
 134    *
 135    * @param[in] key The key of the constant
 136    * @param[in] value The value of the constant
 137    */
 138   void SetStyleConstant( const std::string& key, const Property::Value& value );
 139
 140   /**
 141    * @brief Return the style constant set for a specific key
 142    *
 143    * @param[in] key The key of the constant
 144    * @param[out] valueOut The value of the constant if it exists
 145    *
 146    * @return If the constant for key exists then return the constant in valueOut and return true
 147    */
 148   bool GetStyleConstant( const std::string& key, Property::Value& valueOut );
 149
 150   /**
 151    * @brief Apply the specified style to the control.
 152    *
 153    * The JSON file will be cached and subsequent calls using the same JSON file name will
 154    * use the already loaded cached values instead.
 155    *
 156    * @param[in] control The control to apply style.
 157    * @param[in] jsonFileName The name of the JSON style file to apply.
 158    * @param[in] styleName The name of the style within the JSON file to apply.
 159    */
 160   void ApplyStyle( Toolkit::Control control, const std::string& jsonFileName, const std::string& styleName );
 161
 162 public: // Signals
 163
 164   /**
 165    * @brief This signal is emitted whenever the theme is changed on device
 166    * A callback of the following type may be connected:
 167    * @code
 168    *   void YourCallbackName( StyleManager styleManager );
 169    * @endcode
 170    * @return The signal to connect to.
 171    */
 172   ThemeChangeSignalType& ThemeChangeSignal();
 173
 174 public:
 175
 176   /**
 177    * @brief Creates a new handle from the implementation.
 178    *
 179    * @param[in] impl A pointer to the object.
 180    */
 181   explicit DALI_INTERNAL StyleManager( Internal::StyleManager *impl );
 182
 183 }; // class StyleManager
 184
 185 } // namespace Toolkit
 186
 187 } // namespace Dali
 188
 189
 190 #endif /* __DALI_TOOLKIT_STYLE_MANAGER_H__ */