inc/FUiContainer.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://floralicense.org/license/
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file        FUiContainer.h
  20  * @brief       This is the header file for the %Container class.
  21  *
  22  * This header file contains the declarations of the %Container class.
  23  */
  24
  25 #ifndef _FUI_CONTAINER_H_
  26 #define _FUI_CONTAINER_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseColLinkedList.h>
  30 #include <FUiControl.h>
  31
  32 namespace Tizen { namespace Ui {
  33
  34 class Layout;
  35 class _ContainerImpl;
  36
  37 /**
  38  * @class       Container
  39  * @brief       This class is an abstract base class of all the generic containers of Controls.
  40  *
  41  * @since       2.0
  42  *
  43  * @remarks As the %Container is an abstract class, use the Tizen::Ui::Controls::Panel class or another class derived from
  44  * %Container to apply the container functionality.
  45  *
  46  * The %Container class is the abstract base class of all generic Control containers. A container is a UI element which can contain
  47  * other UI elements.
  48  *
  49  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/containers.htm">Containers</a>.
  50  *
  51
  52  *
  53  */
  54 class _OSP_EXPORT_ Container
  55         : public Control
  56 {
  57
  58 public:
  59         /**
  60          * This destructor overrides Tizen::Base::Object::~Object().
  61          *
  62          * @since       2.0
  63          */
  64         virtual ~Container(void) = 0;
  65
  66 public:
  67         /**
  68          * Adds the control at the end of the list maintained by the container.
  69          *
  70          * @since                       2.0
  71          *
  72          * @return              An error code
  73          * @param[in]   control         The control to be added to the container
  74          * @exception   E_SUCCESS       The method is successful.
  75          * @exception   E_INVALID_ARG   The specified input parameter is invalid. @n
  76          *                              The specified @c control is an instance of Window, or this control's parent container.
  77          * @exception   E_MAX_EXCEEDED  The number of child controls has exceeded the maximum limit.
  78          * @exception   E_SYSTEM        A system error has occurred.
  79          * @remarks             When the control is added, it is placed at the top of the drawing stack maintained by the container.@n
  80          *              This means the last control added is drawn last
  81          * @remarks             A control becomes displayable only after it has been added to a displayable container. Some methods may not work normally if the methods
  82          *                              of the control are called before adding the control to a container. After the control is added to a %Container, the OnInitializing()
  83          *                              method of the control are called before adding the control to a container. After the control is added to a %Container, the
  84          *                              OnInitializing() method of the control is invoked for the initialization of the control such as creating and adding child controls.
  85          * @see                 Tizen::Ui::Control::OnInitializing()
  86          * @see                 Tizen::Ui::Control::OnTerminating()
  87          * @code
  88          *      {
  89          *              // Uses Panel instead of Container, because Container is an abstract class.
  90          *              Panel* pPanel = new Panel();
  91          *              pPanel->Construct(Rectangle(100, 250, 300, 300));
  92          *
  93          *              Form* pForm = new Form();
  94          *              pForm->Construct(FORM_STYLE_NORMAL|FORM_STYLE_TITLE|FORM_STYLE_INDICATOR);
  95          *              pForm->AddControl(*pPanel);
  96          *
  97          *              //...
  98          *              pForm->Invalidate(true);
  99          *              //...
 100          *      }
 101          * @endcode
 102          */
 103         result AddControl(const Control& control);
 104
 105         /**
 106          * Before the system calls OnDraw() method to allow the user to do custom drawing, this method is called to clear the canvas. The user can override this method to change this default behavior.
 107          *
 108          * @since 2.0
 109          *
 110          * @see         GetCanvasN()
 111          */
 112         virtual void OnClearBackground(void);
 113
 114         /**
 115          * Called when the container needs to draw itself. @n
 116          * Users can override this method to display user-specific drawings. @n
 117          * This method is called after the container has drawn itself, but just before the container draws its child controls.
 118          *
 119          * @if OSPCOMPAT
 120          * @brief <i> [Compatibility] </i>
 121          * @endif
 122          * @since                              2.0
 123          *
 124          * @if OSPCOMPAT
 125          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 126          *                       For more information, see @ref CompOnDrawPage "here".
 127          * @endif
 128          *
 129          * @return                  An error code
 130          * @exception    E_SUCCESS        The method is successful.
 131          * @exception    E_SYSTEM         A system error has occurred.
 132          */
 133         virtual result OnDraw(void);
 134
 135         /**
 136          * @if OSPCOMPAT
 137          * @page               CompOnDrawPage        Compatibility for OnDraw()
 138          * @section            CompOnDrawPage IssueSection          Issues
 139          * Implementing this method in OSP compatible applications has the following issues:   @n
 140          * -# The platform draws the control by calling the parent's OnDraw() callback before invoking the control's OnDraw() callback. So, the users can't control the control's drawing behavior by overriding the OnDraw() callback.
 141          *
 142          * @section            CompOnDrawPage SolutionSection               Resolutions
 143          * This issue has been resolved in Tizen.  @n
 144          * -# The platform does not call the parent's OnDraw() callback before invoking the control's OnDraw() callback. Therefore, you needs to call   the parent container's OnDraw() callback in the OnDraw() callback if you override this method.
 145          * @endif
 146          */
 147
 148         /**
 149          * Called to notify that the control's show state is changing.
 150          *
 151          * @since       2.0
 152          *
 153          * @param[in]   showState  The new show state of the control
 154          * @see         Osp::Ui::Control::SetShowState()
 155          */
 156         virtual void OnShowStateChanging(bool showState);
 157
 158         /**
 159          * Called to notify that the control's show state is changed.
 160          *
 161          * @since       2.0
 162          *
 163          * @param[in]   showState  The new show state of the control
 164          * @see         Tizen::Ui::Control::SetShowState()
 165          */
 166         virtual void OnShowStateChanged(bool showState);
 167
 168         /**
 169          * Called to notify that the bounds of the control is changing.
 170          *
 171          * @since       2.0
 172          *
 173          * @return      An error code
 174          * @param[in]   oldRect  The old position and size values of the control
 175          * @param[in]   newRect  The new position and size values of the control
 176          * @remarks     If the method returns an exception, the resulting exception
 177          *              is propagated and the control's size is unchanged.@n
 178          *              Provide control specific exceptions.
 179          * @see         Tizen::Ui::Control::SetBounds()
 180          * @see         Tizen::Ui::Control::SetSize()
 181          */
 182         virtual result OnBoundsChanging(const Tizen::Graphics::Rectangle& oldRect, const Tizen::Graphics::Rectangle& newRect);
 183
 184         /**
 185          * Called to notify that the bounds of the control is changed.
 186          *
 187          * @since       2.0
 188          *
 189          * @return      An error code
 190          * @param[in]   oldRect  The old position and size values of the control
 191          * @param[in]   newRect  The new position and size values of the control
 192          * @see         Tizen::Ui::Control::SetBounds()
 193          * @see         Tizen::Ui::Control::SetSize()
 194          */
 195         virtual void OnBoundsChanged(const Tizen::Graphics::Rectangle& oldRect, const Tizen::Graphics::Rectangle& newRect);
 196
 197         /**
 198          * Overrides this method to indicate that the specified @c width and @c height
 199          * can be supported or a new @c width and @c height should be applied instead
 200          * of the specified values.
 201          *
 202          * @since           2.0
 203          *
 204          * @return          A Boolean flag that indicates whether the specified @c width
 205          *                  and @ height are supported.
 206          * @param[in, out]  evaluatedSize  The width and the height that need to be evaluated.
 207          */
 208         virtual void OnEvaluateSize(Tizen::Graphics::Dimension& evaluatedSize);
 209
 210         /**
 211          * Removes the specified control from the container.
 212          *
 213          * @since                       2.0
 214          *
 215          * @return              An error code
 216          * @param[in]   control                 The child control to be removed
 217          * @exception   E_SUCCESS               The method is successful.
 218          * @exception   E_OBJ_NOT_FOUND         The specified instance is not found within the indicated range (that is, the @c control is not found).
 219          * @exception   E_SYSTEM                A system error has occurred.
 220          * @remarks             The removed child control is deleted from the memory. Before deletion, OnTerminating() of the child control is called.
 221          * @see                 Tizen::Ui::Control::OnTerminating()
 222          */
 223         result RemoveControl(const Control& control);
 224
 225         /**
 226          * Removes the specified control from the container.
 227          *
 228          * @since                       2.0
 229          *
 230          * @return              An error code
 231          * @param[in]   index                   The index of the control to be removed
 232          * @exception   E_SUCCESS                       The method is successful.
 233          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 234          * @exception   E_SYSTEM                A system error has occurred.
 235          * @remarks             The removed child control is deleted from the memory. Before deletion, OnTerminating() of the child control is called.
 236          * @see                 Tizen::Ui::Control::OnTerminating()
 237          */
 238         result RemoveControl(int index);
 239
 240         /**
 241          * Removes all the controls from the container.
 242          *
 243          * @since                       2.0
 244          *
 245          * @remarks             The removed child controls are deleted from the memory. Before deletion, OnTerminating() of the child control is called.
 246          * @see                         Tizen::Ui::Control::OnTerminating()
 247          */
 248         void RemoveAllControls(void);
 249
 250         /**
 251          * Gets the control at the specified index of the list that is kept by the container.
 252          *
 253          * @since                       2.0
 254          *
 255          * @return              The control at the specified index of the list, @n
 256          *              else @c null if the index is not valid
 257          * @param[in]   index   The index of the control
 258          */
 259         Control* GetControl(int index) const;
 260
 261         /**
 262          * Gets the control with the specified name. @n
 263          * If there are multiple matches of the name, the first match is returned.
 264          *
 265          * @if OSPCOMPAT
 266          * @brief <i> [Compatibility] </i>
 267          * @endif
 268          * @since                       2.0
 269          *
 270          * @if OSPCOMPAT
 271          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 272          *                       For more information, see @ref CompGetControlPage "here".
 273          * @endif
 274          *
 275          * @return              The control having the specified name, @n
 276          *                              else @c null if the name is not valid
 277          * @param[in]   name            The name of the control
 278          * @param[in]   recursive       Set to @c true to find a match recursively, @n
 279          *                                                      else @c false
 280          */
 281         Control* GetControl(const Tizen::Base::String& name, bool recursive = false) const;
 282
 283         /**
 284          * @if OSPCOMPAT
 285          * @page               CompGetControlPage        Compatibility for GetControl()
 286          * @section            CompGetControlPage IssueSection          Issues
 287          * Implementing this method in OSP compatible applications has the following issues:   @n
 288          * -# GetControl() method searches for itself first and then child controls in OSP, whereas only @n
 289          * child controls are searched for from Tizen.
 290          *
 291          * @section            CompGetControlPage SolutionSection               Resolutions
 292          * This issue has been resolved in Tizen.  @n
 293          * @endif
 294          */
 295
 296         /**
 297          * Gets the number of the controls in the container.
 298          *
 299          * @since                       2.0
 300          *
 301          * @return              The number of controls in the container
 302          */
 303         int GetControlCount(void) const;
 304
 305         /**
 306          * Gets a list of the controls of the container.
 307          *
 308          * @since               2.0
 309          *
 310          * @return              The list of the controls of the container
 311          */
 312         Tizen::Base::Collection::IList* GetControls(void) const;
 313
 314         /**
 315          * Gets the portrait layout of the container.
 316          *
 317          * @since                       2.0
 318          *
 319          * @return              The portrait layout of the container, @n
 320          *                              else @c null if the layout does not exist
 321          * @exception   E_SUCCESS               The method is successful.
 322          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 323          * @remarks             The returned layout can be @c null, if it is not set.
 324          */
 325         Layout* GetPortraitLayoutN(void) const;
 326
 327         /**
 328          * Gets the landscape layout of the container.
 329          *
 330          * @since                       2.0
 331          *
 332          * @return              The landscape layout of the container, @n
 333          *                              else @c null if the layout does not exist
 334          * @exception   E_SUCCESS               The method is successful.
 335          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 336          * @remarks             The returned layout can be @c null, if it is not set.
 337          */
 338         Layout* GetLandscapeLayoutN(void) const;
 339
 340         /**
 341          * Gets the layout of the current orientation.
 342          *
 343          * @since                       2.0
 344          *
 345          * @return              The layout of the current orientation, @n
 346          *                              else @c null if the layout does not exist
 347          * @exception   E_SUCCESS               The method is successful.
 348          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 349          * @remarks             The returned layout can be @c null, if it is not set.
 350          */
 351         Layout* GetLayoutN(void) const;
 352
 353         /**
 354          * Checks whether the specified control is a child or descendant of the container.
 355          *
 356          * @since                               2.0
 357          *
 358          * @return      @c true if the specified control is within the containment hierarchy of the container, @n
 359          *              else @c false
 360          * @param[in]   control         The control
 361          */
 362         bool IsAncestorOf(const Control& control) const;
 363
 364         /**
 365          * Sets whether the specified child control must always be above other children.
 366          *
 367          * @since        2.0
 368          *
 369          * @return       An error code
 370          * @param[in]    control          The child control
 371          * @param[in]    alwaysOnTop      The Boolean value indicating that @c control
 372          *                                must always be on the top
 373          * @exception    E_SUCCESS        The method is successful.
 374          * @exception    E_INVALID_ARG    A specified input parameter is invalid.@n
 375          *                                The specified control is not a child of this
 376          *                                container.
 377          * @remarks      If multiple child control are set as "always on top", then
 378          *               their relative order is not specified. If the specified child
 379          *               control is a container, then all its children inherit this
 380          *               property and they are "always on top" of other controls.@n
 381          *               If the method is called on a child control with a @c false
 382          *               value, then it's state becomes normal. The relative order
 383          *               of child controls in normal state is not specified.
 384          * @see          IsControlAlwaysOnTop()
 385          */
 386         result SetControlAlwaysOnTop(Tizen::Ui::Control& control, bool alwaysOnTop);
 387
 388         /**
 389          * Sets whether the specified child control must always be below other children.
 390          *
 391          * @since        2.0
 392          *
 393          * @return       An error code
 394          * @param[in]    control          The child control
 395          * @param[in]    alwaysAtBottom   The Boolean value indicating that @c control
 396          *                                must always be at the bottom.
 397          * @exception    E_SUCCESS        The method is successful.
 398          * @exception    E_INVALID_ARG    A specified input parameter is invalid.@n
 399          *                                The specified control is not a child of this
 400          *                                container.
 401          * @remarks      If multiple child control are set as "always at bottom", then
 402          *               their relative order is not specified. If the specified child
 403          *               control is a container, then all its children inherit this
 404          *               property and they become "always at bottom" as well.@n
 405          *               If the method is called on a child control with a @c false
 406          *               value, then it's state becomes normal. The relative order
 407          *               of child controls in normal state is not specified.
 408          * @see          IsControlAlwaysAtBottom()
 409          */
 410         result SetControlAlwaysAtBottom(Tizen::Ui::Control& control, bool alwaysAtBottom);
 411
 412         /**
 413          * Checks whether the specified child control is always at the bottom of
 414          * the drawing stack.
 415          *
 416          * @since       2.0
 417          *
 418          * @return       @c true if the specified child control is set as always at the bottom, @n
 419          *                 else @c false
 420          * @param[in]    control          The child control
 421          * @exception    E_SUCCESS        The method is successful.
 422          * @exception    E_INVALID_ARG    A specified input parameter is invalid.@n
 423          *                                The specified control is not a child of this
 424          *                                container.
 425          * @remarks      The specific error code can be accessed using the GetLastResult()
 426          *               method.
 427          * @see          SetControlAlwaysAtBottom()
 428          */
 429         bool IsControlAlwaysAtBottom(const Tizen::Ui::Control& control) const;
 430
 431         /**
 432          * Checks whether the specified child control is always on the top of
 433          * the drawing stack.
 434          *
 435          * @since        2.0
 436          *
 437          * @return       @c true if the specified child control is set as always on the top, @n
 438          *               else @c false
 439          * @param[in]    control          The child control
 440          * @exception    E_SUCCESS        The method is successful.
 441          * @exception    E_INVALID_ARG    A specified input parameter is invalid. @n
 442          *                                The specified control is not a child of this
 443          *                                container.
 444          * @remarks      The specific error code can be accessed using the GetLastResult()
 445          *               method.
 446          * @see          SetControlAlwaysOnTop()
 447          */
 448         bool IsControlAlwaysOnTop(const Tizen::Ui::Control& control) const;
 449
 450 protected:
 451         /**
 452          * 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.
 453          *
 454          * @since       2.0
 455          */
 456         Container(void);
 457
 458         /**
 459          * Initializes this instance of %Container.
 460          *
 461          * @since                       2.0
 462          *
 463          * @return              An error code
 464          * @exception   E_SUCCESS                       The method is successful.
 465          * @exception   E_SYSTEM                        A system error has occurred.
 466          */
 467         result Construct(void);
 468
 469         /**
 470          * Initializes this instance of %Container.
 471          *
 472          * @since 2.0
 473          *
 474          * @return      An error code
 475          * @param[in]   rect                                      The rectangle bounds to be set
 476          * @param[in]   resizable                                Set to @c true to make the container resizable, @n
 477          *                                  else @c false
 478          * @param[in]   movable                                          Set to @c true to make the container movable, @n
 479          *                                  else @c false
 480          * @exception   E_SUCCESS           The method is successful.
 481          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 482          * @remarks     This method must be called from the derived classes's construct methods.
 483          * @remarks     If the @c resizable is @c false, IsResizable() returns @c false.
 484          * @see IsResizable()
 485         */
 486         result Construct(const Tizen::Graphics::Rectangle& rect, bool resizable = true, bool movable = true);
 487
 488         /**
 489          * Initializes this instance of %Container with the specified layout and rectangular region.
 490          *
 491          * @since 2.0
 492          *
 493          * @return                  An error code
 494          * @param[in]   layout                                   The layout for both the portrait and landscape mode
 495          * @param[in]   rect                                      The location and size of the %Container
 496          * @param[in]   resizable                                Set to @c true to make the container resizable, @n
 497          *                                  else @c false
 498          * @param[in]   movable                                          Set to @c true to make the container movable, @n
 499          *                                  else @c false
 500          * @exception   E_SUCCESS                The method is successful.
 501          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 502          * @remarks     This method must be called from the derived classes's construct methods.
 503          * @remarks     If the @c resizable is @c false, IsResizable() returns @c false.
 504          * @see IsResizable()
 505          * @see Tizen::Ui::Layout
 506          * @see Tizen::Ui::Container::GetLayoutN()
 507         */
 508         result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::Rectangle& rect, bool resizable = true, bool movable = true);
 509
 510         /**
 511          * Initializes this instance of %Container with the specified layouts and rectangular region.
 512          *
 513          * @since 2.0
 514          *
 515          * @return                  An error code
 516          * @param[in]   portraitLayout              The layout for the portrait mode
 517          * @param[in]   landscapeLayout           The layout for the landscape mode
 518          * @param[in]   rect                                      The location and size of the %Container
 519          * @param[in]   resizable                                Set to @c true to make the container resizable, @n
 520          *                                  else @c false
 521          * @param[in]   movable                                          Set to @c true to make the container movable, @n
 522          *                                  else @c false
 523          * @exception   E_SUCCESS                The method is successful.
 524          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 525          * @remarks     If the @c resizable is @c false, IsResizable() returns @c false.
 526          * @see IsResizable()
 527          * @see Tizen::Ui::Layout
 528          * @see Tizen::Ui::Layout
 529          * @see Tizen::Ui::Container::GetLayoutN()
 530          * @see Tizen::Ui::Container::GetPortraitLayoutN()
 531          * @see Tizen::Ui::Container::GetLandscapeLayoutN()
 532         */
 533         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::Rectangle& rect, bool resizable = true, bool movable = true);
 534
 535         /**
 536          * Gets the index of the specified control.
 537          *
 538          * @since                       2.0
 539          * @return              An error code
 540          * @param[in]   control                 The control
 541          * @param[out]  index                   The index of the control
 542          * @exception   E_SUCCESS                       The method is successful.
 543          * @exception   E_OBJ_NOT_FOUND         The specified instance of Control is not found.
 544          * @see                 SetControlAt()
 545          *
 546          */
 547         result GetControlAt(const Control& control, int& index) const;
 548
 549         /**
 550          * Sets the control at the specified index.
 551          *
 552          * @since                       2.0
 553          *
 554          * @return              An error code
 555          * @param[in]   control         The control
 556          * @param[in]   index           The index
 557          * @exception   E_SUCCESS       The method is successful.
 558          * @exception   E_OUT_OF_RANGE  The specified @c index is out of range.
 559          * @exception   E_SYSTEM        A system error has occurred.
 560          * @remarks         The @c control must be first added to this container. @n
 561          *                              Call the Invalidate() method after this, to apply the change to be shown.
 562          * @see         Invalidate(), GetControlAt()
 563          *
 564          */
 565         result SetControlAt(const Control& control, int index);
 566
 567 private:
 568         //
 569         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 570         //
 571         Container(const Container& rhs);
 572
 573         //
 574         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 575         //
 576         Container& operator =(const Container& rhs);
 577
 578 protected:
 579         friend class _ContainerImpl;
 580
 581         //
 582         // This method is for internal use only.
 583         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 584         //
 585         // This method is reserved and may change its name at any time without prior notice.
 586         //
 587         virtual void Container_Reserved1(void) {}
 588
 589         //
 590         // This method is for internal use only.
 591         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 592         //
 593         // This method is reserved and may change its name at any time without prior notice.
 594         //
 595         virtual void Container_Reserved2(void) {}
 596
 597         //
 598         // This method is for internal use only.
 599         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 600         //
 601         // This method is reserved and may change its name at any time without prior notice.
 602         //
 603         virtual void Container_Reserved3(void) {}
 604
 605         //
 606         // This method is for internal use only.
 607         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 608         //
 609         // This method is reserved and may change its name at any time without prior notice.
 610         //
 611         virtual void Container_Reserved4(void) {}
 612
 613         //
 614         // This method is for internal use only.
 615         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 616         //
 617         // This method is reserved and may change its name at any time without prior notice.
 618         //
 619         virtual void Container_Reserved5(void) {}
 620
 621 }; // Container
 622
 623 }}  //Tizen::Ui
 624
 625 #endif //_FUI_CONTAINER_H_