2 // Open Service Platform
\r
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
\r
5 // Licensed under the Flora License, Version 1.0 (the License);
\r
6 // you may not use this file except in compliance with the License.
\r
7 // You may obtain a copy of the License at
\r
9 // http://floralicense.org/license/
\r
11 // Unless required by applicable law or agreed to in writing, software
\r
12 // distributed under the License is distributed on an AS IS BASIS,
\r
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
14 // See the License for the specific language governing permissions and
\r
15 // limitations under the License.
\r
19 * @file FUiControl.h
\r
20 * @brief This is the header file for the %Control class.
\r
22 * This header file contains the declarations of the %Control class.
\r
25 #ifndef _FUI_CONTROL_H_
\r
26 #define _FUI_CONTROL_H_
\r
28 #include <FBaseTypes.h>
\r
29 #include <FBaseString.h>
\r
30 #include <FGrpCanvas.h>
\r
31 #include <FGrpColor.h>
\r
32 #include <FGrpPoint.h>
\r
33 #include <FGrpRectangle.h>
\r
34 #include <FUiIFocusEventListener.h>
\r
35 #include <FUiIKeyEventListener.h>
\r
36 #include <FUiITouchEventListener.h>
\r
37 #include <FUiITouchModeChangedEventListener.h>
\r
38 #include <FUiIDragDropEventListener.h>
\r
39 #include <FUiIDragDropEventListenerF.h>
\r
40 #include <FUiCompositeMode.h>
\r
41 #include <FUiIPropagatedKeyEventListener.h>
\r
42 #include <FUiIPropagatedTouchEventListener.h>
\r
44 namespace Tizen { namespace Ui { namespace Animations {
\r
45 class ControlAnimator;
\r
46 class VisualElement;
\r
49 namespace Tizen { namespace Ui {
\r
51 class AccessibilityContainer;
\r
54 class TouchGestureDetector;
\r
58 * @brief This class is the abstract base class of all the UI control classes.
\r
62 * @remarks In order for a control to be displayed, it must first be bound to a window of the underlying window system. The control's window is
\r
63 * created when it (or its ancestor) is added to a valid control containment hierarchy. A containment hierarchy is valid if and
\r
64 * only if the root of the hierarchy is an instance of the Window class.
\r
66 * The %Control class is the abstract base class of all user interface elements. It encapsulates a
\r
67 * "window" of the underlying window system, and provides the infrastructure necessary for the
\r
68 * elements to respond to user inputs. The %Control class also determines how a key event is dispatched
\r
71 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/controls.htm">UI Controls</a>.
\r
74 * The following examples demonstrate how to use the %Control class.
\r
80 * pControl->SetSize(100, 100); // 100 pixels wide and 100 pixels long
\r
82 * // Sets the position
\r
83 * pControl->SetPosition(5, 5); // Control is drawn 5 pixels down and 5 pixels left from the top-left corner of its parent
\r
89 * // Gets a instance of Canvas
\r
90 * Canvas* pCanvas = pControl->GetCanvasN();
\r
92 * // Fills the canvas with white color
\r
93 * pCanvas->Clear(Tizen::Graphics::Color(255, 255, 255));
\r
95 * // Shows changes on screen
\r
96 * pControl->Invalidate(true);
\r
101 * Key and input focus
\r
104 * // Implements MyKeyEventListener
\r
105 * IKeyEventListener* pKeyListener = new MyKeyEventListener();
\r
106 * pControl->SetFocus();
\r
108 * // The added key listener should be deleted after use
\r
109 * pControl->AddKeyEventListener(*pKeyListener);
\r
113 class _OSP_EXPORT_ Control
\r
114 : public Tizen::Base::Object
\r
119 * This destructor overrides Tizen::Base::Object::~Object().
\r
123 virtual ~Control(void);
\r
126 * Adds the IFocusEventListener instance to the %Control instance. @n
\r
127 * The added listener gets notified when the control gains or loses its focus.
\r
131 * @param[in] listener The event listener to add
\r
132 * @see RemoveFocusEventListener()
\r
134 void AddFocusEventListener(IFocusEventListener& listener);
\r
137 * Adds the IKeyEventListener instance to the %Control instance. @n
\r
138 * The added listener gets notified when a key is pressed, released, or long pressed.
\r
142 * @param[in] listener The event listener to add
\r
143 * @see RemoveKeyEventListener()
\r
145 void AddKeyEventListener(IKeyEventListener& listener);
\r
148 * Adds the ITouchEventListener instance to the %Control instance. @n
\r
149 * The added listener gets notified when a touch event such as a press or a release is fired.
\r
153 * @param[in] listener The event listener to add
\r
154 * @see RemoveTouchEventListener()
\r
156 void AddTouchEventListener(ITouchEventListener& listener);
\r
159 * Adds the ITouchModeChangedEventListener instance to the %Control instance. @n
\r
160 * The added listener gets notified when the device's touch mode is changed.
\r
164 * @param[in] listener The event listener to add
\r
165 * @see RemoveTouchModeChangedEventListener()
\r
167 void AddTouchModeChangedEventListener(Tizen::Ui::ITouchModeChangedEventListener& listener);
\r
170 * Adds the IDragDropEventListener instance to the %Control instance. @n
\r
171 * The added listener gets notified when a drag or a drop happens in the control.
\r
175 * @param[in] listener The event listener to add
\r
176 * @see RemoveDragDropEventListener()
\r
178 void AddDragDropEventListener(IDragDropEventListener& listener);
\r
181 * Adds the IDragDropEventListenerF instance to the %Control instance. @n
\r
182 * The added listener gets notified when a drag or a drop happens in the control.
\r
186 * @param[in] listener The event listener to add
\r
187 * @see RemoveDragDropEventListenerF()
\r
189 void AddDragDropEventListener(IDragDropEventListenerF& listener);
\r
192 * Removes the focus listener instance. @n
\r
193 * The removed listener is not notified even when focus events are fired.
\r
197 * @param[in] listener The listener to remove
\r
198 * @see AddFocusEventListener()
\r
200 void RemoveFocusEventListener(IFocusEventListener& listener);
\r
203 * Removes the key event listener instance. @n
\r
204 * The removed listener is not notified even when key events are fired.
\r
208 * @param[in] listener The listener to remove
\r
209 * @see AddKeyEventListener()
\r
211 void RemoveKeyEventListener(IKeyEventListener& listener);
\r
214 * Removes the touch event listener instance. @n
\r
215 * The removed listener is not notified even when touch events are fired.
\r
219 * @param[in] listener The listener to remove
\r
220 * @see AddTouchEventListener()
\r
222 void RemoveTouchEventListener(ITouchEventListener& listener);
\r
225 * Removes the touch mode changed event listener instance. @n
\r
226 * The removed listener is not notified even when the touch mode changed events are fired.
\r
230 * @param[in] listener The listener to remove
\r
231 * @see AddTouchModeChangedEventListener()
\r
233 void RemoveTouchModeChangedEventListener(Tizen::Ui::ITouchModeChangedEventListener& listener);
\r
236 * Adds the IDragDropEventListener instance to the %Control instance. @n
\r
237 * The added listener gets notified when a drag or a drop happens in the control.
\r
241 * @param[in] listener The event listener to add
\r
242 * @see Tizen::Ui::IDragDropEventListener::OnTouchDragged()
\r
243 * @see Tizen::Ui::IDragDropEventListener::OnTouchDropped()
\r
244 * @see RemoveDragDropEventListener()
\r
246 void RemoveDragDropEventListener(IDragDropEventListener& listener);
\r
249 * Adds the IDragDropEventListenerF instance to the %Control instance. @n
\r
250 * The added listener gets notified when a drag or a drop happens in the control.
\r
254 * @param[in] listener The event listener to add
\r
255 * @see Tizen::Ui::IDragDropEventListenerF::OnTouchDraggedF()
\r
256 * @see Tizen::Ui::IDragDropEventListenerF::OnTouchDroppedF()
\r
257 * @see RemoveDragDropEventListenerF()
\r
259 void RemoveDragDropEventListenerF(IDragDropEventListenerF& listener);
\r
262 * Overrides this method to provide user-specific initialization code before the control is added to a container.
\r
266 * @return An error code
\r
267 * @exception E_SUCCESS The method is successful.
\r
268 * @exception E_FAILURE The method has failed.
\r
269 * @remarks This method is called when the control is about to be added to a container.
\r
270 * @remarks To cancel adding this control to the parent, return @c E_FAILURE in this method.
\r
271 * @see OnTerminating()
\r
273 virtual result OnInitializing(void);
\r
276 * Overrides this method to provide user-specific termination code.
\r
279 * @brief <i> [Compatibility] </i>
\r
284 * @compatibility This method has compatibility issues with OSP compatible applications. @n
\r
285 * For more information, see @ref CompOnTerminatingPage "here".
\r
287 * @return An error code
\r
288 * @exception E_SUCCESS The method is successful.
\r
289 * @exception E_FAILURE The method has failed.
\r
290 * @remarks This method is called right before the control is removed from the container, or Destroy() method is being called.
\r
291 * @remarks To cancel the removal or Destroy() operation, return any exception other than E_SUCCESS.
\r
292 * @see OnInitializing()
\r
294 virtual result OnTerminating(void);
\r
298 * @page CompOnTerminatingPage Compatibility for OnTerminating()
\r
299 * @section CompOnterminatingPageIssueSection Issues
\r
300 * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
\r
301 * -# OnTerminating() callback is called from child to parent.
\r
303 * @section CompOnTerminatingPageSolutionSection Resolutions
\r
304 * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
\r
305 * -# OnTerminating() callback is called from parent to child.
\r
310 * Called asynchronously when the user event that is sent by SendUserEvent() method is
\r
311 * dispatched to the control.
\r
315 * @param[in] requestId The user-defined event ID
\r
316 * @param[in] pArgs A pointer to the argument list
\r
317 * @see SendUserEvent()
\r
319 virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
\r
322 * Deallocates this instance after removing all child controls of this control
\r
326 * @exception E_SUCCESS The method is successful.
\r
327 * @remarks The control will be deleted from memory. Before it is deleted, OnTerminating() is called if it is attached to the main tree.
\r
328 * @remarks If OnTerminating() method is overrided and returns an exception, that exception will be propagated.
\r
329 * @see Tizen::Ui::Control:OnTerminating()
\r
331 result Destroy(void);
\r
334 * Checks whether the control is movable.
\r
338 * @return @c true if the control is movable, @n
\r
340 * @exception E_SUCCESS The method is successful.
\r
341 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
342 * @remarks When control is not movable SetPosition() and SetBounds() return @c E_UNSUPPORTED_OPERATION.
\r
343 * @see SetPosition()
\r
346 bool IsMovable(void) const;
\r
349 * Checks whether the control is resizable.
\r
353 * @return @c true if the control is resizable, @n
\r
355 * @exception E_SUCCESS The method is successful.
\r
356 * @remarks Even if this method returns @c true, the size can be changed internally.
\r
357 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
358 * @remarks When control is not resizable,
\r
359 * SetSize(), SetBounds(), SetMinimumSize() and SetMaximumSize() return @c E_UNSUPPORTED_OPERATION.
\r
362 * @see SetMinimumSize()
\r
363 * @see SetMaximumSize()
\r
365 bool IsResizable(void) const;
\r
368 * Gets the position and the size of the control.
\r
372 * @return An instance of the Tizen::Graphics::Rectangle that represents the position of top-left corner,
\r
373 * the width, and the height of the control
\r
374 * @remarks The shape of the control is rectangular that is defined by the top-left point,
\r
375 * and the width or height. The position
\r
376 * of the top-left point is relative to the top-left corner of the parent container.
\r
379 Tizen::Graphics::Rectangle GetBounds(void) const;
\r
382 * Gets the position and the size of the control.
\r
386 * @return An instance of the Tizen::Graphics::FloatRectangle that represents the position of top-left corner,
\r
387 * the width, and the height of the control
\r
388 * @remarks The shape of the control is rectangular that is defined by the top-left point,
\r
389 * and the width or height. The position
\r
390 * of the top-left point is relative to the top-left corner of the parent container.
\r
393 Tizen::Graphics::FloatRectangle GetBoundsF(void) const;
\r
396 * Gets the position and the size of the control.
\r
400 * @param[out] x The x position of top-left corner of the control
\r
401 * @param[out] y The y position of top-left corner of the control
\r
402 * @param[out] width The width of the rectangular region
\r
403 * @param[out] height The height of the rectangular region
\r
404 * @remarks The shape of the control is regarded as a rectangle that is defined
\r
405 * by the top-left point and the width or height.
\r
406 * The position of the top-left point is relative to the top-left corner of
\r
407 * the parent container.
\r
410 void GetBounds(int& x, int& y, int& width, int& height) const;
\r
413 * Gets the position and the size of the control.
\r
417 * @param[out] x The x position of top-left corner of the control
\r
418 * @param[out] y The y position of top-left corner of the control
\r
419 * @param[out] width The width of the rectangular region
\r
420 * @param[out] height The height of the rectangular region
\r
421 * @remarks The shape of the control is regarded as a rectangle that is defined
\r
422 * by the top-left point and the width or height.
\r
423 * The position of the top-left point is relative to the top-left corner of
\r
424 * the parent container.
\r
427 void GetBounds(float& x, float& y, float& width, float& height) const;
\r
430 * Gets the position of the control's top-left corner.
\r
434 * @return The position of the control's top-left corner
\r
435 * @remarks The position of top-left corner is relative to the top-left corner of its parent container.
\r
438 Tizen::Graphics::Point GetPosition(void) const;
\r
441 * Gets the position of the control's top-left corner.
\r
445 * @return The position of the control's top-left corner
\r
446 * @remarks The position of top-left corner is relative to the top-left corner of its parent container.
\r
449 Tizen::Graphics::FloatPoint GetPositionF(void) const;
\r
452 * Gets the position of the control's top-left corner.
\r
456 * @param[out] x The x position of the control's top-left corner
\r
457 * @param[out] y The y position of the control's top-left corner
\r
458 * @remarks The position of top-left corner is relative to the top-left corner of its parent container.
\r
461 void GetPosition(int& x, int& y) const;
\r
464 * Gets the position of the control's top-left corner.
\r
468 * @param[out] x The x position of the control's top-left corner
\r
469 * @param[out] y The y position of the control's top-left corner
\r
470 * @remarks The position of top-left corner is relative to the top-left corner of its parent container.
\r
473 void GetPosition(float& x, float& y) const;
\r
476 * Gets the size of the control.
\r
480 * @return The size of the control
\r
483 Tizen::Graphics::Dimension GetSize(void) const;
\r
486 * Gets the size of the control.
\r
490 * @return The size of the control
\r
493 Tizen::Graphics::FloatDimension GetSizeF(void) const;
\r
496 * Gets the size of the control.
\r
500 * @param[out] width The width of the control
\r
501 * @param[out] height The height of the control
\r
504 void GetSize(int& width, int& height) const;
\r
507 * Gets the size of the control.
\r
511 * @param[out] width The width of the control
\r
512 * @param[out] height The height of the control
\r
515 void GetSize(float& width, float& height) const;
\r
518 * Gets the x position of the control. @n
\r
519 * The position of control is relative to the top-left corner of its parent container.
\r
523 * @return The x position of the control
\r
525 * @see GetPosition()
\r
528 int GetX(void) const;
\r
531 * Gets the x position of the control. @n
\r
532 * The position of control is relative to the top-left corner of its parent container.
\r
536 * @return The x position of the control
\r
538 * @see GetPosition()
\r
541 float GetXF(void) const;
\r
544 * Gets the y position of the control. @n
\r
545 * The position of control is relative to the top-left corner of its parent container.
\r
549 * @return The y position of the control
\r
551 * @see GetPosition()
\r
554 int GetY(void) const;
\r
557 * Gets the y position of the control. @n
\r
558 * The position of control is relative to the top-left corner of its parent container.
\r
562 * @return The y position of the control
\r
564 * @see GetPosition()
\r
567 float GetYF(void) const;
\r
570 * Gets the width of the control.
\r
574 * @return The width of the control
\r
579 int GetWidth(void) const;
\r
582 * Gets the width of the control.
\r
586 * @return The width of the control
\r
589 * @see GetHeightF()
\r
591 float GetWidthF(void) const;
\r
594 * Gets the height of the control.
\r
598 * @return The height of the control
\r
603 int GetHeight(void) const;
\r
606 * Gets the height of the control.
\r
610 * @return The height of the control
\r
615 float GetHeightF(void) const;
\r
618 * Gets the minimum size of the control.
\r
622 * @return The minimum size of the control
\r
623 * @exception E_SUCCESS The method is successful.
\r
624 * @exception E_SYSTEM A system error has occurred.
\r
625 * @remarks The first call of the method returns the system-defined minimum size.
\r
626 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
628 Tizen::Graphics::Dimension GetMinimumSize(void) const;
\r
631 * Gets the minimum size of the control.
\r
635 * @return The minimum size of the control
\r
636 * @exception E_SUCCESS The method is successful.
\r
637 * @exception E_SYSTEM A system error has occurred.
\r
638 * @remarks The first call of the method returns the system-defined minimum size.
\r
639 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
641 Tizen::Graphics::FloatDimension GetMinimumSizeF(void) const;
\r
644 * Gets the maximum size of the control.
\r
648 * @return The maximum size of the control
\r
649 * @exception E_SUCCESS The method is successful.
\r
650 * @exception E_SYSTEM A system error has occurred.
\r
651 * @remarks The first call of the method returns the system-defined maximum size.
\r
652 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
654 Tizen::Graphics::Dimension GetMaximumSize(void) const;
\r
657 * Gets the maximum size of the control.
\r
661 * @return The maximum size of the control
\r
662 * @exception E_SUCCESS The method is successful.
\r
663 * @exception E_SYSTEM A system error has occurred.
\r
664 * @remarks The first call of the method returns the system-defined maximum size.
\r
665 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
667 Tizen::Graphics::FloatDimension GetMaximumSizeF(void) const;
\r
670 * Gets a font of the control.
\r
674 * @return The font name set in the control @n
\r
675 * else an empty string if the font is not set
\r
678 Tizen::Base::String GetFont(void) const;
\r
681 * Sets the position and size of the control.
\r
685 * @return An error code
\r
686 * @param[in] rect The new bounds of the control
\r
687 * @exception E_SUCCESS The method is successful.
\r
688 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
689 * @exception E_UNSUPPORTED_OPERATION This control is neither movable nor resizable.
\r
690 * @exception E_INVALID_ARG The specified input parameter is invalid.
\r
691 * @exception E_SYSTEM A system error has occurred.
\r
692 * @remarks Do not override this method.
\r
693 * @remarks The size of the control must be within the range defined by the minimum size and the maximum size.
\r
695 * @see IsResizable()
\r
696 * @see GetMinimumSize()
\r
697 * @see GetMaximumSize()
\r
698 * @see SetPosition()
\r
701 result SetBounds(const Tizen::Graphics::Rectangle& rect);
\r
704 * Sets the position and size of the control.
\r
708 * @return An error code
\r
709 * @param[in] rect The new bounds of the control
\r
710 * @exception E_SUCCESS The method is successful.
\r
711 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
712 * @exception E_UNSUPPORTED_OPERATION This control is neither movable nor resizable.
\r
713 * @exception E_INVALID_ARG The specified input parameter is invalid.
\r
714 * @exception E_SYSTEM A system error has occurred.
\r
715 * @remarks Do not override this method.
\r
716 * @remarks The size of the control must be within the range defined by the minimum size and the maximum size.
\r
718 * @see IsResizable()
\r
719 * @see GetMinimumSize()
\r
720 * @see GetMaximumSize()
\r
721 * @see SetPosition()
\r
724 result SetBounds(const Tizen::Graphics::FloatRectangle& rect);
\r
727 * Sets the position and size of the control. @n
\r
728 * The position is set at (x, y), and the @c width and @c height parameters contain
\r
729 * the width and height values of the object, respectively.
\r
733 * @return An error code
\r
734 * @param[in] x The new x position of the control
\r
735 * @param[in] y The new y position of the control
\r
736 * @param[in] width The new width of the control
\r
737 * @param[in] height The new height of the control
\r
738 * @exception E_SUCCESS The method is successful.
\r
739 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
740 * @exception E_UNSUPPORTED_OPERATION This control is neither movable nor resizable.
\r
741 * @exception E_INVALID_ARG A specified input parameter is invalid.
\r
742 * @exception E_SYSTEM A system error has occurred.
\r
743 * @remarks Do not override this method.
\r
744 * @remarks The size of the control must be within the range defined by the minimum size and the maximum size.
\r
746 * @see IsResizable()
\r
747 * @see GetMinimumSize()
\r
748 * @see GetMaximumSize()
\r
749 * @see SetPosition()
\r
752 result SetBounds(int x, int y, int width, int height);
\r
755 * Sets the position and size of the control. @n
\r
756 * The position is set at (x, y), and the @c width and @c height parameters contain
\r
757 * the width and height values of the object, respectively.
\r
761 * @return An error code
\r
762 * @param[in] x The new x position of the control
\r
763 * @param[in] y The new y position of the control
\r
764 * @param[in] width The new width of the control
\r
765 * @param[in] height The new height of the control
\r
766 * @exception E_SUCCESS The method is successful.
\r
767 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
768 * @exception E_UNSUPPORTED_OPERATION This control is neither movable nor resizable.
\r
769 * @exception E_INVALID_ARG A specified input parameter is invalid.
\r
770 * @exception E_SYSTEM A system error has occurred.
\r
771 * @remarks Do not override this method.
\r
772 * @remarks The size of the control must be within the range defined by the minimum size and the maximum size.
\r
774 * @see IsResizable()
\r
775 * @see GetMinimumSize()
\r
776 * @see GetMaximumSize()
\r
777 * @see SetPosition()
\r
780 result SetBounds(float x, float y, float width, float height);
\r
783 * Sets the relative position of the control.
\r
787 * @return An error code
\r
788 * @param[in] Position The new position
\r
789 * @exception E_SUCCESS The method is successful.
\r
790 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
791 * @exception E_UNSUPPORTED_OPERATION This control is not movable.
\r
792 * @exception E_SYSTEM A system error has occurred.
\r
793 * @remarks Do not override this method.
\r
794 * @remarks The position of the control are relative to the top-left corner of its parent.
\r
798 result SetPosition(const Tizen::Graphics::Point& position);
\r
801 * Sets the relative position of the control.
\r
805 * @return An error code
\r
806 * @param[in] Position The new position
\r
807 * @exception E_SUCCESS The method is successful.
\r
808 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
809 * @exception E_UNSUPPORTED_OPERATION This control is not movable.
\r
810 * @exception E_SYSTEM A system error has occurred.
\r
811 * @remarks Do not override this method.
\r
812 * @remarks The position of the control are relative to the top-left corner of its parent.
\r
816 result SetPosition(const Tizen::Graphics::FloatPoint& position);
\r
819 * Sets the position of the control.
\r
822 * @return An error code
\r
823 * @param[in] x The new x position of the control
\r
824 * @param[in] y The new y position of the control
\r
825 * @exception E_SUCCESS The method is successful.
\r
826 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
827 * @exception E_UNSUPPORTED_OPERATION This control is not movable.
\r
828 * @exception E_SYSTEM A system error has occurred.
\r
829 * @remarks Do not override this method.
\r
830 * @remarks The x,y position of the control are relative to the top-left corner of its parent.
\r
834 result SetPosition(int x, int y);
\r
837 * Sets the position of the control.
\r
840 * @return An error code
\r
841 * @param[in] x The new x position of the control
\r
842 * @param[in] y The new y position of the control
\r
843 * @exception E_SUCCESS The method is successful.
\r
844 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
845 * @exception E_UNSUPPORTED_OPERATION This control is not movable.
\r
846 * @exception E_SYSTEM A system error has occurred.
\r
847 * @remarks Do not override this method.
\r
848 * @remarks The x,y position of the control are relative to the top-left corner of its parent.
\r
852 result SetPosition(float x, float y);
\r
855 * Sets the size of the control. @n
856 * The @c width and @c height parameters contain the width and height values of the object, respectively.
\r
860 * @return An error code
\r
861 * @param[in] size The new width and height
\r
862 * @exception E_SUCCESS The method is successful.
\r
863 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
864 * @exception E_UNSUPPORTED_OPERATION This control is not resizable.
\r
865 * @exception E_INVALID_ARG The specified input parameter is invalid.
\r
866 * @exception E_SYSTEM A system error has occurred.
\r
867 * @remarks Do not override this method.
\r
868 * @remarks The size of the control must be within the range defined by the minimum size and the maximum size.
\r
869 * @see IsResizable()
\r
870 * @see GetMinimumSize()
\r
871 * @see GetMaximumSize()
\r
874 result SetSize(const Tizen::Graphics::Dimension& size);
\r
877 * Sets the size of the control.
\r
878 * The @c width and @c height parameters contain the width and height values of the object, respectively.
\r
882 * @return An error code
\r
883 * @param[in] size The new width and height
\r
884 * @exception E_SUCCESS The method is successful.
\r
885 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
886 * @exception E_UNSUPPORTED_OPERATION This control is not resizable.
\r
887 * @exception E_INVALID_ARG The specified input parameter is invalid.
\r
888 * @exception E_SYSTEM A system error has occurred.
\r
889 * @remarks Do not override this method.
\r
890 * @remarks The size of the control must be within the range defined by the minimum size and the maximum size.
\r
891 * @see IsResizable()
\r
892 * @see GetMinimumSize()
\r
893 * @see GetMaximumSize()
\r
896 result SetSize(const Tizen::Graphics::FloatDimension& size);
\r
899 * Sets the size of the control. @n
900 * The @c width and @c height parameters contain the width and height values of the object, respectively.
\r
904 * @return An error code
\r
905 * @param[in] width The new width of the control
\r
906 * @param[in] height The new height of the control
\r
907 * @exception E_SUCCESS The method is successful.
\r
908 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
909 * @exception E_UNSUPPORTED_OPERATION This control is not resizable.
\r
910 * @exception E_INVALID_ARG A specified input parameter is invalid.
\r
911 * @exception E_SYSTEM A system error has occurred.
\r
912 * @remarks Do not override this method.
\r
913 * @remarks The size of the control must be within the range defined by the minimum size and the maximum size.
\r
914 * @see IsResizable()
\r
915 * @see GetMinimumSize()
\r
916 * @see GetMaximumSize()
\r
919 result SetSize(int width, int height);
\r
922 * Sets the size of the control.
\r
923 * The @c width and @c height parameters contain the width and height values of the object, respectively.
\r
927 * @return An error code
\r
928 * @param[in] width The new width of the control
\r
929 * @param[in] height The new height of the control
\r
930 * @exception E_SUCCESS The method is successful.
\r
931 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
\r
932 * @exception E_UNSUPPORTED_OPERATION This control is not resizable.
\r
933 * @exception E_INVALID_ARG A specified input parameter is invalid.
\r
934 * @exception E_SYSTEM A system error has occurred.
\r
935 * @remarks Do not override this method.
\r
936 * @remarks The size of the control must be within the range defined by the minimum size and the maximum size.
\r
937 * @see IsResizable()
\r
938 * @see GetMinimumSize()
\r
939 * @see GetMaximumSize()
\r
942 result SetSize(float width, float height);
\r
945 * Sets the minimum size of the control.
\r
949 * @return An error code
\r
950 * @param[in] newMinDim The new minimum size of the control
\r
951 * @exception E_SUCCESS The method is successful.
\r
952 * @exception E_UNSUPPORTED_OPERATION This control is not resizable.
\r
953 * @exception E_INVALID_ARG The specified input parameter is invalid.
\r
954 * @exception E_SYSTEM A system error has occurred.
\r
955 * @remarks This method can affect the maximum size and the current size of the control. @n
\r
956 * The control needs to be redrawn to reflect the change in its size. @n
\r
957 * If the current maximum size or the control size is smaller than the new minimum size,
\r
958 * it becomes the same as the new minimum size.
\r
959 * @see IsResizable()
\r
961 result SetMinimumSize(const Tizen::Graphics::Dimension& newMinDim);
\r
964 * Sets the minimum size of the control.
\r
968 * @return An error code
\r
969 * @param[in] newMinDim The new minimum size of the control
\r
970 * @exception E_SUCCESS The method is successful.
\r
971 * @exception E_UNSUPPORTED_OPERATION This control is not resizable.
\r
972 * @exception E_INVALID_ARG The specified input parameter is invalid.
\r
973 * @exception E_SYSTEM A system error has occurred.
\r
974 * @remarks This method can affect the maximum size and the current size of the control. @n
\r
975 * The control needs to be redrawn to reflect the change in its size. @n
\r
976 * If the current maximum size or the control size is smaller than the new minimum size,
\r
977 * it becomes the same as the new minimum size.
\r
978 * @see IsResizable()
\r
980 result SetMinimumSize(const Tizen::Graphics::FloatDimension& newMinDim);
\r
983 * Sets the maximum size of the control.
\r
987 * @return An error code
\r
988 * @param[in] newMaxDim The new maximum size of the control
\r
989 * @exception E_SUCCESS The method is successful.
\r
990 * @exception E_UNSUPPORTED_OPERATION This control is not resizable.
\r
991 * @exception E_INVALID_ARG The specified input parameter is invalid.
\r
992 * @exception E_SYSTEM A system error has occurred.
\r
993 * @remarks This method can affect the minimum size and the current size of the control. @n
\r
994 * The control needs to be redrawn to reflect the change in its size. @n
\r
995 * If the current minimum size or the control size is greater than the new maximum size,
\r
996 * it becomes the same as the new maximum size.
\r
997 * @see IsResizable()
\r
999 result SetMaximumSize(const Tizen::Graphics::Dimension& newMaxDim);
\r
1002 * Sets the maximum size of the control.
\r
1006 * @return An error code
\r
1007 * @param[in] newMaxDim The new maximum size of the control
\r
1008 * @exception E_SUCCESS The method is successful.
\r
1009 * @exception E_UNSUPPORTED_OPERATION This control is not resizable.
\r
1010 * @exception E_INVALID_ARG The specified input parameter is invalid.
\r
1011 * @exception E_SYSTEM A system error has occurred.
\r
1012 * @remarks This method can affect the minimum size and the current size of the control. @n
\r
1013 * The control needs to be redrawn to reflect the change in its size. @n
\r
1014 * If the current minimum size or the control size is greater than the new maximum size,
\r
1015 * it becomes the same as the new maximum size.
\r
1016 * @see IsResizable()
\r
1018 result SetMaximumSize(const Tizen::Graphics::FloatDimension& newMaxDim);
\r
1021 * Converts the specified screen position to the position in control's coordinate system.
\r
1025 * @return The position relative to the top-left corner of the control's client-area
\r
1026 * @param[in] screenPosition The position relative to the top-left corner of the screen
\r
1027 * @see ConvertToScreenPosition()
\r
1029 Tizen::Graphics::Point ConvertToControlPosition(const Tizen::Graphics::Point& screenPosition) const;
\r
1032 * Converts the specified screen position to the position in control's coordinate system.
\r
1036 * @return The position relative to the top-left corner of the control's client-area
\r
1037 * @param[in] screenPosition The position relative to the top-left corner of the screen
\r
1038 * @see ConvertToScreenPosition()
\r
1040 Tizen::Graphics::FloatPoint ConvertToControlPosition(const Tizen::Graphics::FloatPoint& screenPosition) const;
\r
1043 * Converts the specified position in the control's coordinate system to the screen position.
\r
1047 * @return The position relative to the top-left corner of the screen
\r
1048 * @param[in] controlPosition The position relative to the top-left corner of the control's client-area
\r
1049 * @see ConvertToControlPosition()
\r
1051 Tizen::Graphics::Point ConvertToScreenPosition(const Tizen::Graphics::Point& controlPosition) const;
\r
1054 * Converts the specified position in the control's coordinate system to the screen position.
\r
1058 * @return The position relative to the top-left corner of the screen
\r
1059 * @param[in] controlPosition The position relative to the top-left corner of the control's client-area
\r
1060 * @see ConvertToControlPosition()
\r
1062 Tizen::Graphics::FloatPoint ConvertToScreenPosition(const Tizen::Graphics::FloatPoint& controlPosition) const;
\r
1065 * Sets the font of the control.
\r
1069 * @return An error code
\r
1070 * @param[in] fontName The app font name or system font name @n
\r
1071 * The app font name is retrieved using Tizen::Graphics::Font::GetFaceName(Tizen::Base::String& filepath). @n
\r
1072 * The system font name is retrieved using Tizen::Graphics::Font::GetSystemFontListN().
\r
1073 * Sets an empty string to reset.
\r
1074 * @exception E_SUCCESS The method is successful.
\r
1075 * @exception E_FILE_NOT_FOUND The specified font cannot be found or accessed.
\r
1076 * @remarks At first, the value of @c fontName is considered app font name if it matches one of the face names of the font files which are located in @b '/res/font'.
\r
1077 * If not, the value of @c fontName is considered system font name if it matches one of the retrieved values using Tizen::Graphics::Font::GetSystemFontListN().
\r
1078 * @remarks The control first attempts to find the control font. If it fails, then it searches for the application default font and the system font, in sequence.
\r
1081 result SetFont(const Tizen::Base::String& fontName);
\r
1084 * Checks whether the specified @c point is inside the control.
\r
1088 * @return @c true if the specified @c point is inside the control, @n
\r
1090 * @param[in] point The point to check
\r
1091 * @remarks The specified @c point must be defined relative to the top-left corner of the control.
\r
1093 bool Contains(const Tizen::Graphics::Point& point) const;
\r
1096 * Checks whether the specified @c point is inside the control.
\r
1100 * @return @c true if the specified @c point is inside the control, @n
\r
1102 * @param[in] point The point to check
\r
1103 * @remarks The specified @c point must be defined relative to the top-left corner of the control.
\r
1105 bool Contains(const Tizen::Graphics::FloatPoint& point) const;
\r
1108 * Checks whether the specified point is inside the control.
\r
1112 * @return @c true if the specified point is inside the control, @n
\r
1114 * @param[in] x The x position of the point to check
\r
1115 * @param[in] y The y position of the point to check
\r
1116 * @remarks The specified point must be defined relative to the top-left corner of the control.
\r
1118 bool Contains(int x, int y) const;
\r
1121 * Checks whether the specified point is inside the control.
\r
1125 * @return @c true if the specified point is inside the control, @n
\r
1127 * @param[in] x The x position of the point to check
\r
1128 * @param[in] y The y position of the point to check
\r
1129 * @remarks The specified point must be defined relative to the top-left corner of the control.
\r
1131 bool Contains(float x, float y) const;
\r
1134 * Draws child controls recursively.
\r
1137 * @brief <i> [Compatibility] </i>
\r
1142 * @compatibility This method has compatibility issues with OSP compatible applications. @n
\r
1143 * For more information, see @ref CompDrawPage "here".
\r
1145 * @return An error code
\r
1146 * @exception E_SUCCESS The method is successful.
\r
1147 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
\r
1148 * Note: This control cannot be displayed.
\r
1149 * @exception E_SYSTEM A system error has occurred.
\r
1150 * @remarks This method calls OnDraw() immediately in a synchronous way.
\r
1153 result Draw(void);
\r
1157 * @page CompDrawPage Compatibility for Draw()
\r
1158 * @section CompDrawPageIssueSection Issues
\r
1159 * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
\r
1160 * -# Draw() method draws child controls in a recursive way regardless of the visibility of the parent.
\r
1162 * @section CompDrawPageSolutionSection Resolutions
\r
1163 * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
\r
1164 * -# Draw() method does not draw child controls if the control itself is not visible.
\r
1169 * Draws the control.
\r
1173 * @param[in] recursive Set to @c true to draw child controls recursively, @n
\r
1175 * @return An error code
\r
1176 * @exception E_SUCCESS The method is successful.
\r
1177 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
\r
1178 * Note: This control cannot be displayed.
\r
1179 * @exception E_SYSTEM A system error has occurred.
\r
1180 * @remarks This method calls OnDraw() immediately in a synchronous way.
\r
1183 result Draw(bool recursive);
\r
1186 * Shows the control on the screen.
\r
1189 * @final Although this method is virtual, it should not be overridden.
\r
1190 * If overridden, it may not work as expected.
\r
1192 * @return An error code
\r
1193 * @exception E_SUCCESS The method is successful.
\r
1194 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
\r
1195 * Note: This control cannot be displayed.
\r
1196 * @exception E_SYSTEM A system error has occurred.
\r
1197 * @remarks Do not override this method.
\r
1199 virtual result Show(void);
\r
1202 * Invalidates the control.
\r
1206 * @param[in] recursive Set to @c true to invalidate child controls recursively, @n
\r
1208 * @exception E_SUCCESS The method is successful.
\r
1209 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
\r
1210 * Note: This control cannot be displayed.
\r
1211 * @exception E_SYSTEM A system error has occurred.
\r
1212 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1213 * @remarks OnDraw() is not called immediately, but called asynchronously just before the screen is updated.
\r
1214 * @see InvalidateBounds()
\r
1217 void Invalidate(bool recursive);
\r
1220 * Invalidates the control of the specified position and size.
\r
1224 * @param[in] bounds The position relative to the top-left corner of the control
\r
1225 * @exception E_SUCCESS The method is successful.
\r
1226 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
\r
1227 * Note: This control cannot be displayed.
\r
1228 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1229 * @see Invalidate()
\r
1232 void InvalidateBounds(const Tizen::Graphics::Rectangle& bounds);
\r
1235 * Invalidates the control of the specified position and size.
\r
1239 * @param[in] bounds The position relative to the top-left corner of the control
\r
1240 * @exception E_SUCCESS The method is successful.
\r
1241 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
\r
1242 * Note: This control cannot be displayed.
\r
1243 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1244 * @see Invalidate()
\r
1247 void InvalidateBounds(const Tizen::Graphics::FloatRectangle& bounds);
\r
1250 * Draws the control asynchronously.
\r
1254 * @param[in] show Set to @c true to also show the %Control, @n
\r
1256 * @remarks This method posts a draw event in the event queue. @n
\r
1257 * Drawing requested by %RequestRedraw() occurs when the draw event is fired to the control.
\r
1259 void RequestRedraw(bool show = true) const;
\r
1262 * Creates and returns a graphics canvas whose bounds (that is, position and size) are equal to those
\r
1267 * @return The graphic canvas of the control, @n
\r
1268 * else @c null if an exception occurs
\r
1269 * @exception E_SUCCESS The method is successful.
\r
1270 * @exception E_SYSTEM A system error has occurred.
\r
1271 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1272 * @remarks The method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the control.
\r
1273 * It is the developer's responsibility to deallocate the canvas after use.
\r
1274 * The canvas is guaranteed to be valid only if the properties of the parent controls of the canvas remain unchanged.
\r
1275 * Therefore, one must delete previously allocated canvas and create a new canvas using the %GetCanvasN() method
\r
1276 * if the size or position of the control is changed.
\r
1277 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1278 * @remarks The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
\r
1279 * if custom drawing is performed on the graphic canvas of Frame and Form
\r
1280 * then it will appear on the screen regardless of which control is currently visible on the screen.
\r
1281 * @see GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const
\r
1282 * @see GetCanvasN(int x, int y, int width, int height) const
\r
1285 * MyForm::OnDraw(void)
\r
1287 * result r = E_SUCCESS;
\r
1288 * Canvas* pCanvas = GetCanvasN();
\r
1289 * if (pCanvas != null)
\r
1291 * // add your drawing code here
\r
1295 * // Do not call Show(). It will be called automatically after OnDraw() callback.
\r
1300 Tizen::Graphics::Canvas* GetCanvasN(void) const;
\r
1303 * Creates and returns a graphic canvas of the control of the specified position and size.
\r
1307 * @return The graphic canvas of the control, @n
\r
1308 * else @c null if an exception occurs
\r
1309 * @param[in] bounds The bounds of the graphic canvas
\r
1310 * @exception E_SUCCESS The method is successful.
\r
1311 * @exception E_OUT_OF_RANGE The specified bounds does not intercept with the bounds of the control.
\r
1312 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1313 * @remarks Only the graphic canvas of displayable controls can be obtained.
\r
1314 * If the specified area is not inside the control,
\r
1315 * the graphics canvas of overlapped area between the control and the specified bound is returned. @n
\r
1316 * @remarks The method allocates an Tizen::Graphics::Canvas whose bounds are equal to that of the control.
\r
1317 * It is the developer's responsibility to deallocate the canvas after use.
\r
1318 * The canvas is guaranteed to be valid only if the properties of the parent controls of the canvas remain unchanged.
\r
1319 * Therefore, one must delete previously allocated canvas and create a new canvas using the %GetCanvasN() method
\r
1320 * if the size or position of the control is changed.
\r
1321 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1322 * @remarks The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
\r
1323 * if custom drawing is performed on the graphic canvas of Frame and Form
\r
1324 * then it will appear on the screen regardless of which control is currently visible on the screen.
\r
1325 * @see GetCanvasN(void) const
\r
1326 * @see GetCanvasN(int x, int y, int width, int height) const
\r
1328 Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const;
\r
1331 * Creates and returns a graphic canvas of the control of the specified position and size.
\r
1335 * @return The graphic canvas of the control, @n
\r
1336 * else @c null if an exception occurs
\r
1337 * @param[in] bounds The bounds of the graphic canvas
\r
1338 * @exception E_SUCCESS The method is successful.
\r
1339 * @exception E_OUT_OF_RANGE The specified bounds does not intercept with the bounds of the control.
\r
1340 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1341 * @remarks Only the graphic canvas of displayable controls can be obtained.
\r
1342 * If the specified area is not inside the control,
\r
1343 * the graphics canvas of overlapped area between the control and the specified bound is returned. @n
\r
1344 * @remarks The method allocates an Tizen::Graphics::Canvas whose bounds are equal to that of the control.
\r
1345 * It is the developer's responsibility to deallocate the canvas after use.
\r
1346 * The canvas is guaranteed to be valid only if the properties of the parent controls of the canvas remain unchanged.
\r
1347 * Therefore, one must delete previously allocated canvas and create a new canvas using the %GetCanvasN() method
\r
1348 * if the size or position of the control is changed.
\r
1349 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1350 * @remarks The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
\r
1351 * if custom drawing is performed on the graphic canvas of Frame and Form
\r
1352 * then it will appear on the screen regardless of which control is currently visible on the screen.
\r
1353 * @see GetCanvasN(void) const
\r
1354 * @see GetCanvasN(float x, float y, float width, float height) const
\r
1356 Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds) const;
\r
1359 * Creates and returns a graphic canvas of the specified position and size in the control.
\r
1363 * @return The graphic canvas of the control, @n
\r
1364 * else @c null if an exception occurs
\r
1365 * @param[in] x The x position relative to the top-left corner of the control
\r
1366 * @param[in] y The y position relative to the top-left corner of the control
\r
1367 * @param[in] width The width of a graphic canvas
\r
1368 * @param[in] height The height of a graphic canvas
\r
1369 * @exception E_SUCCESS The method is successful.
\r
1370 * @exception E_OUT_OF_RANGE The specified bounds do not intercept with the bounds of the control.
\r
1371 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1372 * @remarks Only the graphic canvas of displayable controls can be obtained.
\r
1373 * If the specified area is not inside the control,
\r
1374 * the graphics canvas of the overlapped area between the control and the specified bound is returned. @n
\r
1375 * @remarks The method allocates an Tizen::Graphics::Canvas whose bounds are equal to that of the control.
\r
1376 * It is the developer's responsibility to deallocate the canvas after use.
\r
1377 * The canvas is guaranteed to be valid only if properties of the parent controls of the canvas remain unchanged.
\r
1378 * Therefore, one must delete the previously allocated canvas and create a new canvas using the %GetCanvasN() method
\r
1379 * if the size or position of the control is changed.
\r
1380 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1381 * @remarks The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
\r
1382 * if custom drawing is performed on the graphic canvas of Frame and Form
\r
1383 * then it will appear on the screen regardless of which control is currently visible on the screen.
\r
1384 * @see GetCanvasN(void) const
\r
1385 * @see GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const
\r
1387 Tizen::Graphics::Canvas* GetCanvasN(int x, int y, int width, int height) const;
\r
1390 * Creates and returns a graphic canvas of the specified position and size in the control.
\r
1394 * @return The graphic canvas of the control, @n
\r
1395 * else @c null if an exception occurs
\r
1396 * @param[in] x The x position relative to the top-left corner of the control
\r
1397 * @param[in] y The y position relative to the top-left corner of the control
\r
1398 * @param[in] width The width of a graphic canvas
\r
1399 * @param[in] height The height of a graphic canvas
\r
1400 * @exception E_SUCCESS The method is successful.
\r
1401 * @exception E_OUT_OF_RANGE The specified bounds do not intercept with the bounds of the control.
\r
1402 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1403 * @remarks Only the graphic canvas of displayable controls can be obtained.
\r
1404 * If the specified area is not inside the control,
\r
1405 * the graphics canvas of the overlapped area between the control and the specified bound is returned. @n
\r
1406 * @remarks The method allocates an Tizen::Graphics::Canvas whose bounds are equal to that of the control.
\r
1407 * It is the developer's responsibility to deallocate the canvas after use.
\r
1408 * The canvas is guaranteed to be valid only if properties of the parent controls of the canvas remain unchanged.
\r
1409 * Therefore, one must delete the previously allocated canvas and create a new canvas using the %GetCanvasN() method
\r
1410 * if the size or position of the control is changed.
\r
1411 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1412 * @remarks The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
\r
1413 * if custom drawing is performed on the graphic canvas of Frame and Form
\r
1414 * then it will appear on the screen regardless of which control is currently visible on the screen.
\r
1415 * @see GetCanvasN(void) const
\r
1416 * @see GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds) const
\r
1418 Tizen::Graphics::Canvas* GetCanvasN(float x, float y, float width, float height) const;
\r
1421 * Checks whether the control is currently visible on the screen.
\r
1425 * @return @c true if the control is currently visible on the screen, @n
\r
1427 * @remarks If this method is called before the control is added to a parent, @c false is returned.
\r
1428 * @see GetShowState()
\r
1429 * @see SetShowState()
\r
1431 bool IsVisible(void) const;
\r
1434 * Gets the current show state of the control.
\r
1438 * @return The show state of the control
\r
1439 * @remarks Even if the control's state is "show", the control may not be visible.
\r
1440 * @see SetShowState()
\r
1441 * @see IsVisible()
\r
1443 bool GetShowState(void) const;
\r
1446 * Sets the show state of the control.
\r
1450 * @return An error code
\r
1451 * @param[in] state The new show state
\r
1452 * @exception E_SUCCESS The method is successful.
\r
1453 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1454 * Note: This control cannot be displayed.
\r
1455 * @exception E_SYSTEM A system error has occurred.
\r
1456 * @remarks Do not override this method.
\r
1457 * @remarks Even if this method is invoked, the control is not drawn or shown. @n
\r
1458 * To display the control, use the Invalidate() methods. @n
1459 * Once the control's show state is set to @c false,
\r
1460 * the show state needs to be set to @c true again before you invalidate the control.
\r
1461 * @see GetShowState()
\r
1462 * @see Invalidate()
\r
1464 result SetShowState(bool state);
\r
1467 * Gets the dedicated %VisualElement instance for this control.
\r
1471 * @return An instance of the VisualElement
\r
1472 * @remarks If an application developer modifies the state of the returned VisualElement
\r
1473 * and the host control is not aware of this change, then the control may behave egregiously.
\r
1474 * It is highly recommended to restore the %VisualElement state to avoid such conflicts.
\r
1476 Tizen::Ui::Animations::VisualElement* GetVisualElement(void) const;
\r
1479 * Gets the parent of the control.
\r
1483 * @return The current parent of the control
\r
1485 Container* GetParent(void) const;
\r
1488 * Gets the name of the control.
\r
1492 * @return The name of the control
\r
1494 Tizen::Base::String GetName(void) const;
\r
1497 * Sets the name of the control.
\r
1501 * @param[in] name The name of the control
\r
1503 void SetName(const Tizen::Base::String& name);
\r
1506 * Checks whether the control is focusable.
\r
1510 * @return @c true if control is focusable, @n
\r
1512 * @remarks The focus ability of the container classes like Panel is @c false by default.
\r
1514 bool IsFocusable(void) const;
\r
1517 * Sets the focus ability of the control. @n
\r
1518 * Non-Focusable controls cannot take the key focus.
\r
1522 * @return An error code
\r
1523 * @exception E_SUCCESS The method is successful.
\r
1524 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1525 * Note: The control does not permit to change its focus ability.
\r
1526 * @exception E_SYSTEM A system error has occurred.
\r
1527 * @remarks The focus ability of the container classes like Panel is @c false by default.
\r
1528 * @remarks The RadioGroup class does not render the UI.
\r
1529 * Therefore, RadioGroup::SetFocusable() returns @c E_SYSTEM.
\r
1531 result SetFocusable(bool focusable);
\r
1534 * Checks whether the control currently has the input focus.
\r
1538 * @return @c true if the control currently has the input focus, @n
\r
1540 * @remarks If this method is called before the control is added to a parent, @c false is returned.
\r
1543 bool HasFocus(void) const;
\r
1546 * Sets the focus to the control. @n
\r
1547 * This method is called if the control needs to listen to user input events such as key pressed.
\r
1551 * @return An error code
\r
1552 * @exception E_SUCCESS The method is successful.
\r
1553 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1554 * Note: This control cannot be displayed.
\r
1555 * @exception E_INVALID_CONDITION The control is not contained in, or is not the top z-order frame or form.
\r
1556 * @remarks Do not override this method.
\r
1558 result SetFocus(void);
\r
1561 * Checks whether the control is enabled.
\r
1565 * @return @c true if the control is enabled, @n
\r
1567 * @remarks If this method is called before the control is added to a parent, @c false is returned.
\r
1568 * @see SetEnabled()
\r
1570 bool IsEnabled(void) const;
\r
1573 * Enables or disables the control. @n
\r
1574 * Only an enabled control can respond to the user input. By default, the control is enabled.
\r
1578 * @return An error code
\r
1579 * @param[in] enable The new state of the object
\r
1580 * @exception E_SUCCESS The method is successful.
\r
1581 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
\r
1582 * @exception E_SYSTEM A system error has occurred.
\r
1583 * @remarks Do not override this method.
\r
1585 result SetEnabled(bool enable);
\r
1588 * Checks whether the device is in touch mode. @n
\r
1589 * When the user interacts with the device by touching it, the device is in touch mode.
\r
1593 * @return @c true if the device is in touch mode, @n
\r
1595 * @remarks This method returns @c false, for devices with QWERTY keyboard.
\r
1596 * The user can navigate the UI using directional keys.
\r
1598 bool IsInTouchMode(void) const;
\r
1601 * Enables or disables the drag operation in the %Control.
\r
1605 * @param[in] enable Set to @c true to enable the drag operation, @n
\r
1607 * @see SetDropEnabled()
\r
1609 void SetDragEnabled(bool enable);
\r
1612 * Enables or disables the drop operations in the %Control.
\r
1616 * @param[in] enable Set to @c true to enable drop operations, @n
\r
1618 * @remarks To receive drop event, control's drag property has to be enabled.
\r
1619 * @see SetDragEnabled()
\r
1621 void SetDropEnabled(bool enable);
\r
1624 * Sends a user event to the control.
\r
1628 * @param[in] requestId The user-defined event ID
\r
1629 * @param[in] pArgs A pointer to the argument list
\r
1630 * @remarks This method posts a user event in the event queue
\r
1631 * and returns immediately to support asynchronous actions of the framework.
\r
1632 * @see OnUserEventReceived()
\r
1634 void SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs) const;
\r
1637 * Stops the current UI event dispatch sequence by indicating the current input event is consumed.
\r
1639 * @brief <i> [Deprecated] </i>
\r
1640 * @deprecated This method is deprecated. Instead of using this method, use IPropagatedKeyEventListener or IPropagatedTouchEventListener to consume event. @n To propagate the event, return @c true inside the implementation of IPropagatedKeyEventListener or IPropagatedTouchEventListener.
1643 * @return An error code
\r
1644 * @exception E_SUCCESS The method is successful.
\r
1645 * @exception E_SYSTEM A system error has occurred.
\r
1646 * @remarks If this method is invoked during an UI event (key or touch) propagation sequence,
\r
1647 * the method will stop the propagation and consequently the system will not be notified of the event.@n
\r
1648 * The method will not have any effect if no UI event is being dispatched. @n
\r
1649 * It is recommended that this method is called within IKeyEventListener or
\r
1650 * ITouchEventListener to stop the event from propagating to the next step.
\r
1652 result ConsumeInputEvent(void);
\r
1655 * Gets the control animator of the current instance of %Control.
\r
1659 * @return A pointer to ControlAnimator, @n
\r
1660 * else @c null if this instance is not constructed or not added to a parent or non-animatable
\r
1662 Tizen::Ui::Animations::ControlAnimator* GetControlAnimator(void) const;
\r
1665 * Adds the gesture detector to the %Control. @n
\r
1666 * The added gesture detector receives touch events prior to %Control.
\r
1668 * @brief <i> [Deprecated] </i>
\r
1669 * @deprecated This API is deprecated.
\r
1672 * @return An error code
\r
1673 * @param[in] gestureDetector The gesture detector
\r
1674 * @exception E_SUCCESS The method is successful.
\r
1675 * @see RemoveGestureDetector()
\r
1677 result AddGestureDetector(const TouchGestureDetector& gestureDetector);
\r
1680 * Adds the gesture detector to the %Control. @n
\r
1681 * The added gesture detector receives touch events prior to %Control.
\r
1685 * @return An error code
\r
1686 * @param[in] pGestureDetector Pointer of gesture detector
\r
1687 * @exception E_SUCCESS The method is successful.
\r
1688 * @exception E_INVALID_ARG The specified @c pGestureDetector is null.
\r
1689 * @see RemoveGestureDetector()
\r
1691 result AddGestureDetector(TouchGestureDetector* pGestureDetector);
\r
1694 * Removes the gesture detector from the %Control.
\r
1696 * @brief <i> [Deprecated] </i>
\r
1697 * @deprecated This API is deprecated.
\r
1700 * @return An error code
\r
1701 * @param[in] gestureDetector The gesture detector
\r
1702 * @exception E_SUCCESS The method is successful.
\r
1703 * @see AddGestureDetector()
\r
1705 result RemoveGestureDetector(const TouchGestureDetector& gestureDetector);
\r
1708 * Removes the gesture detector from the %Control.
\r
1712 * @return An error code
\r
1713 * @param[in] pGestureDetector Pointer of gesture detector
\r
1714 * @exception E_SUCCESS The method is successful.
\r
1715 * @exception E_INVALID_ARG The specified @c pGestureDetector is null.
\r
1716 * @see AddGestureDetector()
\r
1718 result RemoveGestureDetector(TouchGestureDetector* pGestureDetector);
\r
1722 * Gets the composite mode for merging with other controls.
\r
1724 * @brief <i> [Deprecated] </i>
\r
1725 * @deprecated This method is deprecated because changing composition mode is not allowed any more.
\r
1728 * @return The composite mode
\r
1729 * @exception E_SUCCESS The method is successful.
\r
1730 * @remarks Since API version 2.1, this method only returns COMPOSITE_MODE_ALPHA_BLENDING.
\r
1731 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1734 Tizen::Ui::CompositeMode GetCompositeMode(void) const;
\r
1738 * Sets the composite mode for merging with other controls.
\r
1740 * @brief <i> [Deprecated] </i>
\r
1741 * @deprecated This method is deprecated because changing composition mode is not allowed any more.
\r
1744 * @return An error code
\r
1745 * @param[in] compositeMode The composite mode
\r
1746 * @exception E_SUCCESS The method is successful.
\r
1747 * @exception E_UNSUPPORTED_OPERATION The method is not supported.
\r
1748 * @remarks In Tizen, only @c COMPOSITE_MODE_ALPHA_BLENDING is allowed.
\r
1749 * Otherwise, this method returns @c E_UNSUPPORTED_OPERATION.
\r
1752 result SetCompositeMode(Tizen::Ui::CompositeMode compositeMode);
\r
1756 * Gets the chroma key color value that is used for the control composition.
\r
1758 * @brief <i> [Deprecated] </i>
\r
1759 * @deprecated This method is deprecated because chromakey color is not supported any more.
\r
1762 * @return The chroma key color
\r
1763 * @exception E_UNSUPPORTED_OPERATION The method is not supported.
\r
1764 * @remarks In Tizen, this method always fails and returns Tizen::Graphics::Color(0, 0, 0, 0).
\r
1765 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1768 Tizen::Graphics::Color GetChromaKeyColor(void) const;
\r
1772 * Sets the chroma key color value that is used for the control composition.
\r
1774 * @brief <i> [Deprecated] </i>
\r
1775 * @deprecated This method is deprecated because chromakey color is not supported any more.
\r
1778 * @return An error code
\r
1779 * @param[in] chromaKeyColor The chroma key color
\r
1780 * @exception E_UNSUPPORTED_OPERATION The method is not supported.
\r
1781 * @remarks In Tizen, this method always fails.
\r
1784 result SetChromaKeyColor(Tizen::Graphics::Color chromaKeyColor);
\r
1787 * Sets the bounds of the content area.
\r
1791 * @param[in] rect The bounds of the content area
\r
1792 * @see GetContentAreaBounds()
\r
1794 void SetContentAreaBounds(const Tizen::Graphics::Rectangle& rect);
\r
1797 * Sets the bounds of the content area.
\r
1801 * @param[in] rect The bounds of the content area
\r
1802 * @see GetContentAreaBoundsF()
\r
1804 void SetContentAreaBounds(const Tizen::Graphics::FloatRectangle& rect);
\r
1807 * Gets the bounds of the content area.
\r
1811 * @return The bounds of the content area
\r
1812 * @see SetContentAreaBounds()
\r
1814 Tizen::Graphics::Rectangle GetContentAreaBounds(void) const;
\r
1817 * Gets the bounds of the content area.
\r
1821 * @return The bounds of the content area
\r
1822 * @see SetContentAreaBoundsF()
1824 Tizen::Graphics::FloatRectangle GetContentAreaBoundsF(void) const;
\r
1827 * Captures the composited scene of the %Panel control.
\r
1831 * @return A Tizen::Graphics::Bitmap instance that captures the current composited scene of the Panel control, @n
\r
1832 * else @c null if an error occurs
\r
1833 * @exception E_SUCCESS The method is successful.
\r
1834 * @exception E_UNSUPPORTED_OPERATION This method is not supported.
\r
1835 * @exception E_SYSTEM A system error has occurred.
\r
1836 * @remarks The specific error code can be accessed using the GetLastResult() method.
\r
1837 * @remarks This method is not supported in the following class that is derived from Panel class:
\r
1838 * @li OverlayPanel
\r
1839 * @remarks The bounds of the %Panel control must be within the client area of the Form control to get a valid composited scene.
\r
1841 Tizen::Graphics::Bitmap* GetCapturedBitmapN(void) const;
\r
1844 * Gets the position and the size of the invalidated bounds.
\r
1848 * @return An instance of Tizen::Graphics::Rectangle that represents the position of top-left corner,
\r
1849 * the width, and the height of the invalidated bounds
\r
1851 Tizen::Graphics::Rectangle GetInvalidatedBounds(void) const;
\r
1854 * Gets the position and the size of the invalidated bounds.
\r
1858 * @return An instance of Tizen::Graphics::Rectangle that represents the position of top-left corner,
\r
1859 * the width, and the height of the invalidated bounds
\r
1861 Tizen::Graphics::FloatRectangle GetInvalidatedBoundsF(void) const;
\r
1864 * Enables or disables the multi-point touch of the %Control.
\r
1868 * @param[in] enable A Boolean flag indicating whether to enable the multi-point touch
\r
1870 * @see IsMultipointTouchEnabled()
\r
1872 void SetMultipointTouchEnabled(bool enable);
\r
1875 * Checks whether the multi-point touch is enabled.
\r
1879 * @return @c true if the multi-point touch is enabled, @n
\r
1881 * @see SetMultipointTouchEnabled()
\r
1883 bool IsMultipointTouchEnabled(void) const;
\r
1886 * Gets the accessibility container.
\r
1890 * @return The accessibility container of the control, if the control supports accessibility feature, @n
1892 * @see AccessibilityContainer::GetOwner()
\r
1894 const AccessibilityContainer* GetAccessibilityContainer(void) const;
\r
1897 * Gets the accessibility container.
\r
1901 * @return The accessibility container of the control, if the control supports accessibility feature, @n
1903 * @see AccessibilityContainer::GetOwner()
\r
1905 AccessibilityContainer* GetAccessibilityContainer(void);
\r
1908 * Sets a propagated touch event listener to the %Control instance. @n
1909 * The registered listener is notified when a touch event occurs in the control. Using the propagated touch event listener, an application can control the touch event routing path.
1913 * @param[in] pListener The event listener to which the propagated touch events are dispatched
1914 * @remarks The specified event listener should be allocated in heap memory.
\r
1915 * To unregister the event listener, pass @c null to @c pListener.
\r
1918 void SetPropagatedTouchEventListener(IPropagatedTouchEventListener* pListener);
\r
1921 * Sets a propagated key event listener to the %Control instance.
1922 * The registered listener is notified when a key event occurs in the control. Using the propagated key event listener, an application can control the key event routing path.
1926 * @param[in] pListener The event listener to which the propagated touch events are dispatched
1927 * @remarks The specified event listener should be allocated in heap memory.
\r
1928 * To unregister the event listener, pass @c null to @c pListener.
\r
1931 void SetPropagatedKeyEventListener(IPropagatedKeyEventListener* pListener);
\r
1935 * Sets the previous focus of the control.
\r
1939 * @param[in] pPreviousFocus The pointer to the previous focus of the control
1940 * @remarks Focus UI supports linear navigation of controls from top-left to bottom-right direction. This method allows for customizing the default navigation behavior.
\r
1941 * @remarks The platform will not take the ownership of @c pPreviousFocus after this call.
1942 * @see SetNextFocus()
\r
1943 * @see GetPreviousFocus()
\r
1945 void SetPreviousFocus(Control* pPreviousFocus);
\r
1948 * Sets the next focus of the control.
\r
1952 * @param[in] pNextFocus The pointer to the next focus of the control
1953 * @remarks Focus UI supports linear navigation of controls from top-left to bottom-right direction. This method allows for customizing the default navigation behavior.
\r
1954 * @remarks The platform will not take the ownership of @c pNextFocus after this call.
1955 * @see SetPreviousFocus()
\r
1956 * @see GetNextFocus()
\r
1958 void SetNextFocus(Control* pNextFocus);
\r
1961 * Gets the previous focus of the control.
1965 * @return The pointer to the previous focus of the control, @n
1966 * else @c null if the previous focus of the control is not set
\r
1967 * @see GetNextFocus()
\r
1968 * @see SetNextFocus ()
\r
1970 Control* GetPreviousFocus(void) const;
\r
1974 * Gets the next focus of the control.
1978 * @return The pointer to the next focus of the control, @n
1979 * else @c null if the next focus of the control is not set
\r
1980 * @see GetPreviousFocus()
\r
1981 * @see SetPreviousFocus ()
\r
1983 Control* GetNextFocus(void) const;
\r
1986 * Sets the touch press threshold of the Control in inch.
1990 * @param[in] distance The logical threshold to fire touch move event
1991 * @remark A touch move events will start to fire if the move distance exceeds the set allowance value.
1992 * For example, Set 0.5 if the distance is 0.5 inch.
1993 * This method is offered to control sensitivity of move events.
1995 void SetTouchPressThreshold(float distance);
1998 * Gets the touch press threshold of the Control in inch.
1999 * If the threshold has not been set, it returns the default value.
2003 * @return The threshold to fire touch move event
2005 float GetTouchPressThreshold(void) const;
\r
2009 * Sets the font of the control with the specified file name.
\r
2013 * @return An error code
\r
2014 * @param[in] fileName The file name of a font-resource located in @b ‘/res/font’, @n
2015 * else an empty string to reset
2016 * @exception E_SUCCESS The method is successful.
\r
2017 * @exception E_FILE_NOT_FOUND The specified font cannot be found or accessed.
\r
2018 * @exception E_UNSUPPORTED_FORMAT The specified font format is not supported.
\r
2019 * @see GetFontFile()
\r
2021 result SetFontFromFile(const Tizen::Base::String& fileName);
\r
2024 * Gets a font file name of the control.
\r
2028 * @return The font name set in the control, @n
2029 * else an empty string if the font is not set
\r
2030 * @see SetFontFromFile()
\r
2032 Tizen::Base::String GetFontFile(void) const;
\r
2036 * Gets the default key event listener.
\r
2038 * @brief <i> [Deprecated] </i>
\r
2039 * @deprecated This method is deprecated.
\r
2042 * @return The default key event listener @n
2043 * If no listener has been set or a system error has occurred @c null is returned.
2044 * @see SetDefaultKeyEventListener()
\r
2046 IKeyEventListener* GetDefaultkeyEventListener(void) const;
\r
2049 * Gets the default touch event listener.
\r
2051 * @brief <i> [Deprecated] </i>
\r
2052 * @deprecated This method is deprecated.
\r
2055 * @return The default touch event listener @n
2056 * If no listener has been set or a system error has occurred @c null is returned.
\r
2057 * @see SetDefaultTouchEventListener()
\r
2059 ITouchEventListener* GetDefaultTouchEventListener(void) const;
\r
2062 * Sets the default key event listener.
\r
2064 * @brief <i> [Deprecated] </i>
\r
2065 * @deprecated This method is deprecated. Instead of using this method, use the SetPropagatedKeyEventListener() method.
\r
2068 * @return An error code
\r
2069 * @param[in] pDefaultListener The default key event listener
\r
2070 * @exception E_SUCCESS The method is successful.
\r
2071 * @exception E_SYSTEM A system error has occurred.
\r
2072 * @remarks The registered listener will be notified to handle the key events
\r
2073 * after all application event listeners has been notified.
\r
2074 * @see GetDefaultkeyEventListener()
\r
2076 result SetDefaultKeyEventListener(IKeyEventListener* pDefaultListener);
\r
2079 * Sets the default touch event listener.
\r
2081 * @brief <i> [Deprecated] </i>
\r
2082 * @deprecated This method is deprecated. Instead of using this method, use the SetPropagatedTouchEventListener() method.
\r
2085 * @return An error code
\r
2086 * @param[in] pDefaultListener The default key event listener
\r
2087 * @exception E_SUCCESS The method is successful.
\r
2088 * @exception E_SYSTEM A system error has occurred.
\r
2089 * @remarks The registered listener will be notified to handle the touch events
\r
2090 * after all application event listeners has been notified.
\r
2091 * @see GetDefaultTouchEventListener()
\r
2093 result SetDefaultTouchEventListener(ITouchEventListener* pDefaultListener);
\r
2096 * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
\r
2103 * This method is for internal use only. Using this method can cause behavioral, security-related,
\r
2104 * and consistency-related issues in the application.
\r
2106 * Initializes this instance of %Control.
\r
2109 * @return An error code
\r
2110 * @exception E_SUCCESS The method is successful.
\r
2111 * @exception E_SYSTEM A system error has occurred.
\r
2113 result Construct(void);
\r
2116 * Frees the resources allocated by Construct().
\r
2120 void Dispose(void);
\r
2123 _ControlImpl* _pControlImpl;
\r
2126 // This method is for internal use only. Using this method can cause behavioral, security-related,
\r
2127 // and consistency-related issues in the application.
\r
2129 // This method is reserved and may change its name at any time without prior notice.
\r
2131 virtual void Control_Reserved1(void) {}
\r
2134 // This method is for internal use only. Using this method can cause behavioral, security-related,
\r
2135 // and consistency-related issues in the application.
\r
2137 // This method is reserved and may change its name at any time without prior notice.
\r
2139 virtual void Control_Reserved2(void) {}
\r
2142 // This method is for internal use only. Using this method can cause behavioral, security-related,
\r
2143 // and consistency-related issues in the application.
\r
2145 // This method is reserved and may change its name at any time without prior notice.
\r
2147 virtual void Control_Reserved3(void) {}
\r
2150 // This method is for internal use only. Using this method can cause behavioral, security-related,
\r
2151 // and consistency-related issues in the application.
\r
2153 // This method is reserved and may change its name at any time without prior notice.
\r
2155 virtual void Control_Reserved4(void) {}
\r
2158 // This method is for internal use only. Using this method can cause behavioral, security-related,
\r
2159 // and consistency-related issues in the application.
\r
2161 // This method is reserved and may change its name at any time without prior notice.
\r
2164 virtual void Control_Reserved5(void) {}
\r
2167 // This method is for internal use only. Using this method can cause behavioral, security-related,
\r
2168 // and consistency-related issues in the application.
\r
2170 // This method is reserved and may change its name at any time without prior notice.
\r
2172 virtual void Control_Reserved6(void) {}
\r
2176 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
\r
2178 Control(const Control& rhs);
\r
2181 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
\r
2183 Control& operator =(const Control& rhs);
\r
2186 friend class _ControlImpl;
\r
2191 #endif // _FUI_CONTROL_H_
\r
projects / platform / framework / native / uifw.git / blob