2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
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 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.
124 * @remarks The maximum number of Forms that an application can construct is limited by available memory.
125 * @remarks The specified position and size are only applied when the show mode is not #FRAME_SHOW_MODE_FULL_SCREEN.
127 result Construct(const Tizen::Graphics::Rectangle& rect);
130 * Initializes this instance of %Frame with the specified position and size.
134 * @return An error code
135 * @param[in] rect An instance of the FloatRectangle class @n
136 * This instance represents the x and y coordinates of the top-left corner @n
137 * of the created window along with its width and height. @n
138 * @exception E_SUCCESS The method is successful.
139 * @exception E_INVALID_ARG The specified input parameter is invalid.
140 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation (that
141 * is, the method is called on an instance that is constructed).
142 * @exception E_MAX_EXCEEDED The number of Frames and Forms exceeds the system limitation.
143 * @exception E_SYSTEM A system error has occurred.
144 * @remarks The maximum number of Forms that an application can construct is limited by available memory.
145 * @remarks The specified position and size are only applied when the show mode is not #FRAME_SHOW_MODE_FULL_SCREEN.
147 result Construct(const Tizen::Graphics::FloatRectangle& rect);
152 * Adds an IOrientationEventListener instance. @n
153 * The added listener can listen to events on the given event dispatcher's context when they are fired.
157 * @param[in] listener The listener to add
158 * @remarks When OnOrientationChanged() event is fired, re-position and draw the child controls, but do not explicitly call
160 * @see RemoveOrientationEventListener()
162 void AddOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
165 * Adds an IFrameEventListener instance. @n
166 * The added listener can listen to events on the given event dispatcher's context when they are fired.
170 * @param[in] listener The listener to add
171 * @see RemoveFrameEventListener()
173 void AddFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
176 * Removes an IOrientationEventListener instance. @n
177 * The removed listener cannot listen to events when they are fired.
181 * @param[in] listener The listener to remove
182 * @see AddOrientationEventListener()
184 void RemoveOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
187 * Removes an IFrameEventListener instance. @n
188 * The removed listener cannot listen to events when they are fired.
192 * @param[in] listener The listener to remove
193 * @see AddFrameEventListener()
195 void RemoveFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
200 * Gets the current %Form control of the %Frame control.
204 * @return The current Form, @n
205 * else @c null if there is no %Form
206 * @see SetCurrentForm()
208 Form* GetCurrentForm(void) const;
211 * Sets the specified Form control as the current %Form of the %Frame control.
213 * @brief <i> [Deprecated] </i>
214 * @deprecated This API is deprecated.
217 * @return An error code
218 * @param[in] form The form to set as the current form of the %Frame control
219 * @exception E_SUCCESS The method is successful.
220 * @exception E_INVALID_ARG The specified input parameter is invalid.
221 * The specified @c form is not a child control of the %Frame control.
222 * @exception E_SYSTEM A system error has occurred.
223 * @remarks If a form is set as the current form, it becomes the topmost form amongst its siblings. @n
224 * SetCurrentForm() does not call Invalidate() internally, so if the current form needs to be drawn
225 * immediately, Invalidate() should be called after SetCurrentForm().
226 * Only Frame whose show mode is @c FRAME_SHOW_MODE_FULL_SCREEN can set a Form which has the style of @c FORM_STYLE_INDICATOR as the current form.
228 result SetCurrentForm(const Form& form);
231 * Sets the specified Form control as the current %Form of the %Frame control.
235 * @return An error code
236 * @param[in] pForm The form to be set as the current form of the %Frame control
237 * @exception E_SUCCESS The method is successful.
238 * @exception E_INVALID_ARG The specified input parameter is invalid.
239 * The specified @c form is not a child control of the %Frame control.
240 * @exception E_SYSTEM A system error has occurred.
241 * @remarks If a form is set as the current form, it becomes the topmost form amongst its siblings. @n
242 * SetCurrentForm() does not call Invalidate() internally, so if the current form needs to be drawn
243 * immediately, Invalidate() should be called after SetCurrentForm().
244 * Only Frame whose show mode is @c FRAME_SHOW_MODE_FULL_SCREEN can set a Form which has the style of @c FORM_STYLE_INDICATOR as the current form.
246 result SetCurrentForm(Form* pForm);
249 * Gets the background color of the %Frame control.
253 * @return The background color of the %Frame control
255 Tizen::Graphics::Color GetBackgroundColor(void) const;
258 * Sets the background color of the %Frame control.
262 * @param[in] color The background color
264 void SetBackgroundColor(const Tizen::Graphics::Color& color);
267 * Sets the orientation mode of a frame.
271 * @param[in] orientation The orientation mode of the %Frame control
272 * @remarks To see the change in the orientation mode, the corresponding frame must be the topmost frame in the z-order hierarchy.
275 void SetOrientation(Tizen::Ui::Orientation orientation);
278 * Gets the orientation mode of the frame.
282 * @return The orientation mode of the frame
284 Tizen::Ui::Orientation GetOrientation(void) const;
287 * Gets the current orientation status of the frame.
291 * @return The orientation status
292 * @remarks The method returns ORIENTATION_STATUS_NONE if the %Frame control is not drawn.
293 * Once it is drawn, the orientation of the %Frame control is set to portrait and the method
294 * returns ORIENTATION_STATUS_PORTRAIT if the application has not specified its orientation.
296 Tizen::Ui::OrientationStatus GetOrientationStatus(void) const;
299 * Gets the FrameAnimator of %Frame.
303 * @return %FrameAnimator, @n
304 * else @c null if this instance is not constructed as yet
306 Tizen::Ui::Animations::FrameAnimator* GetFrameAnimator(void) const;
309 * Sets the mode to show the %Frame control.
313 * @return An error code
314 * @param[in] mode The mode to show the %Frame control
315 * @exception E_SUCCESS The method is successful.
316 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
317 * @remarks The default mode is #FRAME_SHOW_MODE_FULL_SCREEN.
319 result SetShowMode(FrameShowMode mode);
322 * Gets the mode to show the %Frame control.
326 * @return The mode to show the %Frame control
327 * @remarks The default mode is #FRAME_SHOW_MODE_FULL_SCREEN.
329 FrameShowMode GetShowMode(void) const;
332 friend class _FrameImpl;
335 //This method is for internal use only. Using this method can cause behavioral, security-related,
336 //and consistency-related issues in the application.
338 // This method is reserved and may change its name at any time without
343 virtual void Frame_Reserved1(void) { }
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_Reserved2(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_Reserved3(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_Reserved4(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_Reserved5(void) { }
391 Frame& operator =(const Frame&);
394 }}} // Tizen::Ui::Controls
396 #endif // _FUI_CTRL_FRAME_H_