2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0/
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FUiCtrlFrame.h
20 * @brief This is the header file for the %Frame class.
22 * This header file contains the declarations of the %Frame class.
24 #ifndef _FUI_CTRL_FRAME_H_
25 #define _FUI_CTRL_FRAME_H_
27 #include <FBaseTypes.h>
28 #include <FUiWindow.h>
29 #include <FUiIOrientationEventListener.h>
30 #include <FUiCtrlFrameTypes.h>
32 namespace Tizen { namespace Ui { namespace Animations {
34 } } } // Tizen::Ui::Animations
36 namespace Tizen { namespace App {
40 namespace Tizen { namespace Ui { namespace Controls
44 class IFrameEventListener;
48 * @brief This class provides the main frame window for an application.
52 * The %Frame class provides the main frame window for an application.
53 * A frame is the main top-level window of an application. It is the ultimate parent
54 * of all application controls.
56 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_frame.htm">Frame</a>.
58 * The following example demonstrates how to use the %Frame class
61 // Gets a pointer of the frame
62 Frame *pFrame = UiApp::GetInstance()->GetAppFrame()->GetFrame();
64 // Creates an instance of canvas
65 Canvas* pCanvas = new Canvas();
67 pCanvas->DrawText(Point(30, 30), L"FrameSample");
69 // Calls Invalidate();
70 pFrame->Invalidate(true);
74 class _OSP_EXPORT_ Frame
75 : public Tizen::Ui::Window
80 * This is the default constructor for this class.
87 * This is the destructor for this class.
94 * Initializes this instance of %Frame with the specified parameter.
98 * @return An error code
99 * @exception E_SUCCESS The method is successful.
100 * @exception E_INVALID_ARG The specified input parameter is invalid.
101 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation (that
102 * is, the method is called on an instance that is constructed).
103 * @exception E_MAX_EXCEEDED The number of Frames and Forms exceeds the system limitation.
104 * @exception E_SYSTEM A system error has occurred.
105 * @remarks The maximum number of Forms that an application can construct is limited by available memory.
107 result Construct(void);
110 * Initializes this instance of %Frame with the specified position and size.
114 * @return An error code
115 * @param[in] rect An instance of the Tizen::Graphics::Rectangle class @n
116 * This instance represents the x and y coordinates of the top-left corner @n
117 * of the created window along with its width and height. @n
118 * @exception E_SUCCESS The method is successful.
119 * @exception E_INVALID_ARG The specified input parameter is invalid.
120 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation (that
121 * is, the method is called on an instance that is constructed).
122 * @exception E_MAX_EXCEEDED The number of Frames and Forms exceeds the system limitation.
123 * @exception E_SYSTEM A system error has occurred.
125 * - The maximum number of Forms that an application can construct is limited by available memory.
126 * - The specified position and size are only applied when the show mode is not ::FRAME_SHOW_MODE_FULL_SCREEN.
128 result Construct(const Tizen::Graphics::Rectangle& rect);
131 * Initializes this instance of %Frame with the specified position and size.
135 * @return An error code
136 * @param[in] rect An instance of the Tizen::Graphics::FloatRectangle class @n
137 * This instance represents the x and y coordinates of the top-left corner @n
138 * of the created window along with its width and height. @n
139 * @exception E_SUCCESS The method is successful.
140 * @exception E_INVALID_ARG The specified input parameter is invalid.
141 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation (that
142 * is, the method is called on an instance that is constructed).
143 * @exception E_MAX_EXCEEDED The number of Frames and Forms exceeds the system limitation.
144 * @exception E_SYSTEM A system error has occurred.
146 * - The maximum number of Forms that an application can construct is limited by available memory.
147 * - The specified position and size are only applied when the show mode is not ::FRAME_SHOW_MODE_FULL_SCREEN.
149 result Construct(const Tizen::Graphics::FloatRectangle& rect);
154 * Adds an IOrientationEventListener instance. @n
155 * The added listener can listen to events on the given event dispatcher's context when they are fired.
159 * @param[in] listener The listener to add
160 * @remarks When OnOrientationChanged() event is fired, re-position and draw the child controls, but do not explicitly call
162 * @see RemoveOrientationEventListener()
164 void AddOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
167 * Adds an IFrameEventListener instance. @n
168 * The added listener can listen to events on the given event dispatcher's context when they are fired.
172 * @param[in] listener The listener to add
173 * @see RemoveFrameEventListener()
175 void AddFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
178 * Removes an IOrientationEventListener instance. @n
179 * The removed listener cannot listen to events when they are fired.
183 * @param[in] listener The listener to remove
184 * @see AddOrientationEventListener()
186 void RemoveOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
189 * Removes an IFrameEventListener instance. @n
190 * The removed listener cannot listen to events when they are fired.
194 * @param[in] listener The listener to remove
195 * @see AddFrameEventListener()
197 void RemoveFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
202 * Gets the current %Form control of the %Frame control.
206 * @return The current Form, @n
207 * else @c null if there is no %Form
208 * @see SetCurrentForm()
210 Form* GetCurrentForm(void) const;
213 * Sets the specified Form control as the current %Form of the %Frame control.
215 * @brief <i> [Deprecated] </i>
216 * @deprecated This method is deprecated.
219 * @return An error code
220 * @param[in] form The form to set as the current form of the %Frame control
221 * @exception E_SUCCESS The method is successful.
222 * @exception E_INVALID_ARG The specified input parameter is invalid.
223 * The specified @c form is not a child control of the %Frame control.
224 * @exception E_SYSTEM A system error has occurred.
226 * - If a form is set as the current form, it becomes the topmost form amongst its siblings.
227 * - This method does not call Invalidate() internally, so if the current form needs to be drawn
228 * immediately, Invalidate() should be called after SetCurrentForm().
229 * - Only Frame whose show mode is ::FRAME_SHOW_MODE_FULL_SCREEN
230 * can set a Form which has the style of ::FORM_STYLE_PORTRAIT_INDICATOR as the current form.
232 result SetCurrentForm(const Form& form);
235 * Sets a specified Form control as the current %Form of the %Frame control.
239 * @return An error code
240 * @param[in] pForm The form to set as the current form of the %Frame control
241 * @exception E_SUCCESS The method is successful.
242 * @exception E_INVALID_ARG The specified input parameter is invalid.
243 * The specified @c form is not a child control of the %Frame control.
244 * @exception E_SYSTEM A system error has occurred.
246 * - If a form is set as the current form, it becomes the topmost form amongst its siblings.
247 * - This method does not call Invalidate() internally, so if the current form needs to be drawn
248 * immediately, Invalidate() should be called after SetCurrentForm().
249 * - Only Frame whose show mode is ::FRAME_SHOW_MODE_FULL_SCREEN can set a Form which has
250 * the style of ::FORM_STYLE_PORTRAIT_INDICATOR as the current form.
252 result SetCurrentForm(Form* pForm);
255 * Gets the background color of the %Frame control.
259 * @return The background color of the %Frame control
261 Tizen::Graphics::Color GetBackgroundColor(void) const;
264 * Sets the background color of the %Frame control.
268 * @param[in] color The background color
270 void SetBackgroundColor(const Tizen::Graphics::Color& color);
273 * Sets the orientation mode of a frame.
277 * @feature %http://tizen.org/feature/screen.auto_rotation for the @c ORIENTATION_AUTOMATIC_FOUR_DIRECTION or
278 * @c ORIENTATION_AUTOMATIC value of @c orientation
279 * @param[in] orientation The orientation mode of the %Frame control
280 * @exception E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1 @n
281 * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
283 * - The specific error code can be accessed using the GetLastResult() method.
284 * - To see the change in the orientation mode, the corresponding frame must be the topmost frame in the z-order hierarchy.
286 void SetOrientation(Tizen::Ui::Orientation orientation);
289 * Gets the orientation mode of the frame.
293 * @return The orientation mode of the frame
295 Tizen::Ui::Orientation GetOrientation(void) const;
298 * Gets the current orientation status of the frame.
302 * @return The orientation status
303 * @remarks The method returns @c ORIENTATION_STATUS_NONE if the %Frame control is not drawn.
304 * Once it is drawn, the orientation of the %Frame control is set to portrait and the method
305 * returns @c ORIENTATION_STATUS_PORTRAIT if the application has not specified its orientation.
307 Tizen::Ui::OrientationStatus GetOrientationStatus(void) const;
310 * Gets the FrameAnimator of %Frame.
314 * @return %FrameAnimator, @n
315 * else @c null if this instance is not constructed as yet
317 Tizen::Ui::Animations::FrameAnimator* GetFrameAnimator(void) const;
320 * Sets the mode to show the %Frame control.
324 * @return An error code
325 * @param[in] mode The mode to show the %Frame control
326 * @exception E_SUCCESS The method is successful.
327 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
328 * @remarks The default mode is ::FRAME_SHOW_MODE_FULL_SCREEN.
330 result SetShowMode(FrameShowMode mode);
333 * Gets the mode to show the %Frame control.
337 * @return The mode to show the %Frame control
338 * @remarks The default mode is ::FRAME_SHOW_MODE_FULL_SCREEN.
340 FrameShowMode GetShowMode(void) const;
343 friend class _FrameImpl;
346 //This method is for internal use only. Using this method can cause behavioral, security-related,
347 //and consistency-related issues in the application.
349 // This method is reserved and may change its name at any time without
354 virtual void Frame_Reserved1(void) { }
357 //This method is for internal use only. Using this method can cause behavioral, security-related,
358 //and consistency-related issues in the application.
360 // This method is reserved and may change its name at any time without
365 virtual void Frame_Reserved2(void) { }
368 //This method is for internal use only. Using this method can cause behavioral, security-related,
369 //and consistency-related issues in the application.
371 // This method is reserved and may change its name at any time without
376 virtual void Frame_Reserved3(void) { }
379 //This method is for internal use only. Using this method can cause behavioral, security-related,
380 //and consistency-related issues in the application.
382 // This method is reserved and may change its name at any time without
387 virtual void Frame_Reserved4(void) { }
390 //This method is for internal use only. Using this method can cause behavioral, security-related,
391 //and consistency-related issues in the application.
393 // This method is reserved and may change its name at any time without
398 virtual void Frame_Reserved5(void) { }
402 Frame& operator =(const Frame&);
405 }}} // Tizen::Ui::Controls
407 #endif // _FUI_CTRL_FRAME_H_