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) 2019 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 // EXTERNAL INCLUDES
  21 #include <dali/public-api/adaptor-framework/style-change.h>
  22
  23 // INTERNAL INCLUDES
  24 #include <dali-toolkit/public-api/controls/control.h>
  25
  26 namespace Dali
  27 {
  28
  29 namespace Toolkit
  30 {
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class StyleManager;
  35 }
  36
  37 /**
  38  * @addtogroup dali_toolkit_managers
  39  * @{
  40  */
  41
  42 /**
  43  * @brief StyleManager informs applications of system theme change,
  44  * and supports application theme change at runtime.
  45  *
  46  * Applies various styles to Controls using the properties system.
  47  *
  48  * On theme change, it automatically updates all controls, then raises
  49  * a signal to inform the application.
  50  *
  51  * The default theme is automatically loaded and applied, followed by
  52  * any application specific theme defined in Application::New().
  53  *
  54  * If the application wants to customize the theme, RequestThemeChange
  55  * needs to be called.
  56  *
  57  * To supply resource paths ( in json ) the following constant is available: APPLICATION_RESOURCE_PATH.
  58  * It provides the path to the  application resource root folder, from there the filename can an be specified along with
  59  * any sub folders, e.g Images, Models etc.
  60  * The APPLICATION_RESOURCE_PATH can be retrieved using Application::GetResourcePath()
  61  *
  62  * Signals
  63  * | %Signal Name            | Method                           |
  64  * |------------------------------------------------------------|
  65  * | styleChanged            | @ref StyleChangedSignal()        |
  66  * @SINCE_1_1.32
  67  */
  68 class DALI_TOOLKIT_API StyleManager : public BaseHandle
  69 {
  70 public:
  71
  72   /// @brief Style Changed signal. Emitted after controls have been updated.
  73   typedef Signal< void ( StyleManager, StyleChange::Type ) >  StyleChangedSignalType;
  74
  75   /**
  76    * @brief Creates a StyleManager handle; this can be initialized with StyleManager::Get().
  77    *
  78    * Calling member functions with an uninitialized handle is not allowed.
  79    * @SINCE_1_1.32
  80    */
  81   StyleManager();
  82
  83   /**
  84    * @brief Destructor.
  85    *
  86    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  87    * @SINCE_1_1.32
  88    */
  89   ~StyleManager();
  90
  91   /**
  92    * @brief Gets the singleton of StyleManager object.
  93    *
  94    * @SINCE_1_1.32
  95    * @return A handle to the StyleManager control
  96    */
  97   static StyleManager Get();
  98
  99   /**
 100    * @brief Applies a new theme to the application. This will be merged
 101    * on top of the default Toolkit theme.
 102    *
 103    * If the application theme file doesn't style all controls that the
 104    * application uses, then the default Toolkit theme will be used
 105    * instead for those controls.
 106    *
 107    * On application startup, it is suggested that the theme file name is
 108    * passed to Application::New instead of using this API to prevent
 109    * controls being styled more than once.
 110    * @sa Application::New().
 111    *
 112    * @SINCE_1_1.32
 113    * @param[in] themeFile If a relative path is specified, then this is relative
 114    * to the directory returned by Application::GetResourcePath()
 115    */
 116   void ApplyTheme( const std::string& themeFile );
 117
 118   /**
 119    * @brief Applies the default Toolkit theme.
 120    *
 121    * Request that any application specific styling is removed
 122    * and that the default Toolkit theme is re-applied.
 123    *
 124    * @SINCE_1_1.32
 125    */
 126   void ApplyDefaultTheme();
 127
 128   /**
 129    * @brief Sets a constant for use when building styles.
 130    *
 131    * A constant is used in JSON files e.g. "myImage":"{RELATIVE_PATH}/image.jpg"
 132    * where the string "{RELATIVE_PATH}" is substituted with the value.
 133    *
 134    * @SINCE_1_1.32
 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 Returns the style constant set for a specific key.
 142    *
 143    * @SINCE_1_1.32
 144    * @param[in] key The key of the constant
 145    * @param[out] valueOut The value of the constant if it exists
 146    *
 147    * @return If the constant for key exists, then return the constant in valueOut and return true
 148    */
 149   bool GetStyleConstant( const std::string& key, Property::Value& valueOut );
 150
 151   /**
 152    * @brief Applies the specified style to the control.
 153    *
 154    * @SINCE_1_1.32
 155    * @param[in] control The control to which to apply the style
 156    * @param[in] jsonFileName The name of the JSON style file to apply. If a
 157    * relative path is specified, then this is relative to the directory
 158    * returned by Application::GetResourcePath()
 159    * @param[in] styleName The name of the style within the JSON file to apply
 160    */
 161   void ApplyStyle( Toolkit::Control control, const std::string& jsonFileName, const std::string& styleName );
 162
 163 public: // Signals
 164
 165   /**
 166    * @brief This signal is emitted after the style (e.g. theme/font change) has changed
 167    * and the controls have been informed.
 168    *
 169    * @SINCE_1_1.32
 170    * A callback of the following type may be connected:
 171    * @code
 172    *   void YourCallbackName( StyleManager styleManager, StyleChange change );
 173    * @endcode
 174    * @return The signal to connect to
 175    */
 176   StyleChangedSignalType& StyleChangedSignal();
 177
 178 public:
 179
 180   /// @cond internal
 181   /**
 182    * @brief Allows the creation of a StyleManager handle from an internal pointer.
 183    *
 184    * @note Not intended for application developers
 185    * @SINCE_1_1.32
 186    * @param[in] impl A pointer to the object
 187    */
 188   explicit DALI_INTERNAL StyleManager( Internal::StyleManager *impl );
 189   /// @endcond
 190
 191 }; // class StyleManager
 192
 193 /**
 194  * @}
 195  */
 196
 197 } // namespace Toolkit
 198
 199 } // namespace Dali
 200
 201 #endif // DALI_TOOLKIT_STYLE_MANAGER_H