1 #ifndef DALI_APPLICATION_H
2 #define DALI_APPLICATION_H
5 * Copyright (c) 2022 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/object/base-handle.h>
23 #include <dali/public-api/signals/callback.h>
26 #include <dali/public-api/adaptor-framework/device-status.h>
27 #include <dali/public-api/adaptor-framework/window.h>
34 * @addtogroup dali_adaptor_framework
38 namespace Internal DALI_INTERNAL
44 } // namespace DALI_INTERNAL
46 * @brief An Application class object should be created by every application
47 * that wishes to use Dali.
49 * It provides a means for initializing the
50 * resources required by the Dali::Core.
52 * The Application class emits several signals which the user can
53 * connect to. The user should not create any Dali objects in the main
54 * function and instead should connect to the Init signal of the
55 * Application and create the Dali objects in the connected callback.
57 * Applications should follow the example below:
60 * class ExampleController: public ConnectionTracker
63 * ExampleController( Application& application )
64 * : mApplication( application )
66 * mApplication.InitSignal().Connect( this, &ExampleController::Create );
69 * void Create( Application& application )
71 * // Create Dali components...
75 * Application& mApplication;
78 * int main (int argc, char **argv)
80 * Application app = Application::New(&argc, &argv);
81 * ExampleController example( app );
86 * If required, you can also connect class member functions to a signal:
90 * app.ResumeSignal().Connect(&app, &MyApplication::Resume);
95 * There is the UI thread feature.
96 * UI thread is an additional thread that an Application object creates. The thread is for UI events.
98 * When the UI thread feature is enabled, you can use the task signals(TaskInit, TaskTerminate, TaskAppControl, TaskLanguageChanged, TaskLowBattery, and TaskLowMemory).
99 * The task signals are emitted on the main thread,
100 * and the normal signals(Init, Terminate, Pause, Resume, Reset, AppControl, LanguageChanged, Region, LowBattery, and LowMemory) are emitted on the UI thread.
102 * If you want to handle windows or actors in cases like when the memory level of the device is low, you have to use the normal signals, not the task signals.
103 * Callbacks of all signals in DALi except the task signals are emitted on the UI thread. (e.g., Timer callbacks are emitted on the UI thread.)
105 * To enable the UI Thread, you can use this method. you have to set True to the useUiThread.
106 * Dali::Application::New(int *argc, char **argv[], const std::string &stylesheet, Application::WINDOW_MODE windowMode, PositionSize positionSize, bool useUiThread)
109 * This class accepts command line arguments as well. The following options are supported:
112 * -w|--width Stage Width
113 * -h|--height Stage Height
114 * -d|--dpi Emulated DPI
118 * When the above options are found, they are stripped from argv, and argc is updated appropriately.
121 class DALI_ADAPTOR_API Application : public BaseHandle
124 typedef Signal<void(DeviceStatus::Battery::Status)> LowBatterySignalType; ///< Application device signal type @SINCE_1_2.62
125 typedef Signal<void(DeviceStatus::Memory::Status)> LowMemorySignalType; ///< Application device signal type @SINCE_1_2.62
126 typedef Signal<void(Application&)> AppSignalType; ///< Application lifecycle signal and system signal callback type @SINCE_1_0.0
127 typedef Signal<void(Application&, void*)> AppControlSignalType; ///< Application control signal callback type @SINCE_1_0.0
130 * @brief Enumeration for deciding whether a Dali application window is opaque or transparent.
135 OPAQUE = 0, ///< The window will be opaque @SINCE_1_0.0
136 TRANSPARENT = 1 ///< The window transparency will match the alpha value set in Dali::Stage::SetBackgroundcolor() @SINCE_1_0.0
141 * @brief This is the constructor for applications without an argument list.
145 * @return A handle to the Application
147 static Application New();
150 * @brief This is the constructor for applications.
155 * @param[in,out] argc A pointer to the number of arguments
156 * @param[in,out] argv A pointer to the argument list
157 * @return A handle to the Application
159 static Application New(int* argc, char** argv[]);
162 * @brief This is the constructor for applications with a name.
167 * @param[in,out] argc A pointer to the number of arguments
168 * @param[in,out] argv A pointer to the argument list
169 * @param[in] stylesheet The path to user defined theme file
170 * @return A handle to the Application
171 * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
173 static Application New(int* argc, char** argv[], const std::string& stylesheet);
176 * @brief This is the constructor for applications with a name.
181 * @param[in,out] argc A pointer to the number of arguments
182 * @param[in,out] argv A pointer to the argument list
183 * @param[in] stylesheet The path to user defined theme file
184 * @param[in] windowMode A member of WINDOW_MODE
185 * @return A handle to the Application
186 * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
188 static Application New(int* argc, char** argv[], const std::string& stylesheet, WINDOW_MODE windowMode);
191 * @brief This is the constructor for applications.
196 * @param[in,out] argc A pointer to the number of arguments
197 * @param[in,out] argv A pointer to the argument list
198 * @param[in] stylesheet The path to user defined theme file
199 * @param[in] windowMode A member of WINDOW_MODE
200 * @param[in] positionSize A position and a size of the window
201 * @return A handle to the Application
202 * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
204 static Application New(int* argc, char** argv[], const std::string& stylesheet, Application::WINDOW_MODE windowMode, PositionSize positionSize);
207 * @brief This is the constructor for applications.
212 * @param[in,out] argc A pointer to the number of arguments
213 * @param[in,out] argv A pointer to the argument list
214 * @param[in] stylesheet The path to user defined theme file
215 * @param[in] windowMode A member of WINDOW_MODE
216 * @param[in] positionSize A position and a size of the window
217 * @param[in] useUiThread True if the application would create a UI thread
218 * @return A handle to the Application
219 * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.<BR>
220 * UI thread is an additional thread that DALi creates for UI events.
221 * The UI thread isn't blocked from the system events(AppControl, LanguageChanged, RegionChanged, LowMemory, LowBattery task signals).
223 static Application New(int* argc, char** argv[], const std::string& stylesheet, Application::WINDOW_MODE windowMode, PositionSize positionSize, bool useUiThread);
226 * @brief Constructs an empty handle.
232 * @brief Copy Constructor.
234 * @param[in] application Handle to an object
236 Application(const Application& application);
239 * @brief Assignment operator.
241 * @param[in] application Handle to an object
242 * @return A reference to this
244 Application& operator=(const Application& application);
247 * @brief Move constructor.
250 * @param[in] rhs A reference to the moved handle
252 Application(Application&& rhs);
255 * @brief Move assignment operator.
258 * @param[in] rhs A reference to the moved handle
259 * @return A reference to this handle
261 Application& operator=(Application&& rhs);
266 * This is non-virtual since derived Handle types must not contain data or virtual methods.
273 * @brief This starts the application.
275 * On platforms where context loss can occur, the application is responsible for tearing down and
276 * re-loading UI. The application should listen to Stage::ContextLostSignal and
277 * Stage::ContextRegainedSignal.
284 * @brief This lowers the application to bottom without actually quitting it.
290 * @brief This quits the application. Tizen applications should use Lower to improve re-start performance unless they need to Quit completely.
296 * @brief Ensures that the function passed in is called from the main loop when it is idle.
298 * @param[in] callback The function to call
299 * @return @c true if added successfully, @c false otherwise
301 * @note Function must be called from main event thread only
303 * A callback of the following type may be used:
307 * This callback will be deleted once it is called.
309 * @note Ownership of the callback is passed onto this class.
311 bool AddIdle(CallbackBase* callback);
314 * @brief Retrieves the main window used by the Application class.
316 * The application writer can use the window to change indicator and orientation
319 * @return A handle to the window
324 * @brief Get path application resources are stored at
327 * @return the full path of the resources
329 static std::string GetResourcePath();
332 * @brief This is used to get region information from device.
335 * @return Region information
337 std::string GetRegion() const;
340 * @brief This is used to get language information from device.
343 * @return Language information
345 std::string GetLanguage() const;
348 * @brief Gets the Object registry.
351 * @return The object registry
352 * @note This will only be a valid handle after the InitSignal has been emitted.
354 ObjectRegistry GetObjectRegistry() const;
358 * @brief The user should connect to this signal to determine when they should initialize
360 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
361 * Otherwise, it is emitted on the main thread.
363 * @return The signal to connect to
365 AppSignalType& InitSignal();
368 * @brief The user should connect to this signal to determine when they should terminate
370 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
371 * Otherwise, it is emitted on the main thread.
373 * @return The signal to connect to
375 AppSignalType& TerminateSignal();
378 * @brief The user should connect to this signal if they need to perform any special
379 * activities when the application is about to be paused.
380 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
381 * Otherwise, it is emitted on the main thread.
383 * @return The signal to connect to
385 AppSignalType& PauseSignal();
388 * @brief The user should connect to this signal if they need to perform any special
389 * activities when the application has resumed.
390 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
391 * Otherwise, it is emitted on the main thread.
393 * @return The signal to connect to
395 AppSignalType& ResumeSignal();
398 * @brief This signal is sent when the system requires the user to reinitialize itself.
399 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
400 * Otherwise, it is emitted on the main thread.
402 * @return The signal to connect to
404 AppSignalType& ResetSignal();
407 * @brief This signal is emitted when another application sends a launch request to the application.
409 * When the application is launched, this signal is emitted after the main loop of the application starts up.
410 * The passed parameter describes the launch request and contains the information about why the application is launched.
411 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
412 * Otherwise, it is emitted on the main thread.
414 * @return The signal to connect to
416 AppControlSignalType& AppControlSignal();
419 * @brief This signal is emitted when the language is changed on the device.
420 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
421 * Otherwise, it is emitted on the main thread.
423 * @return The signal to connect to
425 AppSignalType& LanguageChangedSignal();
428 * @brief This signal is emitted when the region of the device is changed.
429 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
430 * Otherwise, it is emitted on the main thread.
432 * @return The signal to connect to
434 AppSignalType& RegionChangedSignal();
437 * @brief This signal is emitted when the battery level of the device is low.
438 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
439 * Otherwise, it is emitted on the main thread.
441 * @return The signal to connect to
443 LowBatterySignalType& LowBatterySignal();
446 * @brief This signal is emitted when the memory level of the device is low.
447 * Only when the user uses the UiThread, this signal is emitted on the UI thread.
448 * Otherwise, it is emitted on the main thread.
450 * @return The signal to connect to
452 LowMemorySignalType& LowMemorySignal();
456 * @brief The user should connect to this signal to determine when they should initialize
458 * Only when the user uses the UiThread, this signal is emitted on the main thread.
459 * Otherwise, it is not emitted at all.
460 * @return The signal to connect to
462 AppSignalType& TaskInitSignal();
465 * @brief The user should connect to this signal to determine when they should terminate
467 * Only when the user uses the UiThread, this signal is emitted on the main thread.
468 * Otherwise, it is not emitted at all.
469 * @return The signal to connect to
471 AppSignalType& TaskTerminateSignal();
474 * @brief This signal is emitted when another application sends a launch request to the application.
476 * When the application is launched, this signal is emitted after the main loop of the application starts up.
477 * The passed parameter describes the launch request and contains the information about why the application is launched.
478 * Only when the user uses the UiThread, this signal is emitted on the main thread.
479 * Otherwise, it is not emitted at all.
480 * @return The signal to connect to
482 AppControlSignalType& TaskAppControlSignal();
485 * @brief This signal is emitted when the language is changed on the device.
486 * Only when the user uses the UiThread, this signal is emitted on the main thread.
487 * Otherwise, it is not emitted at all.
488 * @return The signal to connect to
490 AppSignalType& TaskLanguageChangedSignal();
493 * @brief This signal is emitted when the region of the device is changed.
494 * Only when the user uses the UiThread, this signal is emitted on the main thread.
495 * Otherwise, it is not emitted at all.
496 * @return The signal to connect to
498 AppSignalType& TaskRegionChangedSignal();
501 * @brief This signal is emitted when the battery level of the device is low.
502 * Only when the user uses the UiThread, this signal is emitted on the main thread.
503 * Otherwise, it is not emitted at all.
504 * @return The signal to connect to
506 LowBatterySignalType& TaskLowBatterySignal();
509 * @brief This signal is emitted when the memory level of the device is low.
510 * Only when the user uses the UiThread, this signal is emitted on the main thread.
511 * Otherwise, it is not emitted at all.
512 * @return The signal to connect to
514 LowMemorySignalType& TaskLowMemorySignal();
516 public: // Not intended for application developers
519 * @brief Internal constructor.
522 explicit DALI_INTERNAL Application(Internal::Adaptor::Application* application);
531 #endif // DALI_APPLICATION_H