include/app.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17
  18 #ifndef __TIZEN_APPFW_APP_H__
  19 #define __TIZEN_APPFW_APP_H__
  20
  21 #include <tizen.h>
  22 #include <app_control.h>
  23 #include <app_alarm.h>
  24 #include <app_common.h>
  25 #include <app_preference.h>
  26 #include <app_i18n.h>
  27 #include <app_types.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * @addtogroup CAPI_APPLICATION_MODULE
  35  * @{
  36  */
  37
  38
  39 /**
  40  * @brief Called when the application starts.
  41  *
  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.
  46  *
  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,
  50  *         otherwise @c false
  51  * @pre ui_app_main() will invoke this callback function.
  52  * @see ui_app_main()
  53  * @see #ui_app_lifecycle_callback_s
  54  */
  55 typedef bool (*app_create_cb) (void *user_data);
  56
  57
  58 /**
  59  * @brief Called when the application is completely obscured by another application and becomes invisible.
  60  *
  61  * @details The application is not terminated and still running in the paused state.
  62  *
  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
  65  * @see ui_app_main()
  66  * @see #ui_app_lifecycle_callback_s
  67  */
  68 typedef void (*app_pause_cb) (void *user_data);
  69
  70
  71 /**
  72  * @brief Called when the application becomes visible.
  73  *
  74  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  75  *
  76  * @param[in] user_data The user data passed from the callback registration function
  77  * @see ui_app_main()
  78  * @see #ui_app_lifecycle_callback_s
  79  */
  80 typedef void (*app_resume_cb) (void *user_data);
  81
  82
  83 /**
  84  * @brief Called when the application's main loop exits.
  85  * @details You should release the application's resources in this function.
  86  *
  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
  89  * @see ui_app_main()
  90  * @see #ui_app_lifecycle_callback_s
  91  */
  92 typedef void (*app_terminate_cb) (void *user_data);
  93
  94
  95 /**
  96  * @brief Called when another application sends a launch request to the application.
  97  *
  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.
 102  *
 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.
 109  *
 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
 113  * @see ui_app_main()
 114  * @see #ui_app_lifecycle_callback_s
 115  * @see @ref CAPI_APP_CONTROL_MODULE API
 116  */
 117 typedef void (*app_control_cb) (app_control_h app_control, void *user_data);
 118
 119 /**
 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.
 122  *
 123  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 124  * @see ui_app_main()
 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()
 130  */
 131 typedef struct {
 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;
 138
 139 /**
 140  * @brief Gets the current device orientation.
 141  *
 142  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 143  * @return The current device orientation
 144  */
 145 app_device_orientation_e app_get_device_orientation(void);
 146
 147 /**
 148  * @brief Runs the application's main loop until ui_app_exit() is called.
 149  *
 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.
 155  *
 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
 161  *
 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
 167  *
 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()
 173  * @see ui_app_exit()
 174  * @see #ui_app_lifecycle_callback_s
 175  */
 176 int ui_app_main(int argc, char **argv, ui_app_lifecycle_callback_s *callback, void *user_data);
 177
 178
 179 /**
 180  * @brief Exits the main loop of application.
 181  *
 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
 184  *
 185  * @see ui_app_main()
 186  * @see app_terminate_cb()
 187  */
 188 void ui_app_exit(void);
 189
 190
 191 /**
 192  * @brief Adds the system event handler
 193  *
 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
 199  *
 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
 204  *
 205  * @see app_event_type_e
 206  * @see app_event_cb
 207  * @see ui_app_remove_event_handler
 208  */
 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);
 210
 211
 212 /**
 213  * @brief Removes registered event handler
 214  *
 215  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 216  * @param[in] event_handler The event handler
 217  *
 218  * @return 0 on success, otherwise a negative error value
 219  * @retval #APP_ERROR_NONE Successful
 220  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 221  *
 222  * @see ui_app_add_event_handler
 223  */
 224 int ui_app_remove_event_handler(app_event_handler_h event_handler);
 225
 226
 227 /**
 228  * @}
 229  */
 230
 231 #ifdef __cplusplus
 232 }
 233 #endif
 234 #endif /* __TIZEN_APPFW_APP_H__ */