2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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.
19 * @brief This is the header file for the %UiApp class.
21 * This header file contains the declarations of the %UiApp class.
24 #ifndef _FAPP_UI_APP_H_
25 #define _FAPP_UI_APP_H_
29 namespace Tizen { namespace Base { namespace Collection { class IList; } } }
30 namespace Tizen { namespace Ui { namespace Controls { class Frame; } } }
32 namespace Tizen { namespace App
38 typedef UiApp* (*UiAppInstanceFactory)(void);
42 * @brief This class is the base class of a %Tizen native UI application.
46 * The %UiApp class is the base class of a %Tizen native UI application.@n
47 * A %Tizen native UI application must inherit from the %UiApp class. This class provides the basic features necessary to define the
48 * %Tizen native UI application.
50 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_namespace.htm">App Guide</a> and <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/tizen_app_model/application_model.htm">Native Application Model</a>.
53 class _OSP_EXPORT_ UiApp
54 : public Tizen::App::App
58 * This destructor overrides Tizen::Base::Object::~Object().
65 * Gets the first frame to the frame list of the UI application.
69 * @return A pointer to the IAppFrame instance of the frame, @n
70 * else @c null if it fails
71 * @exception E_SUCCESS The method is successful.
72 * @exception E_INVALID_STATE The frame has not been initialized properly.
73 * @exception E_OBJ_NOT_FOUND The frame has not been found.
75 IAppFrame* GetAppFrame(void) const;
78 * Adds a frame to the end of the list that is maintained by the UI application.
82 * @return An error code
83 * @param[in] frame The frame that is added to the UI application
84 * @exception E_SUCCESS The method is successful.
85 * @exception E_INVALID_ARG The specified input parameter is invalid.
86 * @exception E_INVALID_STATE The application is in an invalid state.
87 * @exception E_OBJ_ALREADY_EXIST The frame to be added is already registered with the UI application.
88 * @exception E_OUT_OF_MEMORY The memory is insufficient.
89 * @exception E_MAX_EXCEEDED The number of frames has exceeded the maximum limit.
90 * @exception E_SYSTEM A system error has occurred.
92 result AddFrame(const Tizen::Ui::Controls::Frame& frame);
95 * Removes the specified @c frame from the UI application.
99 * @return An error code
100 * @param[in] frame The frame to remove
101 * @exception E_SUCCESS The method is successful.
102 * @exception E_OBJ_NOT_FOUND The specified @c frame cannot be found.
103 * @exception E_SYSTEM A system error has occurred.
104 * @remarks The removed frame is deleted from the memory.
106 result RemoveFrame(const Tizen::Ui::Controls::Frame& frame);
109 * Gets the list of the frames of the UI application.
113 * @return A pointer to the Tizen::Base::Collection::IList that contains the Tizen::Ui::Frame instances, @n
114 * else @c null if it fails
115 * @exception E_SUCCESS The method is successful.
116 * @exception E_INVALID_STATE The application is in an invalid state.
117 * @remarks The specific error code can be accessed using the GetLastResult() method.
119 Tizen::Base::Collection::IList* GetFrameList(void) const;
122 * Gets the frame with the specified @c name.
126 * @return A pointer to the frame that contains the specified @c name, @n
127 * else @c null if it fails
128 * @param[in] name The name of the frame
129 * @exception E_SUCCESS The method is successful.
130 * @exception E_OBJ_NOT_FOUND The specified @c frame cannot be found.
131 * @remarks The specific error code can be accessed using the GetLastResult() method.
133 Tizen::Ui::Controls::Frame* GetFrame(const Tizen::Base::String& name) const;
136 * Gets the frame at the specified @c index in the list.
140 * @return A pointer to the frame at the specified @c index, @n
141 * else @c null if it fails
142 * @param[in] index The index of the frame
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_OUT_OF_RANGE The specified @c index is outside the bounds of the frame list.
145 * @remarks The specific error code can be accessed using the GetLastResult() method.
147 Tizen::Ui::Controls::Frame* GetFrameAt(int index) const;
150 * Gets the UI state of the UI application.
154 * @return The UI state of the UI application
155 * @remarks Note that the UiApp::OnBackground() method is invoked when the UI state of the UI application changes
156 * from App::APP_UI_STATE_FOREGROUND to App::APP_UI_STATE_PARTIAL_BACKGROUND, or App::APP_UI_STATE_BACKGROUND.
158 AppUiState GetAppUiState(void) const;
161 * Called when the UI application moves to the foreground. @n
162 * User interaction is enabled when the UI application moves to the foreground. @n
163 * A UI application moves to the foreground when:
165 * - The UI application is selected from the Task Switcher.
166 * - The UI application icon in the Launcher application is pressed when it is running in the background.
167 * - The UI application is to be launched while it is running in the background.
168 * - A system pop-up, such as an incoming call, a notification (for example, an SMS), or a low battery warning
171 * When the %OnForeground() method is invoked, the following actions are recommended:
173 * - Resume the graphic processing, such as 3D or animation, as the UI application now has the focus.
174 * - Resume the operations that stopped when the UI application is last moved to the background.
178 * @remarks When the system needs to refresh a screen component, it can call this method even if the UI application is present in the foreground.
180 virtual void OnForeground(void);
183 * Called when another UI application moves to the top or a system pop-up is displayed. @n
184 * User interaction is disabled when the UI application is in the background. @n
185 * A UI application moves to the background when:
187 * - A system pop-up, such as an incoming call or a low battery warning pop-up is displayed.
188 * - The device is locked.
189 * - The Home key is pressed.
191 * When the %OnBackground() method is invoked, the following actions are recommended:
193 * - Stop the graphic processing, such as 3D or animation, as they will not be displayed.
194 * - Release unnecessary resources.
195 * - Stop media processing, sensor manipulations, and location updates.
200 * - When a notification (for example, an SMS) pops up, this method is not called.
201 * - When a system pop-up is displayed, the UI application becomes partially hidden (App::APP_UI_STATE_PARTIAL_BACKGROUND).
202 * - If the UI application is partially hidden, it is recommended to hold the activated tasks or resources instead of stopping or releasing them.
203 * @see GetAppUiState()
205 virtual void OnBackground(void);
208 * Gets a pointer to the %UiApp instance.
212 * @return A pointer to the %UiApp instance, @n
213 * else @c null if it fails
215 static UiApp* GetInstance(void);
218 * Executes an application implemented by inheriting this class.
219 * The %Execute() method must be called from the entry method, that is, OspMain(), which is generated by IDE.
223 * @return An error code
224 * @param[in] pUiAppFactory The factory method that creates this UiApp instance
225 * @param[in] pArguments The launch arguments for the application
226 * @exception E_SUCCESS The method is successful.
227 * @exception E_INVALID_ARG A specified input parameter is invalid.
228 * @exception E_OUT_OF_MEMORY The memory is insufficient.
229 * @exception E_INIT_FAILED A failure occurred while initializing using the OnAppInitializing() method.
230 * @exception E_SYSTEM A system error has occurred.
232 static result Execute(UiAppInstanceFactory pUiAppFactory, const Tizen::Base::Collection::IList* pArguments);
236 * This is the default constructor for this class.
243 // This method is for internal use only.
244 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
246 // This method is reserved and may change its name at any time without prior notice.
250 virtual void UiApp_Reserved1(void) {}
253 // This method is for internal use only.
254 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
256 // This method is reserved and may change its name at any time without prior notice.
260 virtual void UiApp_Reserved2(void) {}
263 // This method is for internal use only.
264 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
266 // This method is reserved and may change its name at any time without prior notice.
270 virtual void UiApp_Reserved3(void) {}
274 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
278 UiApp(const UiApp& rhs);
281 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
285 UiApp& operator =(const UiApp& rhs);
288 class _UiAppImpl* __pUiAppImpl;
291 typedef UiApp Application;
295 #endif // _FAPP_UI_APP_H_