[dali_2.1.42] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / 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