inc/FUiCtrlGroupContainer.h

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