2 * Copyright (c) 2011 - 2016 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __TIZEN_APPFW_APP_H__
19 #define __TIZEN_APPFW_APP_H__
22 #include <app_control.h>
23 #include <app_alarm.h>
24 #include <app_common.h>
25 #include <app_preference.h>
27 #include <app_types.h>
34 * @addtogroup CAPI_APPLICATION_MODULE
40 * @brief Called when the application starts.
42 * @details The callback function is called before the main loop of the application starts.
43 * In this callback, you can initialize application resources like window creation, data structure, and so on.
44 * After this callback function returns @c true, the main loop starts up and app_control_cb() is subsequently called.
45 * If this callback function returns @c false, the main loop doesn't start and app_terminate_cb() is subsequently called.
47 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
48 * @param[in] user_data The user data passed from the callback registration function
49 * @return @c true on success,
51 * @pre ui_app_main() will invoke this callback function.
53 * @see #ui_app_lifecycle_callback_s
55 typedef bool (*app_create_cb) (void *user_data);
59 * @brief Called when the application is completely obscured by another application and becomes invisible.
61 * @details The application is not terminated and still running in the paused state.
63 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
64 * @param[in] user_data The user data passed from the callback registration function
66 * @see #ui_app_lifecycle_callback_s
68 typedef void (*app_pause_cb) (void *user_data);
72 * @brief Called when the application becomes visible.
74 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
76 * @param[in] user_data The user data passed from the callback registration function
78 * @see #ui_app_lifecycle_callback_s
80 typedef void (*app_resume_cb) (void *user_data);
84 * @brief Called when the application's main loop exits.
85 * @details You should release the application's resources in this function.
87 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
88 * @param[in] user_data The user data passed from the callback registration function
90 * @see #ui_app_lifecycle_callback_s
92 typedef void (*app_terminate_cb) (void *user_data);
96 * @brief Called when another application sends a launch request to the application.
98 * @details When the application is launched, this callback function is called after the main loop of the application starts up.
99 * The passed app_control handle describes the launch request and contains the information about why the application is launched.
100 * If the launch request is sent to the application in the running or pause state,
101 * this callback function can be called again to notify that the application has been asked to launch.
103 * The application could be explicitly launched by the user from the application launcher or be launched to perform the specific operation by another application.
104 * The application is responsible for handling each launch request and responding appropriately.
105 * Using the App Control API, the application can get information about what is to be performed.
106 * If the application is launched from the application launcher or explicitly launched by another application,
107 * the passed app_control handle may include only the default operation (#APP_CONTROL_OPERATION_DEFAULT) without any data.
108 * For more information, see The @ref CAPI_APP_CONTROL_MODULE API description.
110 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
111 * @param[in] app_control The handle to the app_control
112 * @param[in] user_data The user data passed from the callback registration function
114 * @see #ui_app_lifecycle_callback_s
115 * @see @ref CAPI_APP_CONTROL_MODULE API
117 typedef void (*app_control_cb) (app_control_h app_control, void *user_data);
120 * @brief The structure type containing the set of callback functions for handling application lifecycle events.
121 * @details It is one of the input parameters of the ui_app_main() function.
123 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
125 * @see app_create_cb()
126 * @see app_pause_cb()
127 * @see app_resume_cb()
128 * @see app_terminate_cb()
129 * @see app_control_cb()
132 app_create_cb create; /**< This callback function is called at the start of the application. */
133 app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
134 app_pause_cb pause; /**< This callback function is called each time the application is completely obscured by another application and becomes invisible to the user. */
135 app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */
136 app_control_cb app_control; /**< This callback function is called when another application sends the launch request to the application. */
137 } ui_app_lifecycle_callback_s;
140 * @brief Gets the current device orientation.
142 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
143 * @return The current device orientation
145 app_device_orientation_e app_get_device_orientation(void);
148 * @brief Runs the application's main loop until ui_app_exit() is called.
150 * @details This function is the main entry point of the Tizen application.
151 * The app_create_cb() callback function is called to initialize the application before the main loop of application starts up.
152 * After the app_create_cb() callback function returns true, the main loop starts up and the app_control_cb() callback function is subsequently called.
153 * If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called.
154 * This main loop supports event handling for the Ecore Main Loop.
156 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
157 * @param[in] argc The argument count
158 * @param[in] argv The argument vector
159 * @param[in] callback The set of callback functions to handle application lifecycle events
160 * @param[in] user_data The user data to be passed to the callback functions
162 * @return 0 on success, otherwise a negative error value
163 * @retval #APP_ERROR_NONE Successful
164 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
165 * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
166 * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts
168 * @see app_create_cb()
169 * @see app_terminate_cb()
170 * @see app_pause_cb()
171 * @see app_resume_cb()
172 * @see app_control_cb()
174 * @see #ui_app_lifecycle_callback_s
176 int ui_app_main(int argc, char **argv, ui_app_lifecycle_callback_s *callback, void *user_data);
180 * @brief Exits the main loop of application.
182 * @details The main loop of application stops and app_terminate_cb() is invoked.
183 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
186 * @see app_terminate_cb()
188 void ui_app_exit(void);
192 * @brief Adds the system event handler
194 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
195 * @param[out] event_handler The event handler
196 * @param[in] event_type The system event type
197 * @param[in] callback The callback function
198 * @param[in] user_data The user data to be passed to the callback functions
200 * @return 0 on success, otherwise a negative error value
201 * @retval #APP_ERROR_NONE Successful
202 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
203 * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
205 * @see app_event_type_e
207 * @see ui_app_remove_event_handler
209 int ui_app_add_event_handler(app_event_handler_h *event_handler, app_event_type_e event_type, app_event_cb callback, void *user_data);
213 * @brief Removes registered event handler
215 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
216 * @param[in] event_handler The event handler
218 * @return 0 on success, otherwise a negative error value
219 * @retval #APP_ERROR_NONE Successful
220 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
222 * @see ui_app_add_event_handler
224 int ui_app_remove_event_handler(app_event_handler_h event_handler);
234 #endif /* __TIZEN_APPFW_APP_H__ */