inc/FUiGridLayout.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                FUiGridLayout.h
  20  * @brief               This is the header file for the %GridLayout class.
  21  *
  22  * This header file contains the declarations of the %GridLayout class.
  23  */
  24
  25 #ifndef _FUI_GRID_LAYOUT_H_
  26 #define _FUI_GRID_LAYOUT_H_
  27
  28 #include <FUiLayout.h>
  29
  30 namespace Tizen { namespace Ui
  31 {
  32 class Control;
  33
  34 /**
  35  * @class       GridLayout
  36  * @brief       The grid layout positions the children of a container in a rectangular grid.
  37  *
  38  * @since       2.0
  39  *
  40  * The %GridLayout class defines the grid layout for a Container. The layout positions the children of the %Container in a rectangular grid.
  41  * @n
  42  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/grid_layout.htm">Grid Layout</a>.
  43  *
  44  * @code
  45 // Sample code for GridLayoutSample.h
  46 #include <FUi.h>
  47
  48 class GridLayoutSample
  49         : public Tizen::Ui::Controls::Form
  50 {
  51 public:
  52         bool Initialize(void);
  53         virtual result OnInitializing(void);
  54 };
  55  *      @endcode
  56  *
  57  *      @code
  58 // Sample code for GridLayoutSample.cpp
  59 #include <FGraphics.h>
  60
  61 #include "GridLayoutSample.h"
  62
  63 using namespace Tizen::Graphics;
  64 using namespace Tizen::Ui;
  65 using namespace Tizen::Ui::Controls;
  66
  67 bool
  68 GridLayoutSample::Initialize(void)
  69 {
  70         Construct(FORM_STYLE_NORMAL);
  71         return true;
  72 }
  73
  74 result
  75 GridLayoutSample::OnInitializing(void)
  76 {
  77         result r = E_SUCCESS;
  78
  79         // Creates an instance of GridLayout
  80         GridLayout gridPanelLayout;
  81         gridPanelLayout.Construct(2, 3);
  82
  83         // Creates an instance of Panel and applies it to grid layout
  84         Panel* pPanel = new Panel();
  85         pPanel->Construct(gridPanelLayout, Rectangle((GetClientAreaBounds().width - 440)/2, (GetClientAreaBounds().height - 700)/2, 440, 700));
  86         {
  87                 // Creates instances of Label and an instanceo of Button
  88                 Label* pLabel1 = new Label();
  89                 pLabel1->Construct(Rectangle(0, 0, 100, 200), L"Label1\n(0, 0)");
  90                 pLabel1->SetBackgroundColor(Color(0x00, 0x10, 0x80, 0xFF));
  91                 pPanel->AddControl(*pLabel1);
  92
  93                 Label* pLabel2 = new Label();
  94                 pLabel2->Construct(Rectangle(0, 0, 100, 200), L"Label2\n(0, 1)");
  95                 pLabel2->SetBackgroundColor(Color(0x00, 0x20, 0xA0, 0xFF));
  96                 pPanel->AddControl(*pLabel2);
  97
  98                 Label* pLabel3 = new Label();
  99                 pLabel3->Construct(Rectangle(0, 0, 100, 200), L"Label3\n(0, 2)");
 100                 pLabel3->SetBackgroundColor(Color(0x00, 0x30, 0xC0, 0xFF));
 101                 pPanel->AddControl(*pLabel3);
 102
 103                 Label* pLabel4 = new Label();
 104                 pLabel4->Construct(Rectangle(0, 0, 100, 200), L"Label4\n(1, 0)");
 105                 pLabel4->SetBackgroundColor(Color(0x00, 0x40, 0xE0, 0xFF));
 106                 pPanel->AddControl(*pLabel4);
 107
 108                 Button* pButton = new Button();
 109                 pButton->Construct(Rectangle(0, 0, 100, 200), L"Button\n(1, 1)");
 110                 pPanel->AddControl(*pButton);
 111
 112                 // Sets position to each label and button in grid layout
 113                 gridPanelLayout.SetPosition(*pLabel1, 0, 0, 1, 1);
 114                 gridPanelLayout.SetPosition(*pLabel2, 0, 1, 1, 1);
 115                 gridPanelLayout.SetPosition(*pLabel3, 0, 2, 1, 1);
 116                 gridPanelLayout.SetPosition(*pLabel4, 1, 0, 1, 1);
 117                 gridPanelLayout.SetPosition(*pButton, 1, 1, 1, 2);
 118
 119                 // Sets stretchability each label and button in grid layout
 120                 gridPanelLayout.SetColumnStretchable(0, true);
 121                 gridPanelLayout.SetColumnStretchable(1, true);
 122                 gridPanelLayout.SetColumnStretchable(2, true);
 123                 gridPanelLayout.SetRowStretchable(1, true);
 124
 125                 // Sets spacing
 126                 gridPanelLayout.SetColumnSpacing(1, 10);
 127                 gridPanelLayout.SetRowSpacing(1, 10);
 128         }
 129
 130         // Adds the top panel to the form
 131         AddControl(*pPanel);
 132
 133         return r;
 134 }
 135  * @endcode
 136  *
 137  */
 138
 139 class _OSP_EXPORT_ GridLayout
 140         : public Layout
 141 {
 142 public:
 143         /**
 144          * 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.
 145          *
 146          * @since               2.0
 147          *
 148          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 149          */
 150         GridLayout(void);
 151
 152         /**
 153          * This destructor overrides Tizen::Base::Object::~Object().
 154          *
 155          * @since               2.0
 156          */
 157         virtual ~GridLayout(void);
 158
 159         /**
 160          * Initializes this instance of %GridLayout with the specified parameters.
 161          *
 162          * @since               2.0
 163          *
 164          * @return              An error code
 165          * @param[in]   rowCount                The number of rows
 166          * @param[in]   columnCount             The number of columns
 167          * @exception   E_SUCCESS               The method is successful.
 168          * @exception   E_INVALID_ARG   The specified index is out of range. @n
 169          *                                                              Either @c rowCount or @c columnCount is @c 0 or negative.
 170          * @exception   E_SYSTEM                A system error has occurred.
 171          */
 172         result Construct(int rowCount, int columnCount);
 173
 174         /**
 175          * Gets the type of the layout.
 176          *
 177          * @since       2.0
 178          *
 179          * @return      The layout type
 180          */
 181         virtual LayoutType GetLayoutType(void) const;
 182
 183         /**
 184          * Gets the number of rows in a grid layout.
 185          *
 186          * @since               2.0
 187          *
 188          * @return              The number of rows
 189          * @exception   E_SUCCESS                       The method is successful.
 190          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 191          */
 192         int GetRowCount(void) const;
 193
 194         /**
 195          * Gets the number of columns in a grid layout.
 196          *
 197          * @since               2.0
 198          *
 199          * @return              The number of columns
 200          * @exception   E_SUCCESS                       The method is successful.
 201          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 202          */
 203         int GetColumnCount(void) const;
 204
 205         /**
 206          * Sets the stretching ability of the specified column.
 207          *
 208          * @since               2.0
 209          *
 210          * @return              An error code
 211          * @param[in]   columnIndex             The column index
 212          * @param[in]   stretchable             Set to @c true to make the column stretchable, @n
 213          *                                                              else @c false
 214          * @exception   E_SUCCESS               The method is successful.
 215          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 216          * @exception   E_SYSTEM                A system error has occurred.
 217          */
 218         result SetColumnStretchable(int columnIndex, bool stretchable);
 219
 220         /**
 221          * Sets the shrinking ability of the specified column.
 222          *
 223          * @since               2.0
 224          *
 225          * @return              An error code
 226          * @param[in]   columnIndex             The column index
 227          * @param[in]   shrinkable              Set to @c true to make the column shrinkable, @n
 228          *                                                              else @c false
 229          * @exception   E_SUCCESS               The method is successful.
 230          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 231          * @exception   E_SYSTEM                A system error has occurred.
 232          */
 233         result SetColumnShrinkable(int columnIndex, bool shrinkable);
 234
 235         /**
 236          * Sets the collapsibility of a column.
 237          *
 238          * @since               2.0
 239          *
 240          * @return              An error code
 241          * @param[in]   columnIndex             The column index
 242          * @param[in]   collapsed               Set to @c true to make the column collapsible, @n
 243          *                                                              else @c false
 244          * @exception   E_SUCCESS               The method is successful.
 245          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 246          * @exception   E_SYSTEM                A system error has occurred.
 247          */
 248         result SetColumnCollapsed(int columnIndex, bool collapsed);
 249
 250         /**
 251          * Sets the stretching ability of all the columns.
 252          *
 253          * @since               2.0
 254          *
 255          * @return              An error code
 256          * @param[in]   stretchable             Set to @c true to set all columns as stretchable, @n
 257          *                                                              else @c false
 258          * @exception   E_SUCCESS               The method is successful.
 259          * @exception   E_SYSTEM                A system error has occurred.
 260          */
 261         result SetAllColumnsStretchable(bool stretchable);
 262
 263         /**
 264          * Sets the shrinking ability of all the columns.
 265          *
 266          * @since               2.0
 267          *
 268          * @return              An error code
 269          * @param[in]   shrinkable              Set to @c true to set all columns as shrinkable, @n
 270          *                                                              else @c false
 271          * @exception   E_SUCCESS               The method is successful.
 272          * @exception   E_SYSTEM                A system error has occurred.
 273          */
 274         result SetAllColumnsShrinkable(bool shrinkable);
 275
 276         /**
 277          * Sets the space before the specified column index.
 278          *
 279          * @since               2.0
 280          *
 281          * @return              An error code
 282          * @param[in]   columnIndex             The column index
 283          * @param[in]   space                   An @c int representing the space
 284          * @exception   E_SUCCESS               The method is successful.
 285          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 286          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 287          * @exception   E_SYSTEM                A system error has occurred.
 288          * @remarks             This method does not perform any operation if the value of @c columnIndex is 0.
 289          * @remarks             The column spacing cannot be applied to the first column.
 290          */
 291         result SetColumnSpacing(int columnIndex, int space);
 292
 293         /**
 294          * Sets the space before the specified column index.
 295          *
 296          * @since               2.1
 297          *
 298          * @return              An error code
 299          * @param[in]   columnIndex             The column index
 300          * @param[in]   space                   An @c int representing the space
 301          * @exception   E_SUCCESS               The method is successful.
 302          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 303          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 304          * @exception   E_SYSTEM                A system error has occurred.
 305          * @remarks             This method does not perform any operation if the value of @c columnIndex is 0.
 306          * @remarks             The column spacing cannot be applied to the first column.
 307          */
 308         result SetColumnSpacing(int columnIndex, float space);
 309
 310         /**
 311          * Sets the stretching ability of the specified row.
 312          *
 313          * @since               2.0
 314          *
 315          * @return              An error code
 316          * @param[in]   rowIndex                The row index
 317          * @param[in]   stretchable             Set to @c true to make the row stretchable, @n
 318          *                                                              else @c false
 319          * @exception   E_SUCCESS               The method is successful.
 320          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 321          * @exception   E_SYSTEM                A system error has occurred.
 322          */
 323         result SetRowStretchable(int rowIndex, bool stretchable);
 324
 325         /**
 326          * Sets the shrinking ability of the specified row.
 327          *
 328          * @since               2.0
 329          *
 330          * @return              An error code
 331          * @param[in]   rowIndex                The row index
 332          * @param[in]   shrinkable              Set to @c true to make the row shrinkable, @n
 333          *                                                              else @c false
 334          * @exception   E_SUCCESS               The method is successful.
 335          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 336          * @exception   E_SYSTEM                A system error has occurred.
 337          */
 338         result SetRowShrinkable(int rowIndex, bool shrinkable);
 339
 340         /**
 341          * Sets the collapsibility of the specified row.
 342          *
 343          * @since               2.0
 344          *
 345          * @return              An error code
 346          * @param[in]   rowIndex                The row index
 347          * @param[in]   collapsed               Set to @c true to make the row as collapsible, @n
 348          *                                                              else @c false
 349          * @exception   E_SUCCESS               The method is successful.
 350          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 351          * @exception   E_SYSTEM                A system error has occurred.
 352          */
 353         result SetRowCollapsed(int rowIndex, bool collapsed);
 354
 355         /**
 356          * Sets the stretching ability of all the rows.
 357          *
 358          * @since               2.0
 359          *
 360          * @return              An error code
 361          * @param[in]   stretchable             Set to @c true to set all the rows as stretchable, @n
 362          *                                                              else @c false
 363          * @exception   E_SUCCESS               The method is successful.
 364          * @exception   E_SYSTEM                A system error has occurred.
 365          */
 366         result SetAllRowsStretchable(bool stretchable);
 367
 368         /**
 369          * Sets the shrinking ability of all the rows.
 370          *
 371          * @since               2.0
 372          *
 373          * @return              An error code
 374          * @param[in]   shrinkable              Set to @c true to set all the rows as shrinkable, @n
 375          *                                                              else @c false
 376          * @exception   E_SUCCESS               The method is successful.
 377          * @exception   E_SYSTEM                A system error has occurred.
 378          */
 379         result SetAllRowsShrinkable(bool shrinkable);
 380
 381         /**
 382          * Sets the space before the specified column index.
 383          *
 384          * @since               2.0
 385          *
 386          * @return              An error code
 387          * @param[in]   rowIndex                The row index
 388          * @param[in]   space                   An @c int representing the space
 389          * @exception   E_SUCCESS               The method is successful.
 390          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 391          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 392          * @exception   E_SYSTEM                A system error has occurred.
 393          * @remarks             This method does not perform any operation if the value of @c rowIndex is @c 0.
 394          * @remarks             The row spacing cannot be applied to the first column.
 395          */
 396         result SetRowSpacing(int rowIndex, int space);
 397
 398         /**
 399          * Sets the space before the specified column index.
 400          *
 401          * @since               2.1
 402          *
 403          * @return              An error code
 404          * @param[in]   rowIndex                The row index
 405          * @param[in]   space                   An @c int representing the space
 406          * @exception   E_SUCCESS               The method is successful.
 407          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 408          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 409          * @exception   E_SYSTEM                A system error has occurred.
 410          * @remarks             This method does not perform any operation if the value of @c rowIndex is @c 0.
 411          * @remarks             The row spacing cannot be applied to the first column.
 412          */
 413         result SetRowSpacing(int rowIndex, float space);
 414
 415         /**
 416          * Sets the position and span of the control. @n
 417          * Adds the control at the specified position.
 418          *
 419          * @since               2.0
 420          *
 421          * @return              An error code
 422          * @param[in]   childControl            The control for which the position is set
 423          * @param[in]   rowStartIndex           The row index
 424          * @param[in]   columnStartIndex        The column index
 425          * @param[in]   rowSpan                         The row span specifies the total number of cells in a row that are to be merged into a cell
 426          * @param[in]   columnSpan                      The column span specifies the total number of cells in a column that are to be merged into a cell
 427          * @exception   E_SUCCESS                       The method is successful.
 428          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 429          *                                                                      - A specified input parameter is invalid. @n
 430          *                                                                      - Either @c rowSpan or @c columnSpan is @c 0 or negative. @n
 431          *                                                                      - The specified @c childControl parameter is not a child of the container that owns the layout. @n
 432          *                                                                      - The specified span has tried to include a cell, which is already included in another span.
 433          * @exception   E_OUT_OF_RANGE          The specified index is out of range, or @n
 434          *                                                                      the calculated range of the cell is out of the grid.
 435          * @exception   E_SYSTEM                        A system error has occurred.
 436          */
 437         result SetPosition(Control& childControl, int rowStartIndex, int columnStartIndex, int rowSpan, int columnSpan);
 438
 439         /**
 440          * Sets the horizontal alignment and the vertical alignment.
 441          *
 442          * @since               2.0
 443          *
 444          * @return              An error code
 445          * @param[in]   childControl            The control for which the alignment is set
 446          * @param[in]   horizontalAlignment     The horizontal alignment
 447          * @param[in]   verticalAlignment       The vertical alignment
 448          * @exception   E_SUCCESS                       The method is successful.
 449          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 450          *                                                                      The specified @c childControl parameter is not a child of the container that owns the layout.
 451          * @exception   E_SYSTEM                        A system error has occurred.
 452          * @remarks                                             By default, the value of @c horizontalAlignment is HORIZONTAL_ALIGN_LEFT and the value of @c verticalAlignment is
 453          *                                                                      VERTICAL_ALIGN_TOP.
 454          *                                                              The column width is set to the largest width amongst controls in the column, and the row height is set to the largest
 455          *                                                                      height amongst controls in the row.
 456          *                                                              Therefore, the smaller controls have vertical or horizontal margins around them, and they are repositioned in cells
 457          *                                                                      according to the alignment options.
 458          */
 459         result SetAlignment(Control& childControl, LayoutHorizontalAlignment horizontalAlignment, LayoutVerticalAlignment verticalAlignment);
 460
 461         /**
 462          * Sets the margins of the specified control.
 463          *
 464          * @since               2.0
 465          *
 466          * @return              An error code
 467          * @param[in]   childControl    The control for which the margins are set
 468          * @param[in]   left                    The left margin
 469          * @param[in]   right                   The right margin
 470          * @param[in]   top                             The top margin
 471          * @param[in]   bottom                  The bottom margin
 472          * @exception   E_SUCCESS               The method is successful.
 473          * @exception   E_INVALID_ARG   A specified input parameter is invalid. @n
 474          *                                                              The specified @c childControl parameter is not a child of the container that owns the layout.
 475          * @exception   E_SYSTEM                A system error has occurred.
 476          * @remarks             By default, the margins are set to @c 0.
 477          */
 478         result SetMargin(Control& childControl, int left, int right, int top, int bottom);
 479
 480         /**
 481          * Sets the margins of the specified control.
 482          *
 483          * @since               2.1
 484          *
 485          * @return              An error code
 486          * @param[in]   childControl    The control for which the margins are set
 487          * @param[in]   left                    The left margin
 488          * @param[in]   right                   The right margin
 489          * @param[in]   top                             The top margin
 490          * @param[in]   bottom                  The bottom margin
 491          * @exception   E_SUCCESS               The method is successful.
 492          * @exception   E_INVALID_ARG   A specified input parameter is invalid. @n
 493          *                                                              The specified @c childControl parameter is not a child of the container that owns the layout.
 494          * @exception   E_SYSTEM                A system error has occurred.
 495          * @remarks             By default, the margins are set to @c 0.
 496          */
 497         result SetMargin(Control& childControl, float left, float right, float top, float bottom);
 498 private:
 499         //
 500         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 501         //
 502         GridLayout(const GridLayout& rhs);
 503
 504         //
 505         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 506         //
 507         GridLayout& operator =(const GridLayout& rhs);
 508 }; // GridLayout
 509
 510 }} // Tizen::Ui
 511
 512 #endif // _FUI_GRID_LAYOUT_H_