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.
20 * @brief This is the header file for the %Form class.
22 * This header file contains the declarations of the %Form class.
24 #ifndef _FUI_CTRL_FORM_H_
25 #define _FUI_CTRL_FORM_H_
27 #include <FBaseTypes.h>
28 #include <FBaseString.h>
29 #include <FBaseColLinkedListT.h>
30 #include <FUiIActionEventListener.h>
31 #include <FUiContainer.h>
32 #include <FUiIOrientationEventListener.h>
33 #include <FUiCtrlControlsTypes.h>
34 #include <FUiCtrlOverlayRegion.h>
36 namespace Tizen { namespace Ui
38 class DataBindingContext;
41 namespace Tizen { namespace Ui { namespace Controls
46 class IFormBackEventListener;
51 * Defines the %Form control style.
57 FORM_STYLE_NORMAL = 0x00000000, /**< The basic form style */
58 FORM_STYLE_TITLE = 0x00000001, /**<@if OSPDEPREC @deprecated This enumeration field is deprecated because the use of the Title control is no longer recommended.@endif */
59 FORM_STYLE_INDICATOR = 0x00000002, /**< The form with the indicator area */
60 FORM_STYLE_SOFTKEY_0 = 0x00000010, /**<@if OSPDEPREC @deprecated This enumeration field is deprecated because the use of the Softkey control is no longer recommended.@endif */
61 FORM_STYLE_SOFTKEY_1 = 0x00000020, /**<@if OSPDEPREC @deprecated This enumeration field is deprecated because the use of the Softkey control is no longer recommended.@endif */
62 FORM_STYLE_OPTIONKEY = 0x00000040, /**<@if OSPDEPREC @deprecated This enumeration field is deprecated because the use of the Optionkey control is no longer recommended.@endif */
63 FORM_STYLE_TEXT_TAB = 0x00000100, /**<@if OSPDEPREC @deprecated This enumeration field is deprecated because the use of the Tab control is no longer recommended. @endif */
64 FORM_STYLE_ICON_TAB = 0x00000200, /**<@if OSPDEPREC @deprecated This enumeration field is deprecated because the use of the Tab control is no longer recommended. @endif */
65 FORM_STYLE_HEADER = 0x00001000, /**< The form with a header */
66 FORM_STYLE_FOOTER = 0x00002000 /**< The form with a footer */
74 * Defines the softkey.
76 * @brief <i> [Deprecated] </i>
77 * @deprecated This enumeration type is deprecated because the use of the Softkey control is no longer recommended.
83 SOFTKEY_0, /**< @if OSPDEPREC The left softkey @endif */
84 SOFTKEY_1, /**< @if OSPDEPREC The right softkey @endif */
85 SOFTKEY_COUNT // This enum value is for internal use only. Using this enum value can cause behavioral, security-related, and consistency-related issues in the application.
92 * Defines the action bars that can be attached to the %Form control.
98 FORM_ACTION_BAR_INDICATOR = 0x0001, /**< The indicator */
99 FORM_ACTION_BAR_HEADER = 0x0002, /**< The header */
100 FORM_ACTION_BAR_FOOTER = 0x0004, /**< The footer */
101 FORM_ACTION_BAR_TAB = 0x0008 /**< The tab */ // Ki-Dong,Hong.Temp
107 * @brief This class provides a container with general controls.
111 * The %Form class displays a full screen container. It can contain user-created controls and system UI components, such
112 * as an indicator area, header, and footer. The application can have multiple forms that are all added to a single Frame.
114 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_form.htm">Form</a>.
116 * The following example demonstrates how to use the %Form class.
120 *@image html ui_controls_form.png
123 * This is a simple UI application that uses a %Form.
127 // Creates an instance of Form
128 Form* pForm = new Form();
129 pForm->Construct(FORM_STYLE_NORMAL| FORM_STYLE_HEADER| FORM_STYLE_FOOTER);
131 // Gets a pointer of the frame
132 Frame *pFrame = UiApp::GetInstance()->GetAppFrame()->GetFrame();
133 pFrame->AddControl(*pForm);
134 pFrame->SetCurrentForm(*pForm);
136 // Implements MyActionEventListener
137 IActionEventListener* pListener = new MyActionEventListener();
140 Header * pHeader = GetHeader();
141 pHeader->SetTitleText(L"FormSample");
144 Footer * pFooter = GetFooter();
145 pFooter->SetStyle(FOOTER_STYLE_TAB);
146 pFooter->AddActionEventListener(*this);
148 // Calls Invalidate() to display the form
149 pForm->Invalidate(true)
153 class _OSP_EXPORT_ Form
154 : public Tizen::Ui::Container
159 * This is the default constructor for this class.
165 * This is the destructor for this class.
171 * Initializes this instance of %Form with the specified parameters.
175 * @return An error code
176 * @param[in] formStyle The form style @n
177 * Multiple form styles can be combined using bitwise OR (see Tizen::Ui::Controls::FormStyle).
178 * @exception E_SUCCESS The method is successful.
179 * @exception E_INVALID_ARG The specified input parameter is invalid @if OSPCOMPAT @b Since: @b 2.0 @endif. @n
180 * - FORM_STYLE_HEADER and FORM_STYLE_TITLE are specified at the same time. @n
181 * - FORM_STYLE_FOOTER and FORM_STYLE_SOFTKEY_0 are specified at the same time. @n
182 * - FORM_STYLE_FOOTER and FORM_STYLE_SOFTKEY_1 are specified at the same time. @n
183 * - FORM_STYLE_FOOTER and FORM_STYLE_OPTIONKEY are specified at the same time.
184 * @exception E_MAX_EXCEEDED The total number of Frames and Forms exceeds the system limitation.
185 * @exception E_SYSTEM A system error has occurred.
186 * @remarks The maximum number of Forms that an application can construct is limited by available memory.
189 result Construct(unsigned long formStyle);
193 * Initializes this instance of %Form with the specified resource ID. @n
194 * This method first attempts to find the resource file in the folder that corresponds to the current screen resolution. If it fails to find the
195 * appropriate resource file, the method tries searching in other folders. When AutoScaling is enabled, the method first searches the folder that
196 * corresponds to the current screen size category and then searches the "res/screen-size-normal/" folder.
200 * @return An error code
201 * @param[in] resourceId The resource ID describing the %Form control
202 * @exception E_SUCCESS The method is successful.
203 * @exception E_FILE_NOT_FOUND The specified file cannot be found.
204 * @exception E_INVALID_FORMAT The specified XML format is invalid.
205 * @exception E_OPERATION_FAILED The operation has failed.
207 result Construct(const Tizen::Base::String& resourceId);
210 * Initializes this instance of %Form with the form style and layout.
214 * @return An error code
215 * @param[in] layout The layout for both the portrait and landscape mode
216 * @param[in] formStyle The form style @n
217 * Multiple form styles can be combined using bitwise OR (see Tizen::Ui::Controls::FormStyle).
218 * @exception E_SUCCESS The method is successful.
219 * @exception E_INVALID_ARG A specified input parameter is invalid, or
220 * the specified layout is already bound to another container.
221 * @exception E_MAX_EXCEEDED The total number of Frames and Forms exceeds the system limitation.
222 * @exception E_SYSTEM A system error has occurred.
223 * @remarks The maximum number of Forms that an application can construct is limited by available memory. @n
224 * The children are arranged within the client area bounds of the form area by @c layout.
227 result Construct(const Tizen::Ui::Layout& layout, unsigned long formStyle);
230 * Initializes this instance of %Form with the specified parameters.
234 * @return An error code
235 * @param[in] portraitLayout The layout for the portrait mode
236 * @param[in] landscapeLayout The layout for the landscape mode
237 * @param[in] formStyle The form style @n
238 * Multiple form styles can be combined using bitwise OR (see Tizen::Ui::Controls::FormStyle).
239 * @exception E_SUCCESS The method is successful.
240 * @exception E_INVALID_ARG A specified input parameter is invalid, or
241 * the specified layout is already bound to another container.
242 * @exception E_MAX_EXCEEDED The total number of Frames and Forms exceeds the system limitation.
243 * @exception E_SYSTEM A system error has occurred.
244 * @remarks The maximum number of Forms that an application can construct is limited by available memory. @n
245 * The children are arranged within the bounds of the form area by @c layout.
248 result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, unsigned long formStyle);
253 * Adds an IOrientationEventListener instance. @n
254 * The added listener can listen to the orientation changed events that are fired when the orientation mode of the screen is changed.
258 * @param[in] listener The listener to be added
259 * @remarks The %Form control can only listen to those changes to the orientation mode that are enabled by calling SetOrientation().
260 * @see RemoveOrientationEventListener()
262 void AddOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
267 * Adds an IActionEventListener instance. @n
268 * The added listener can listen to the action events that are fired when an option key is selected.
270 * @brief <i> [Deprecated] </i>
271 * @deprecated This method is deprecated because the use of the Optionkey control is no longer recommended.
274 * @param[in] listener The listener to be added
275 * @see RemoveOptionkeyActionListener()
278 void AddOptionkeyActionListener(Tizen::Ui::IActionEventListener& listener);
283 * Adds an IActionEventListener instance. @n
284 * The added listener can listen to the action events that are fired when a softkey is selected.
286 * @brief <i> [Deprecated] </i>
287 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
290 * @param[in] softkey The style of the softkey
291 * @param[in] listener The listener to be added
292 * @see RemoveSoftkeyActionListener()
295 void AddSoftkeyActionListener(Softkey softkey, Tizen::Ui::IActionEventListener& listener);
300 * Removes an IActionEventListener instance. @n
301 * The removed listener cannot listen to the events when they are fired.
303 * @brief <i> [Deprecated] </i>
304 * @deprecated This method is deprecated because the use of the Optionkey control is no longer recommended.
307 * @param[in] listener The listener to be removed
308 * @see AddOptionkeyActionListener()
311 void RemoveOptionkeyActionListener(Tizen::Ui::IActionEventListener& listener);
315 * Removes an IOrientationEventListener instance. @n
316 * The removed listener cannot listen to the events when they are fired.
320 * @param[in] listener The listener to be removed
322 * @see AddOrientationEventListener()
324 void RemoveOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
329 * Removes an IActionEventListener instance. @n
330 * The removed listener cannot listen to the events when they are fired.
332 * @brief <i> [Deprecated] </i>
333 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
336 * @param[in] softkey The style of the softkey
337 * @param[in] listener The listener to be removed
338 * @see AddSoftkeyActionListener()
341 void RemoveSoftkeyActionListener(Softkey softkey, Tizen::Ui::IActionEventListener& listener);
346 * Gets the background color of the %Form control.
350 * @return The background color of the %Form control
352 Tizen::Graphics::Color GetBackgroundColor(void) const;
356 * Gets the bounds of the client area.
360 * @return The bounds of the client area
361 * @remarks The client area of the %Form control does not include the title, indicator, header and footer areas.
362 * header and footer areas.
365 Tizen::Graphics::Rectangle GetClientAreaBounds(void) const;
369 * Gets the style of the %Form control.
373 * @return An @c unsigned @c long value representing the style of the %Form control
375 unsigned long GetFormStyle(void) const;
379 * Gets the orientation mode of the %Form control.
383 * @return The orientation of the %Form control
385 Tizen::Ui::Orientation GetOrientation(void) const;
389 * Gets the current orientation status of the %Form control.
393 * @return The orientation status of the %Form control, @n
394 * else ORIENTATION_NONE if the %Form control is not the current form of the Frame control
396 Tizen::Ui::OrientationStatus GetOrientationStatus(void) const;
401 * Gets the action ID of the specified softkey.
403 * @brief <i> [Deprecated] </i>
404 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
407 * @return An integer value representing the action ID
408 * @param[in] softkey The softkey
411 int GetSoftkeyActionId(Softkey softkey) const;
416 * Gets the text of the specified softkey.
418 * @brief <i> [Deprecated] </i>
419 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
422 * @return The text of the softkey
423 * @param[in] softkey The softkey
426 Tizen::Base::String GetSoftkeyText(Softkey softkey) const;
431 * Gets the pointer of the Tab control if it exists.
433 * @brief <i> [Deprecated] </i>
434 * @deprecated This method is deprecated because the use of the Tab control is no longer recommended.
437 * @return A pointer to the Tab control, @n
438 * else @c null if there is no tab
439 * @remarks The retrieved pointer may be temporary. Therefore, it should not be stored after immediate use.
442 Tab* GetTab(void) const;
447 * Gets the title of the %Form control.
449 * @brief <i> [Deprecated] </i>
450 * @deprecated This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
451 * use the Header control.
454 * @return The title of the %Form control
457 Tizen::Base::String GetTitleText(void) const;
462 * Gets the horizontal alignment of the title text.
464 * @brief <i> [Deprecated] </i>
465 * @deprecated This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
466 * use the Header control.
469 * @return The horizontal alignment of the title text
470 * @remarks By default, the horizontal alignment is center aligned.
473 HorizontalAlignment GetTitleTextHorizontalAlignment(void) const;
476 * Checks whether the %Form control has an Indicator.
480 * @return @c true if the %Form control has a title, @n
483 bool HasIndicator(void) const;
488 * Checks whether the %Form control has an optionkey.
490 * @brief <i> [Deprecated] </i>
491 * @deprecated This method is deprecated because the use of the Optionkey control is no longer recommended.
494 * @return @c true if the %Form control has an optionkey, @n
498 bool HasOptionkey(void) const;
503 * Checks whether the %Form control has the specified softkey.
505 * @brief <i> [Deprecated] </i>
506 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
509 * @return @c true if the %Form control has the specified softkey, @n
511 * @param[in] softkey The required softkey
514 bool HasSoftkey(Softkey softkey) const;
519 * Checks whether the %Form control has a tab.
521 * @brief <i> [Deprecated] </i>
522 * @deprecated This method is deprecated because the use of the Tab control is no longer recommended.
525 * @return @c true if the %Form control has a tab, @n
529 bool HasTab(void) const;
534 * Checks whether the %Form control has a title.
536 * @brief <i> [Deprecated] </i>
537 * @deprecated This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
538 * use the Header control.
541 * @return @c true if the %Form control has a title, @n
545 bool HasTitle(void) const;
550 * Checks whether the softkey is enabled.
552 * @brief <i> [Deprecated] </i>
553 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
556 * @return @c true if the softkey is enabled, @n
558 * @param[in] softkey The softkey
561 bool IsSoftkeyEnabled(Softkey softkey) const;
565 * Sets the background color of the %Form control.
569 * @param[in] color The background color to set
571 void SetBackgroundColor(const Tizen::Graphics::Color& color);
575 * Sets the style of the %Form control.
579 * @param[in] formStyle The form style to set @n
580 * This parameter can be a combination of Tizen::Ui::Controls::FormStyle.
581 * @exception E_SUCCESS The method is successful @if OSPCOMPAT @b Since: @b 2.0 @endif.
582 * @exception E_INVALID_ARG A specified input parameter is invalid @if OSPCOMPAT @b Since: @b 2.0 @endif. @n
583 * - FORM_STYLE_HEADER and FORM_STYLE_TITLE are specified at the same time. @n
584 * - FORM_STYLE_FOOTER and FORM_STYLE_SOFTKEY_0 are specified at the same time. @n
585 * - FORM_STYLE_FOOTER and FORM_STYLE_SOFTKEY_1 are specified at the same time. @n
586 * - FORM_STYLE_FOOTER and FORM_STYLE_OPTIONKEY are specified at the same time. @n
587 * @remarks The specific error code can be accessed using the GetLastResult() method. @n
588 * Note that you must not change the style of %Form control that is constructed with FORM_STYLE_TEXT_TAB or FORM_STYLE_ICON_TAB style.
589 * A Form which is added to a container except Frame cannot have the style of @c FORM_STYLE_INDICATOR.
591 void SetFormStyle(unsigned long formStyle);
596 * Sets an action ID of the optionkey.
598 * @brief <i> [Deprecated] </i>
599 * @deprecated This method is deprecated because the use of the Optionkey control is no longer recommended.
602 * @param[in] actionId The action ID of this button instance
605 void SetOptionkeyActionId(int actionId);
609 * Sets the orientation of the %Form control.
613 * @param[in] orientation The orientation of the %Form control
615 void SetOrientation(Orientation orientation);
620 * Sets an action ID of each softkey.
622 * @brief <i> [Deprecated] </i>
623 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
626 * @param[in] softkey The softkey
627 * @param[in] actionId The action ID to be set
630 void SetSoftkeyActionId(Softkey softkey, int actionId);
635 * Enables or disables the specified softkey.
637 * @brief <i> [Deprecated] </i>
638 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
641 * @param[in] softkey The softkey
642 * @param[in] enable Set to @c true to enable this softkey @n
646 void SetSoftkeyEnabled(Softkey softkey, bool enable);
651 * Sets the title icon of the %Form control.
653 * @brief <i> [Deprecated] </i>
654 * @deprecated This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
655 * use the %Header control.
658 * @return An error code
659 * @param[in] pTitleBitmap The title icon to be set, @n
660 * else @c null if the title icon is removed
661 * @exception E_SUCCESS The method is successful.
662 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of a specified operation (that is, this control cannot be displayed).
663 * @exception E_SYSTEM A system error has occurred.
666 result SetTitleIcon(const Tizen::Graphics::Bitmap* pTitleBitmap);
671 * Sets the title of this %Form control.
673 * @brief <i> [Deprecated] </i>
674 * @deprecated This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
675 * use the Header control.
678 * @return An error code
679 * @param[in] title The title to be set
680 * @param[in] alignment The horizontal alignment
681 * @exception E_SUCCESS The method is successful.
682 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of a specified operation (that is, this control cannot be displayed).
683 * @exception E_SYSTEM A system error has occurred.
684 * @remarks If the size of the text exceeds the displayable area, the text slides automatically. @n
685 * Note that when the title icon is set along with the title text, the title retains the left alignment.
688 result SetTitleText(const Tizen::Base::String& title, HorizontalAlignment alignment = ALIGNMENT_CENTER);
693 * Sets the icon of the softkey.
695 * @brief <i> [Deprecated] </i>
696 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
699 * @param[in] softkey The softkey
700 * @param[in] normalBitmap The Bitmap of the normal icon
701 * @param[in] pPressedBitmap The Bitmap of the pressed icon
702 * @remarks If both the icon and text are set for a softkey at the same time, the text takes precedence over the icon.
705 void SetSoftkeyIcon(Softkey softkey, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap);
709 * Sets the text of the specified softkey.
711 * @brief <i> [Deprecated] </i>
712 * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
715 * @param[in] softkey The softkey
716 * @param[in] text The text to be set
717 * @remarks If both the icon and text are set for a softkey at the same time, the text takes precedence over the icon. @n
718 * To display text in multi-lines or to denote the end of line, use '\\n'.
721 void SetSoftkeyText(Softkey softkey, const Tizen::Base::String& text);
724 * Gets the pointer to the Footer control if it exists.
728 * @return A pointer to the Footer control, @n
729 * else @c null if there is no %Footer
730 * @remarks The retrieved pointer may be temporary. Therefore, it should not be stored after immediate use.
732 Footer* GetFooter(void) const;
736 * Gets the pointer to the Header control if it exists.
740 * @return A pointer to the Header control, @n
741 * else @c null if there is no %Header
742 * @remarks The retrieved pointer may be temporary. Therefore, it should not be
743 * stored after immediate use.
745 Header* GetHeader(void) const;
749 * Checks whether the %Form control has a Footer.
753 * @return @c true if the %Form control has a Footer, @n
756 bool HasFooter(void) const;
760 * Checks whether the %Form control has a Header.
764 * @return @c true if the %Form control has a Header, @n
767 bool HasHeader(void) const;
771 * Checks whether the Indicator control is visible.
775 * @return @c true if the Indicator control is visible, @n
778 bool IsIndicatorVisible(void) const;
782 * Checks whether the Header control is visible.
786 * @return @c true if the Header control is visible, @n
789 bool IsHeaderVisible(void) const;
793 * Checks whether the Footer control is visible.
797 * @return @c true if the Footer control is visible, @n
800 bool IsFooterVisible(void) const;
804 * Checks whether the Indicator control is translucent.
808 * @return @c true if the Indicator control is translucent, @n
811 bool IsIndicatorTranslucent(void) const;
815 * Checks whether the Header control is translucent.
819 * @return @c true if the Header control is translucent, @n
822 bool IsHeaderTranslucent(void) const;
826 * Checks whether the Footer control is translucent.
830 * @return @c true if the Footer control is translucent, @n
833 bool IsFooterTranslucent(void) const;
837 * Sets the translucency of the action bars.
841 * @return An error code
842 * @param[in] actionBars The action bars @n
843 * Multiple action bars can be combined using bitwise OR (see Tizen::Ui::Controls::FormActionBar).
844 * @param[in] translucent Set to @c to make the action bars translucent, @n
846 * @exception E_SUCCESS The method is successful.
847 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of a specified operation, or
848 * the specified action bars do not exist.
849 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
850 * @exception E_SYSTEM A system error has occurred.
851 * @remarks Modifying the translucency of the action bars causes the client area of the %Form to change. @n
852 * The translucency of multiple action bars can be modified at the same time by using logical OR for several values of FormActionBar.
853 * @remarks The method is not supported in 16-bit devices.
856 result SetActionBarsTranslucent(unsigned long actionBars, bool translucent);
860 * Sets the visibility state of the action bars.
864 * @return An error code
865 * @param[in] actionBars The action bars @n
866 * Multiple action bars can be combined using bitwise OR (see Tizen::Ui::Controls::FormActionBar).
867 * @param[in] visible Set to @c true to make the action bars visible, @n
869 * @exception E_SUCCESS The method is successful.
870 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
871 * the specified action bars does not exist.
872 * @exception E_SYSTEM A system error has occurred.
873 * @remarks Modifying the translucency of action bars causes the client area of the %Form to change. @n
874 * The visibility of multiple action bars can be modified at the same time by using logical OR for several values of FormActionBar.
877 result SetActionBarsVisible(unsigned long actionBars, bool visible);
881 * Creates and returns an overlay region of the specified position and size. @n
882 * Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
883 * The hardware capability for an overlay region is checked by using OverlayRegion::GetWidthUnit(), OverlayRegion::GetHeightUnit() and
884 * OverlayRegion::GetMaxCount().
885 * If the specified condition is not satisfied, E_INVALID_ARG exception is returned.
889 * @return An overlay region instance
890 * @param[in] rect The x and y coordinates relative to the top-left corner of the form along with the width and height
891 * @param[in] regionType The type of the overlay region
892 * @exception E_SUCCESS The method is successful.
893 * @exception E_INVALID_ARG A specified input parameter is invalid.
894 * @exception E_MAX_EXCEEDED The number of overlay regions has reached the maximum limit.
895 * @exception E_UNSUPPORTED_OPTION The specified option of the overlay region type is not supported.
896 * @exception E_SYSTEM A system error has occurred.
897 * @remarks The specific error code can be accessed using the GetLastResult() method. @n
898 * If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay region. @n
899 * In such cases, GetOverlayRegionN() returns the E_INVALID_ARG exception. To prevent this problem, the application should use the
900 * OverlayRegion::EvaluateBounds() method to get the validated bounds that can be used as the input bounds of the GetOverlayRegionN() method.
901 * @remarks Do not use OverlayRegion with OverlayPanel. If used, the E_SYSTEM exception is thrown.
903 OverlayRegion* GetOverlayRegionN(const Tizen::Graphics::Rectangle& rect, OverlayRegionType regionType);
907 * Creates and returns a graphics canvas whose bounds (position and size) are equal to the bounds of the client area of the %Form.
911 * @return The graphic canvas of the %Form control, @n
912 * else @c null if an error occurs
913 * @exception E_SUCCESS The method is successful.
914 * @exception E_RESOURCE_UNAVAILABLE The required resource is currently unavailable.
915 * @remarks The method allocates Tizen::Graphics::Canvas whose bounds are equal to that of the client area of the %Form. @n
916 * It is the responsibility of the developers to deallocate the canvas after use.
917 * @remarks The canvas is valid only if the properties of the parent control of the canvas remain unchanged. @n
918 * Therefore, delete the previously allocated canvas and create a new canvas using the GetCanvasN() method @n
919 * if the size or position of the control is changed.
920 * @remarks The specific error code can be accessed using the GetLastResult() method.
921 * @remarks The Frame and %Form instances share a single frame-buffer. @n
922 * Therefore, the custom drawing on the graphic canvas of the Frame and %Form controls appears on the screen regardless of whether the
923 * control is currently visible on the screen.
925 Tizen::Graphics::Canvas* GetClientAreaCanvasN(void) const;
928 * Translates the specified position to the client coordinate.
932 * @return The position relative to the top-left corner of the client area, @n
933 * else @c (-1,-1) if the instance is invalid
934 * @param[in] position The position relative to the top-left corner of the %Form control
935 * @see TranslateFromClientAreaPosition()
937 Tizen::Graphics::Point TranslateToClientAreaPosition(const Tizen::Graphics::Point& position) const;
940 * Translates the specified client position to the control coordinate.
944 * @return The position relative to the top-left corner of the %Form control, @n
945 * else @c (-1,-1) if the instance is invalid
946 * @param[in] clientPosition The position relative to the top-left corner of the client area
947 * @see TranslateToClientAreaPosition()
949 Tizen::Graphics::Point TranslateFromClientAreaPosition(const Tizen::Graphics::Point& clientPosition) const;
953 * Sets the %Form back event listener.
957 * @param[in] pFormBackEventListener The %Form back event listener to set
958 * @see Tizen::Ui::Controls::IFormBackEventListener.
960 void SetFormBackEventListener(IFormBackEventListener* pFormBackEventListener);
964 * Gets the data binding context.
968 * @return DataBindingContext the data binding context
969 * @exception E_SUCCESS The method is successful.
970 * @exception E_SYSTEM A system error has occurred.
971 * @remarks The specific error code can be accessed using the GetLastResult() method.
973 DataBindingContext* GetDataBindingContextN(void) const;
976 friend class _FormImpl;
979 //This method is for internal use only. Using this method can cause behavioral, security-related,
980 //and consistency-related issues in the application.
982 // This method is reserved and may change its name at any time without
987 virtual void Form_Reserved1(void) { }
990 //This method is for internal use only. Using this method can cause behavioral, security-related,
991 //and consistency-related issues in the application.
993 // This method is reserved and may change its name at any time without
998 virtual void Form_Reserved2(void) { }
1001 //This method is for internal use only. Using this method can cause behavioral, security-related,
1002 //and consistency-related issues in the application.
1004 // This method is reserved and may change its name at any time without
1009 virtual void Form_Reserved3(void) { }
1011 // Friend Class Declaration
1013 friend class UiBuilder;
1018 Form& operator =(const Form&);
1022 } } } // Tizen::Ui::Controls
1024 #endif // _FUI_CTRL_FORM_H_