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