inc/FUiCtrlGroupContainer.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                 FUiCtrlGroupContainer.h
  20 * @brief               This is the header file for the %GroupContainer class.
  21 *
  22 * This header file contains the declarations of the %GroupContainer class.
  23 */
  24 #ifndef _FUI_CTRL_GROUP_CONTAINER_H_
  25 #define _FUI_CTRL_GROUP_CONTAINER_H_
  26
  27 #include <FBaseTypes.h>
  28 #include <FUiContainer.h>
  29
  30 namespace Tizen { namespace Ui { namespace Controls
  31 {
  32 /**
  33 * @class GroupContainer
  34 * @brief   This class defines common behavior for a %GroupContainer container.
  35 *
  36 * @since 2.1
  37 *
  38 * The %GroupContainer class displays child controls in grouping look. It is a concrete implementation of the Container class.
  39 */
  40
  41 class _OSP_EXPORT_ GroupContainer
  42      : public Tizen::Ui::Container
  43 {
  44 public:
  45      /**
  46      * 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.
  47      *
  48      * @since 2.1
  49      */
  50      GroupContainer(void);
  51
  52      /**
  53      * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called when the destructor of this interface is called.
  54      *
  55      * @since   2.1
  56      */
  57      virtual ~GroupContainer(void);
  58
  59      /**
  60      * Initializes this instance of %GroupContainer with the specified parameters.
  61      *
  62      * @since 2.1
  63      *
  64      * @return      An error code
  65      * @param[in]   rect                The location and size of the %GroupContainer control as an instance of Rectangle
  66      * @param[in]   rowCount            The number of rows
  67      * @param[in]   columnCount         The number of columns
  68      * @param[in]   lineWidth           Width of the grid lines to draw
  69      * @exception   E_SUCCESS           The method is successful.
  70      * @exception   E_INVALID_ARG       A specified input parameter is invalid. @n
  71      *                                  The width or height of @c rect or @c rowCount or @c columnnCount is negative or the value of @c lineWidth is @c 0 or negative.
  72      * @exception E_OPERATION_FAILED    The operation has failed.
  73      * @remarks The available space for controls is less than the width or height of the container by the total width or height of the grid lines.
  74      */
  75      result Construct(const Tizen::Graphics::Rectangle& rect, int rowCount, int columnCount, int lineWidth = 1);
  76
  77      /**
  78      * Initializes this instance of %GroupContainer with the specified parameters.
  79      *
  80      * @since 2.1
  81      *
  82      * @return      An error code
  83      * @param[in]   rect                The location and size of the %GroupContainer control as an instance of FloatRectangle
  84      * @param[in]   rowCount            The number of rows
  85      * @param[in]   columnCount         The number of columns
  86      * @param[in]   lineWidth           Width of the grid lines to draw
  87      * @exception   E_SUCCESS           The method is successful.
  88      * @exception   E_INVALID_ARG       A specified input parameter is invalid. @n
  89      *                                  The width or height of @c rect or @c rowCount or @c columnnCount is negative or the value of @c lineWidth is @c 0 or negative.
  90      * @exception E_OPERATION_FAILED    The operation has failed.
  91      * @remarks The available space for controls is less than the width or height of the container by the total width or height of the grid lines.
  92      */
  93      result Construct(const Tizen::Graphics::FloatRectangle& rect, int rowCount, int columnCount, float lineWidth = 1.0f);
  94
  95     /**
  96      * Adds a control at the specified row and column index.
  97      *
  98      * @since 2.1
  99      *
 100      * @return      An error code
 101      * @param[in]   control                             The control to add to the container
 102      * @param[in]   rowIndex                    The row index of the cell
 103      * @param[in]   columnIndex                 The column index of the cell
 104      * @exception   E_SUCCESS                   The method is successful.
 105      * @exception   E_OUT_OF_RANGE      The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
 106      * @exception   E_INVALID_OPERATION The specified operation is not allowed
 107      * @see    Merge()
 108      * @remarks  If a control is being added to the merged cells, the row index and column index of a representative cell should be given.
 109      * @remarks  The control to add should be allocated in heap memory, and the ownership of the control is transferred to the platform.
 110      */
 111      result AddControlAt(Control& control, int rowIndex, int columnIndex);
 112
 113      /**
 114      * Gets the control at the specified cell index in the GroupContainer.
 115      *
 116      * @since 2.1
 117      *
 118      * @return          The control at the specified index of the list, @n
 119      *              else @c null if the cell index is not valid or no control is added
 120      * @param[in]       rowIndex                        The row index of the cell
 121      * @param[in]   columnIndex                 The column index of the cell
 122      * @exception       E_SUCCESS                       The method is successful.
 123      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
 124      * @exception       E_INVALID_OPERATION The specified operation is not allowed
 125      * @remarks  When you get the control from the merged cell, the row index and column index of a representative cell should be given.
 126      */
 127      const Tizen::Ui::Control* GetControlAt(int rowIndex, int columnIndex) const;
 128
 129      /**
 130      * Gets the control at the specified cell index in the GroupContainer.
 131      *
 132      * @since 2.1
 133      *
 134      * @return          The control at the specified index of the list, @n
 135      *              else @c null if the cell index is not valid or no control is added
 136      * @param[in]       rowIndex                        The row index of the cell
 137      * @param[in]       columnIndex                     The column index of the cell
 138      * @exception       E_SUCCESS                       The method is successful.
 139      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
 140      * @exception       E_INVALID_OPERATION The specified operation is not allowed
 141      * @remarks  When you get the control from the merged cells, the row index and column index of a representative cell should be given.
 142      */
 143      Tizen::Ui::Control* GetControlAt(int rowIndex, int columnIndex);
 144
 145      /**
 146      * Removes the specified control from the specified row and column index
 147      *
 148      * @since 2.1
 149      *
 150      * @return          An error code
 151      * @param[in]       rowIndex                        The row index of the control to remove
 152      * @param[in]       columnIndex                     The column index of the control to remove
 153      * @exception       E_SUCCESS                       The method is successful.
 154      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex  or @c columnIndex is greater than the number of elements or less than @c 0.
 155      * @exception   E_OPERATION_FAILED  The operation has failed.
 156      * @exception   E_OBJ_NOT_FOUND             The specified cell does not have any control.
 157      * @exception       E_INVALID_OPERATION The specified operation is not allowed
 158      * @remarks  When you remove the control from the merged cell, the row index and column index of a representative cell should be given.
 159      * @remarks                 The removed child control is deleted from the memory. Before it is removed from the container, OnTerminating() of the child control is called.
 160      * @see                      Tizen::Ui::Control::OnTerminating()
 161      */
 162      result RemoveControlAt (int rowIndex, int columnIndex);
 163
 164      /**
 165      * Sets the width of a column.
 166      *
 167      * @since 2.1
 168      *
 169      * @return          An error code
 170      * @param[in]       columnIndex                     The column index
 171      * @param[in]       width                           The new width of the column
 172      * @exception       E_SUCCESS                       The method is successful.
 173      * @exception       E_OUT_OF_RANGE          The specified @c columnIndex is greater than the number of elements or less than @c 0.
 174      * @exception   E_INVALID_ARG               The specified @c width must be greater than or equal to @c 0.
 175      *
 176      */
 177      result SetColumnWidth(int columnIndex, int width);
 178
 179      /**
 180      * Sets the width of a column.
 181      *
 182      * @since 2.1
 183      *
 184      * @return          An error code
 185      * @param[in]       columnIndex                     The column index
 186      * @param[in]       width                           The new width of the column
 187      * @exception       E_SUCCESS                       The method is successful.
 188      * @exception       E_OUT_OF_RANGE          The specified @c columnIndex is greater than the number of elements or less than @c 0.
 189      * @exception   E_INVALID_ARG               The specified @c width must be greater than or equal to @c 0.0f.
 190      *
 191      */
 192      result SetColumnWidth(int columnIndex, float width);
 193
 194      /**
 195      * Gets the width of a column.
 196      *
 197      * @since 2.1
 198      *
 199      * @return          The width of the column
 200      * @param[in]       columnIndex                     The column index
 201      * @exception       E_SUCCESS                       The method is successful.
 202      * @exception       E_OUT_OF_RANGE      The specified @c columnIndex is greater than the number of elements or less than @c 0.
 203      */
 204      int GetColumnWidth(int columnIndex) const;
 205
 206      /**
 207      * Gets the width of a column.
 208      *
 209      * @since 2.1
 210      *
 211      * @return          The width of the column
 212      * @param[in]       columnIndex                     The column index
 213      * @exception       E_SUCCESS                       The method is successful.
 214      * @exception       E_OUT_OF_RANGE      The specified @c columnIndex is greater than the number of elements or less than @c 0.
 215      */
 216      float GetColumnWidthF(int columnIndex) const;
 217
 218      /**
 219      * Sets the height of a row.
 220      *
 221      * @since 2.1
 222      *
 223      * @return          An error code
 224      * @param[in]       rowIndex                        The row index
 225      * @param[in]       height                          The new height of the row
 226      * @exception       E_SUCCESS                       The method is successful.
 227      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex is greater than the number of elements or less than @c 0.
 228      * @exception       E_INVALID_ARG           The specified @c height must be greater than or equal to @c 0.
 229      *
 230      */
 231      result SetRowHeight(int rowIndex, int height);
 232
 233      /**
 234      * Sets the height of a row.
 235      *
 236      * @since 2.1
 237      *
 238      * @return          An error code
 239      * @param[in]       rowIndex                        The row index
 240      * @param[in]       height                          The new height of the row
 241      * @exception       E_SUCCESS                       The method is successful.
 242      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex is greater than the number of elements or less than @c 0.
 243      * @exception       E_INVALID_ARG           The specified @c height must be greater than or equal to @c 0.
 244      *
 245      */
 246      result SetRowHeight(int rowIndex, float height);
 247
 248      /**
 249      * Gets the height of a row.
 250      *
 251      * @since 2.1
 252      *
 253      * @return          The height of the row
 254      * @param[in]       rowIndex                        The row index
 255      * @exception       E_SUCCESS                       The method is successful.
 256      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex is greater than the number of elements or less than @c 0.
 257      *
 258      */
 259      int GetRowHeight(int rowIndex) const;
 260
 261      /**
 262      * Gets the height of a row.
 263      *
 264      * @since 2.1
 265      *
 266      * @return          The height of the row
 267      * @param[in]       rowIndex                        The row index
 268      * @exception       E_SUCCESS                       The method is successful.
 269      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex is greater than the number of elements or less than @c 0.
 270      *
 271      */
 272      float GetRowHeightF(int rowIndex) const;
 273
 274      /**
 275      * Merges the cells for the given row and column index.
 276      *
 277      * @since 2.1
 278      *
 279      * @return          An error code
 280      * @param[in]       rowStartIndex           The start index of the row from which the merge should happen
 281      * @param[in]       columnStartIndex        The start index of the column from which the merge should happen
 282      * @param[in]       rowCount                        The number of cells to merge along the row
 283      * @param[in]       columnCount                     The number of cells to merge along the column
 284      * @exception       E_SUCCESS                       The method is successful.
 285      * @exception       E_OUT_OF_RANGE          The specified @c rowStartIndex or @c columnStartIndex is greater than the number of elements or less than @c 0
 286      * @remarks  When the cells are merged, the top-left cell will play the role of representative cell on behalf of merged cells. @n
 287      *            To manipulate the merge cell, the row index and column index of the representative cell has to be given. Merging cells with the merged cell
 288      *            is allowed, but the newly merged cell should completely contain the all cells to merge.
 289      */
 290      result Merge(int rowStartIndex, int columnStartIndex, int rowCount, int columnCount);
 291
 292      /**
 293      * Enables/disables resizing of the control in a cell
 294      *
 295      * @since 2.1
 296      *
 297      * @return          An error code
 298      * @param[in]       rowIndex                        The row index of the row in which the control should be resized
 299      * @param[in]       columnIndex                     The column index of the column in which the control should be resized
 300      * @param[in]       enable                          boolean value to enable or disable the resizing of control
 301      * @exception       E_SUCCESS                       The method is successful.
 302      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex  or @c columnIndex is greater than the number of elements or less than @c 0.
 303      *
 304      */
 305      result SetChildResizingEnabled(int rowIndex, int columnIndex, bool enable);
 306
 307      /**
 308      * Sets the margin of a cell
 309      *
 310      * @since 2.1
 311      *
 312      * @return          An error code
 313      * @param[in]       rowIndex                        The row index of the cell
 314      * @param[in]       columnIndex                     The column index of the cell
 315      * @param[in]       leftMargin                      The left margin
 316      * @param[in]       rightMargin                     The right margin
 317      * @param[in]       topMargin                       The top margin
 318      * @param[in]       bottomMargin            The bottom margin
 319      * @exception       E_SUCCESS                       The method is successful.
 320      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex  or @c columnIndex is greater than the number of elements or less than @c 0.
 321      * @exception   E_INVALID_ARG               The specified @c leftMargin or @c topMargin or @c rightMargin or @c bottomMargin must be greater than or equal to @c 0.
 322      * @remarks     The default margin value is 2.0f logical pixel.
 323      */
 324      result SetMargin(int rowIndex, int columnIndex, int leftMargin, int rightMargin, int topMargin, int bottomMargin);
 325
 326      /**
 327      * Sets the margin of a cell
 328      *
 329      * @since 2.1
 330      *
 331      * @return          An error code
 332      * @param[in]       rowIndex                        The row index of the cell
 333      * @param[in]       columnIndex                     The column index of the cell
 334      * @param[in]       leftMargin                      The left margin
 335      * @param[in]       rightMargin                     The right margin
 336      * @param[in]       topMargin                       The top margin
 337      * @param[in]       bottomMargin            The bottom margin
 338      * @exception       E_SUCCESS                       The method is successful.
 339      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex  or @c columnIndex is greater than the number of elements or less than @c 0.
 340      * @exception   E_INVALID_ARG               The specified @c leftMargin or @c topMargin or @c rightMargin or @c bottomMargin must be greater than or equal to @c 0.0f.
 341      * @remarks     The default margin value is 2.0f logical pixel.
 342      */
 343      result SetMargin(int rowIndex, int columnIndex, float leftMargin, float rightMargin, float topMargin, float bottomMargin);
 344
 345      /**
 346      * Splits the merged cells
 347      *
 348      * @since 2.1
 349      *
 350      * @return          An error code
 351      * @param[in]       rowIndex                        The row index of the representative cell of the merged cells
 352      * @param[in]       columnIndex                     The column index of the representative cell of the merged cells
 353      * @exception       E_SUCCESS                       The method is successful.
 354      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex  or @c columnIndex is greater than the number of elements or less than @c 0.
 355      * @exception       E_INVALID_ARG           The specified row and column index are not those of the representative cell of the merged cells.
 356      */
 357      result Split(int rowIndex, int columnIndex);
 358
 359      /**
 360      * Gets the bounds of specified cell
 361      *
 362      * @since 2.1
 363      *
 364      * @return          An instance of the FloatRectangle that represents the position of top-left corner,
 365      *              the width, and the height of the cell, @n else Rectangle(0, 0, -1, -1)  if an error occurs
 366      * @param[in]       rowIndex                        The row index of the cell
 367      * @param[in]       columnIndex                     The column index of the cell
 368      * @exception       E_SUCCESS                       The method is successful.
 369      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex  or @c columnIndex is greater than the number of elements or less than @c 0.
 370      */
 371      Tizen::Graphics::Rectangle GetBoundsAt(int rowIndex, int columnIndex) const;
 372
 373      /**
 374      * Gets the bounds of specified cell
 375      *
 376      * @since 2.1
 377      *
 378      * @return          An instance of the FloatRectangle that represents the position of top-left corner,
 379      *              the width, and the height of the cell, @n else Rectangle(0.0f, 0.0f, -1.0f, -1.0f)  if an error occurs
 380      * @param[in]       rowIndex                        The row index of the cell
 381      * @param[in]       columnIndex                     The column index of the cell
 382      * @exception       E_SUCCESS                       The method is successful.
 383      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex  or @c columnIndex is greater than the number of elements or less than @c 0.
 384      */
 385      Tizen::Graphics::FloatRectangle GetBoundsAtF(int rowIndex, int columnIndex) const;
 386
 387      /**
 388      * Enables/disables stretchable or shrinkable property of a column
 389      *
 390      * @since 2.1
 391      *
 392      * @return          An error code
 393      * @param[in]       columnIndex                     The column index of the cell
 394      * @param[in]       stretchable                     boolean value to set stretchable or shrinkable property
 395      * @exception       E_SUCCESS                       The method is successful.
 396      * @exception       E_OUT_OF_RANGE          The specified @c columnIndex is greater than the number of elements or less than @c 0.
 397      */
 398      result SetColumnStretchable(int columnIndex, bool stretchable);
 399
 400      /**
 401      * Checks whether the column is stretchable or shrinkable
 402      *
 403      * @since 2.1
 404      *
 405      * @return          @c true if the column is stretchable or shrinkable
 406      *                   else @c false
 407      * @param[in]       columnIndex                     The column index of the cell
 408      * @exception       E_SUCCESS                       The method is successful.
 409      * @exception       E_OUT_OF_RANGE          The specified @c columnIndex is greater than the number of elements or less than @c 0.
 410      */
 411      bool IsColumnStretchable(int columnIndex) const;
 412
 413      /**
 414      * Enables/disables stretchable or shrinkable property of a row
 415      *
 416      * @since 2.1
 417      *
 418      * @return          An error code
 419      * @param[in]       rowIndex                        The row index of the cell
 420      * @param[in]       stretchable                     boolean value to set stretchable or shrinkable property
 421      * @exception       E_SUCCESS                       The method is successful.
 422      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex is greater than the number of elements or less than @c 0.
 423      */
 424      result SetRowStretchable(int rowIndex, bool stretchable);
 425
 426      /**
 427      * Checks whether the row is stretchable or shrinkable
 428      *
 429      * @since 2.1
 430      *
 431      * @return          @c true if the row is stretchable or shrinkable
 432      *                   else @c false
 433      * @param[in]       rowIndex                        The row index of the cell
 434      * @exception       E_SUCCESS                       The method is successful.
 435      * @exception       E_OUT_OF_RANGE          The specified @c rowIndex is greater than the number of elements or less than @c 0.
 436      */
 437     bool IsRowStretchable(int rowIndex) const;
 438
 439      /**
 440      * Gets the background color of the %GroupContainer control.
 441      *
 442      * @since           2.1
 443      *
 444      * @return          The background color, @n
 445      *                  else RGBA(0, 0, 0, 0) if an error occurs
 446      */
 447      Tizen::Graphics::Color GetBackgroundColor(void) const;
 448
 449      /**
 450      * Sets the background color of the %GroupContainer control.
 451      *
 452      * @since 2.1
 453      *
 454      * @param[in]       color                   The background color
 455      */
 456      void SetBackgroundColor(const Tizen::Graphics::Color& color);
 457
 458      /**
 459      * Gets the row and column divider line color of the %GroupContainer control.
 460      *
 461      * @since           2.1
 462      *
 463      * @return          The row and column divider line color, @n
 464      *                              else RGBA(0, 0, 0, 255) if line color is not set.
 465      */
 466      Tizen::Graphics::Color GetLineColor(void) const;
 467
 468      /**
 469      * Sets the row and column divider line color of the %GroupContainer control.
 470      *
 471      * @since           2.1
 472      *
 473      * @param[in]    color              The line color
 474      */
 475      void SetLineColor(const Tizen::Graphics::Color& color);
 476
 477 protected:
 478      //
 479      // This method is for internal use only. Using this method can cause behavioral, security-related,
 480      // and consistency-related issues in the application.
 481      //
 482      // Following method is reserved and may change its name at any time without
 483      // prior notice.
 484      //
 485      // @since 2.1
 486      //
 487      virtual void GroupContainer_Reserved1(void) {}
 488
 489      //
 490      // This method is for internal use only. Using this method can cause behavioral, security-related,
 491      // and consistency-related issues in the application.
 492      //
 493      // Following method is reserved and may change its name at any time without
 494      // prior notice.
 495      //
 496      // @since 2.1
 497      //
 498      virtual void GroupContainer_Reserved2(void) {}
 499
 500      //
 501      // This method is for internal use only. Using this method can cause behavioral, security-related,
 502      // and consistency-related issues in the application.
 503      //
 504      // Following method is reserved and may change its name at any time without
 505      // prior notice.
 506      //
 507      // @since 2.1
 508      //
 509      virtual void GroupContainer_Reserved3(void) {}
 510
 511 private:
 512      friend class _GroupContainerImpl;
 513
 514      //
 515      // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 516      //
 517      // @since 2.1
 518      //
 519      GroupContainer(const GroupContainer& rhs);
 520
 521      //
 522      // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 523      //
 524      GroupContainer& operator =(const GroupContainer& rhs);
 525
 526 }; // GroupContainer
 527
 528 }}} //Tizen::Ui::Controls
 529
 530 #endif // _FUI_CTRL_GROUP_CONTAINER_H_