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 stretching ability of the specified row.
 295          *
 296          * @since               2.0
 297          *
 298          * @return              An error code
 299          * @param[in]   rowIndex                The row index
 300          * @param[in]   stretchable             Set to @c true to make the row stretchable, @n
 301          *                                                              else @c false
 302          * @exception   E_SUCCESS               The method is successful.
 303          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 304          * @exception   E_SYSTEM                A system error has occurred.
 305          */
 306         result SetRowStretchable(int rowIndex, bool stretchable);
 307
 308         /**
 309          * Sets the shrinking ability of the specified row.
 310          *
 311          * @since               2.0
 312          *
 313          * @return              An error code
 314          * @param[in]   rowIndex                The row index
 315          * @param[in]   shrinkable              Set to @c true to make the row shrinkable, @n
 316          *                                                              else @c false
 317          * @exception   E_SUCCESS               The method is successful.
 318          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 319          * @exception   E_SYSTEM                A system error has occurred.
 320          */
 321         result SetRowShrinkable(int rowIndex, bool shrinkable);
 322
 323         /**
 324          * Sets the collapsibility of the specified row.
 325          *
 326          * @since               2.0
 327          *
 328          * @return              An error code
 329          * @param[in]   rowIndex                The row index
 330          * @param[in]   collapsed               Set to @c true to make the row as collapsible, @n
 331          *                                                              else @c false
 332          * @exception   E_SUCCESS               The method is successful.
 333          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 334          * @exception   E_SYSTEM                A system error has occurred.
 335          */
 336         result SetRowCollapsed(int rowIndex, bool collapsed);
 337
 338         /**
 339          * Sets the stretching ability of all the rows.
 340          *
 341          * @since               2.0
 342          *
 343          * @return              An error code
 344          * @param[in]   stretchable             Set to @c true to set all the rows as stretchable, @n
 345          *                                                              else @c false
 346          * @exception   E_SUCCESS               The method is successful.
 347          * @exception   E_SYSTEM                A system error has occurred.
 348          */
 349         result SetAllRowsStretchable(bool stretchable);
 350
 351         /**
 352          * Sets the shrinking ability of all the rows.
 353          *
 354          * @since               2.0
 355          *
 356          * @return              An error code
 357          * @param[in]   shrinkable              Set to @c true to set all the rows as shrinkable, @n
 358          *                                                              else @c false
 359          * @exception   E_SUCCESS               The method is successful.
 360          * @exception   E_SYSTEM                A system error has occurred.
 361          */
 362         result SetAllRowsShrinkable(bool shrinkable);
 363
 364         /**
 365          * Sets the space before the specified column index.
 366          *
 367          * @since               2.0
 368          *
 369          * @return              An error code
 370          * @param[in]   rowIndex                The row index
 371          * @param[in]   space                   An @c int representing the space
 372          * @exception   E_SUCCESS               The method is successful.
 373          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 374          * @exception   E_OUT_OF_RANGE  The specified index is out of range.
 375          * @exception   E_SYSTEM                A system error has occurred.
 376          * @remarks             This method does not perform any operation if the value of @c rowIndex is @c 0.
 377          * @remarks             The row spacing cannot be applied to the first column.
 378          */
 379         result SetRowSpacing(int rowIndex, int space);
 380
 381         /**
 382          * Sets the position and span of the control. @n
 383          * Adds the control at the specified position.
 384          *
 385          * @since               2.0
 386          *
 387          * @return              An error code
 388          * @param[in]   childControl            The control for which the position is set
 389          * @param[in]   rowStartIndex           The row index
 390          * @param[in]   columnStartIndex        The column index
 391          * @param[in]   rowSpan                         The row span specifies the total number of cells in a row that are to be merged into a cell
 392          * @param[in]   columnSpan                      The column span specifies the total number of cells in a column that are to be merged into a cell
 393          * @exception   E_SUCCESS                       The method is successful.
 394          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 395          *                                                                      - A specified input parameter is invalid. @n
 396          *                                                                      - Either @c rowSpan or @c columnSpan is @c 0 or negative. @n
 397          *                                                                      - The specified @c childControl parameter is not a child of the container that owns the layout. @n
 398          *                                                                      - The specified span has tried to include a cell, which is already included in another span.
 399          * @exception   E_OUT_OF_RANGE          The specified index is out of range, or @n
 400          *                                                                      the calculated range of the cell is out of the grid.
 401          * @exception   E_SYSTEM                        A system error has occurred.
 402          */
 403         result SetPosition(Control& childControl, int rowStartIndex, int columnStartIndex, int rowSpan, int columnSpan);
 404
 405         /**
 406          * Sets the horizontal alignment and the vertical alignment.
 407          *
 408          * @since               2.0
 409          *
 410          * @return              An error code
 411          * @param[in]   childControl            The control for which the alignment is set
 412          * @param[in]   horizontalAlignment     The horizontal alignment
 413          * @param[in]   verticalAlignment       The vertical alignment
 414          * @exception   E_SUCCESS                       The method is successful.
 415          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 416          *                                                                      The specified @c childControl parameter is not a child of the container that owns the layout.
 417          * @exception   E_SYSTEM                        A system error has occurred.
 418          * @remarks                                             By default, the value of @c horizontalAlignment is HORIZONTAL_ALIGN_LEFT and the value of @c verticalAlignment is
 419          *                                                                      VERTICAL_ALIGN_TOP.
 420          *                                                              The column width is set to the largest width amongst controls in the column, and the row height is set to the largest
 421          *                                                                      height amongst controls in the row.
 422          *                                                              Therefore, the smaller controls have vertical or horizontal margins around them, and they are repositioned in cells
 423          *                                                                      according to the alignment options.
 424          */
 425         result SetAlignment(Control& childControl, LayoutHorizontalAlignment horizontalAlignment, LayoutVerticalAlignment verticalAlignment);
 426
 427         /**
 428          * Sets the margins of the specified control.
 429          *
 430          * @since               2.0
 431          *
 432          * @return              An error code
 433          * @param[in]   childControl    The control for which the margins are set
 434          * @param[in]   left                    The left margin
 435          * @param[in]   right                   The right margin
 436          * @param[in]   top                             The top margin
 437          * @param[in]   bottom                  The bottom margin
 438          * @exception   E_SUCCESS               The method is successful.
 439          * @exception   E_INVALID_ARG   A specified input parameter is invalid. @n
 440          *                                                              The specified @c childControl parameter is not a child of the container that owns the layout.
 441          * @exception   E_SYSTEM                A system error has occurred.
 442          * @remarks             By default, the margins are set to @c 0.
 443          */
 444         result SetMargin(Control& childControl, int left, int right, int top, int bottom);
 445
 446 private:
 447         //
 448         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 449         //
 450         GridLayout(const GridLayout& rhs);
 451
 452         //
 453         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 454         //
 455         GridLayout& operator =(const GridLayout& rhs);
 456 }; // GridLayout
 457
 458 }} // Tizen::Ui
 459
 460 #endif // _FUI_GRID_LAYOUT_H_