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