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) 2016 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  * Signals
  58  * | %Signal Name            | Method                           |
  59  * |------------------------------------------------------------|
  60  * | styleChanged            | @ref StyleChangedSignal()        |
  61  * @SINCE_1_1.32
  62  */
  63 class DALI_IMPORT_API StyleManager : public BaseHandle
  64 {
  65 public:
  66
  67   /// @brief Style Changed signal. Emitted after controls have been updated
  68   typedef Signal< void ( StyleManager, StyleChange::Type ) >  StyleChangedSignalType;
  69
  70   /**
  71    * @brief Create a StyleManager handle; this can be initialised with StyleManager::Get()
  72    *
  73    * Calling member functions with an uninitialised handle is not allowed.
  74    * @SINCE_1_1.32
  75    */
  76   StyleManager();
  77
  78   /**
  79    * @brief Destructor
  80    *
  81    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  82    * @SINCE_1_1.32
  83    */
  84   ~StyleManager();
  85
  86   /**
  87    * @brief Get the singleton of StyleManager object.
  88    *
  89    * @SINCE_1_1.32
  90    * @return A handle to the StyleManager control.
  91    */
  92   static StyleManager Get();
  93
  94   /**
  95    * @brief Apply a new theme to the application. This will be merged
  96    * on top of the default Toolkit theme.
  97    *
  98    * If the application theme file doesn't style all controls that the
  99    * application uses, then the default Toolkit theme will be used
 100    * instead for those controls.
 101    *
 102    * On application startup, it is suggested that the theme file name is
 103    * passed to Application::New instead of using this API to prevent
 104    * controls being styled more than once.
 105    * @sa Application::New()
 106    *
 107    * @SINCE_1_1.32
 108    * @param[in] themeFile If a relative path is specified, then this is relative
 109    * to the directory returned by app_get_resource_path().
 110    */
 111   void ApplyTheme( const std::string& themeFile );
 112
 113   /**
 114    * @brief Apply the default Toolkit theme.
 115    *
 116    * Request that any application specific styling is removed
 117    * and that the default Toolkit theme is re-applied.
 118    *
 119    * @SINCE_1_1.32
 120    */
 121   void ApplyDefaultTheme();
 122
 123   /**
 124    * @brief Set a constant for use when building styles
 125    *
 126    * A constant is used in JSON files e.g. "myImage":"{RELATIVE_PATH}/image.jpg"
 127    * where the string "{RELATIVE_PATH}" is substituted with the value.
 128    *
 129    * @SINCE_1_1.32
 130    * @param[in] key The key of the constant
 131    * @param[in] value The value of the constant
 132    */
 133   void SetStyleConstant( const std::string& key, const Property::Value& value );
 134
 135   /**
 136    * @brief Return the style constant set for a specific key
 137    *
 138    * @SINCE_1_1.32
 139    * @param[in] key The key of the constant
 140    * @param[out] valueOut The value of the constant if it exists
 141    *
 142    * @return If the constant for key exists then return the constant in valueOut and return true
 143    */
 144   bool GetStyleConstant( const std::string& key, Property::Value& valueOut );
 145
 146   /**
 147    * @brief Apply the specified style to the control.
 148    *
 149    * @SINCE_1_1.32
 150    * @param[in] control The control to which to apply the style.
 151    * @param[in] jsonFileName The name of the JSON style file to apply. If a
 152    * relative path is specified, then this is relative to the directory
 153    * returned by app_get_resource_path().
 154    * @param[in] styleName The name of the style within the JSON file to apply.
 155    */
 156   void ApplyStyle( Toolkit::Control control, const std::string& jsonFileName, const std::string& styleName );
 157
 158 public: // Signals
 159
 160   /**
 161    * @brief This signal is emitted after the style (e.g. theme/font change) has changed
 162    * and the controls have been informed.
 163    *
 164    * @SINCE_1_1.32
 165    * A callback of the following type may be connected:
 166    * @code
 167    *   void YourCallbackName( StyleManager styleManager, StyleChange change );
 168    * @endcode
 169    * @return The signal to connect to.
 170    */
 171   StyleChangedSignalType& StyleChangedSignal();
 172
 173 public:
 174
 175   /**
 176    * @brief Allows the creation of a StyleManager handle from an internal pointer.
 177    *
 178    * @note Not intended for application developers
 179    * @SINCE_1_1.32
 180    * @param[in] impl A pointer to the object.
 181    */
 182   explicit DALI_INTERNAL StyleManager( Internal::StyleManager *impl );
 183
 184 }; // class StyleManager
 185
 186 /**
 187  * @}
 188  */
 189 } // namespace Toolkit
 190
 191 } // namespace Dali
 192
 193
 194 #endif /* __DALI_TOOLKIT_STYLE_MANAGER_H__ */