dali-toolkit/devel-api/controls/table-view/table-view.h

   1 #ifndef DALI_TOOLKIT_TABLE_VIEW_H
   2 #define DALI_TOOLKIT_TABLE_VIEW_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <dali/public-api/actors/actor-enumerations.h>
  23 #include <dali/public-api/common/vector-wrapper.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/controls/control.h>
  27
  28 namespace Dali
  29 {
  30 namespace Toolkit
  31 {
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class TableView;
  35 }
  36 /**
  37  * @addtogroup dali_toolkit_controls_table_view
  38  * @{
  39  */
  40
  41 /**
  42  * @brief TableView is a layout container for aligning child actors in a grid like layout.
  43  *
  44  * TableView constrains the x and y position and width and height of the child actors.
  45  * z position and depth are left intact so that 3D model actors can also be laid out
  46  * in a grid without loosing their depth scaling.
  47  *
  48  * @nosubgrouping
  49  * <h3>Per-child Custom properties for script supporting:</h3>
  50  *
  51  * When an actor is add to the tableView through Actor::Add() instead of TableView::AddChild,
  52  * the following custom properties of the actor are checked to decide the actor position inside the table.
  53  *
  54  * These properties are registered dynamically to the child and is non-animatable.
  55  *
  56  * | %Property Name          | Type        |
  57  * |-------------------------|-------------|
  58  * | cellIndex               | Vector2     |
  59  * | rowSpan                 | float       |
  60  * | columnSpan              | float       |
  61  * | cellHorizontalAlignment | string      |
  62  * | cellVerticalAlignment   | string      |
  63  *
  64  * The rowSpan or columnSpan has integer value, but its type is float here due to the limitation of the builder's ability to differentiate integer and float from Json string.
  65  * The available values for cellHorizontalAlignment are: left, center, right.
  66  * The available values for cellVerticalAlignment are: top, center, bottom.
  67  *
  68  * @code
  69  * "name":"gallery1",
  70  * "type":"ImageView",
  71  * "image": {
  72  *    "url": "{DALI_IMAGE_DIR}gallery-small-1.jpg"
  73  *  },
  74  *  "properties": {
  75  *     "cellIndex":[1,1],  // Property to specify the top-left cell this child occupies, if not set, the first available cell is used
  76  *     "rowSpan":3,        // Property to specify how many rows this child occupies, if not set, default value is 1
  77  *     "columnSpan": 2,    // Property to specify how many columns this child occupies, if nor set, default value is 1
  78  *     "cellHorizontalAlignment": "left", // Property to specify how to align horizontally inside the cells, if not set, default value is 'left'
  79  *     "cellVerticalAlignment": "center"  // Property to specify how to align vertically inside the cells, if not set, default value is 'top'
  80  *   }
  81  * @endcode
  82  * @SINCE_1_0.0
  83  */
  84 class DALI_TOOLKIT_API TableView : public Control
  85 {
  86 public:
  87   /**
  88    * @brief Enumeration for the start and end property ranges for this control.
  89    * @SINCE_1_0.0
  90    */
  91   enum PropertyRange
  92   {
  93     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  94     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000,             ///< Reserve property indices @SINCE_1_0.0
  95
  96     CHILD_PROPERTY_START_INDEX = CHILD_PROPERTY_REGISTRATION_START_INDEX,       ///< @SINCE_1_1.36
  97     CHILD_PROPERTY_END_INDEX   = CHILD_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve child property indices @SINCE_1_1.36
  98   };
  99
 100   /**
 101    * @brief Enumeration for the instance of properties belonging to the TableView class.
 102    *
 103    * LayoutRows: set the height of the rows.
 104    * It has the format as follows in script:
 105    * @code
 106    * "layoutRows":
 107    *       {
 108    *         "0": { "policy": "fixed", "value": 40 },       //@see SetFixedHight
 109    *         "2": { "policy": "relative", "value": 0.33 },  //@see SetRelativeHeight
 110    *         "3": { "policy": "fit", "value":0.0 }          //@see SetFitHeight, the value is not used, its height is decided by the children in this row
 111    *       }
 112    * @endcode
 113    *
 114    * LayoutColumns: set the width of the columns.
 115    * It has the format as follows in script:
 116    * @code
 117    * "layoutColumns":
 118    *       {
 119    *         "0": { "policy": "fixed", "value": 40 },       //@see SetFixedWidth
 120    *         "1": { "policy": "fit", "value":0.0 }          //@see SetFitHeight, the value is not used, its width is decided by the children in this column
 121    *         "2": { "policy": "relative", "value": 0.33 }   //@see SetRelativeWidth
 122    *       }
 123    * @endcode
 124    * @SINCE_1_0.0
 125    */
 126   struct Property
 127   {
 128     /**
 129      * @brief Enumeration for the instance of properties belonging to the TableView class.
 130      *
 131      * @SINCE_1_0.0
 132      */
 133     enum
 134     {
 135       ROWS = PROPERTY_START_INDEX, ///< name "rows",           type unsigned int @SINCE_1_0.0
 136       COLUMNS,                     ///< name "columns",        type unsigned int @SINCE_1_0.0
 137       CELL_PADDING,                ///< name "cellPadding",    type Vector2 @SINCE_1_0.0
 138       LAYOUT_ROWS,                 ///< name "layoutRows",     type Map @SINCE_1_0.0
 139       LAYOUT_COLUMNS,              ///< name "layoutColumns",  type Map @SINCE_1_0.0
 140     };
 141   };
 142
 143   /**
 144    * @brief Enumeration for the instance of child properties belonging to the TableView class.
 145    * @SINCE_1_1.36
 146    */
 147   struct ChildProperty
 148   {
 149     /**
 150      * @brief Enumeration for the instance of child properties belonging to the TableView class.
 151      * @SINCE_1_1.36
 152      */
 153     enum
 154     {
 155       CELL_INDEX = CHILD_PROPERTY_START_INDEX, ///< name "cellIndex",                The top-left cell this child occupies, if not set, the first available cell is used,           type VECTOR2 @SINCE_1_1.36
 156       ROW_SPAN,                                ///< name "rowSpan",                  The number of rows this child occupies, if not set, default value is 1,                        type FLOAT @SINCE_1_1.36
 157       COLUMN_SPAN,                             ///< name "columnSpan",               The number of columns this child occupies, if not set, default value is 1,                     type FLOAT @SINCE_1_1.36
 158       CELL_HORIZONTAL_ALIGNMENT,               ///< name "cellHorizontalAlignment",  The horizontal alignment of this child inside the cells, if not set, default value is 'left',  type STRING @SINCE_1_1.36
 159       CELL_VERTICAL_ALIGNMENT                  ///< name "cellVerticalAlignment",    The vertical alignment of this child inside the cells, if not set, default value is 'top',     type STRING @SINCE_1_1.36
 160     };
 161   };
 162
 163   /**
 164    * @brief Enumeration for describing how the size of a row / column has been set.
 165    * @SINCE_1_0.0
 166    */
 167   enum LayoutPolicy
 168   {
 169     FIXED,    ///< Fixed with the given value. @SINCE_1_0.0
 170     RELATIVE, ///< Calculated as percentage of the remainder after subtracting Padding and Fixed height/width @SINCE_1_0.0
 171     FILL,     ///< Default policy, get the remainder of the 100% (after subtracting Fixed, Fit and Relative height/ width) divided evenly between 'fill' rows/columns @SINCE_1_0.0
 172     FIT       ///< Fit around its children. @SINCE_1_0.0
 173   };
 174
 175   /**
 176    * @brief Structure to specify layout position for child actor.
 177    * @SINCE_1_0.0
 178    */
 179   struct CellPosition
 180   {
 181     /**
 182      * @brief Constructor to initialise values to defaults for convenience.
 183      * @SINCE_1_0.0
 184      * @param[in] rowIndex The row index initialized
 185      * @param[in] columnIndex The column index initialized
 186      * @param[in] rowSpan The row span initialized
 187      * @param[in] columnSpan The column span initialized
 188      */
 189     CellPosition(unsigned int rowIndex = 0, unsigned int columnIndex = 0, unsigned int rowSpan = 1, unsigned int columnSpan = 1)
 190     : rowIndex(rowIndex),
 191       columnIndex(columnIndex),
 192       rowSpan(rowSpan),
 193       columnSpan(columnSpan)
 194     {
 195     }
 196
 197     unsigned int rowIndex;
 198     unsigned int columnIndex;
 199     unsigned int rowSpan;
 200     unsigned int columnSpan;
 201   };
 202
 203   /**
 204    * @brief Creates a TableView handle; this can be initialized with TableView::New().
 205    * Calling member functions with an uninitialized handle is not allowed.
 206    * @SINCE_1_0.0
 207    */
 208   TableView();
 209
 210   /**
 211    * @brief Copy constructor. Creates another handle that points to the same real object.
 212    * @SINCE_1_0.0
 213    * @param[in] handle Handle to copy from
 214    */
 215   TableView(const TableView& handle);
 216
 217   /**
 218    * @brief Assignment operator. Changes this handle to point to another real object.
 219    * @SINCE_1_0.0
 220    * @param[in] handle Handle to an object
 221    * @return A reference to this
 222    */
 223   TableView& operator=(const TableView& handle);
 224
 225   /**
 226    * @brief Destructor.
 227    *
 228    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 229    * @SINCE_1_0.0
 230    */
 231   ~TableView();
 232
 233   /**
 234    * @brief Creates the TableView control.
 235    * @SINCE_1_0.0
 236    * @param[in] initialRows for the table
 237    * @param[in] initialColumns for the table
 238    * @return A handle to the TableView control
 239    */
 240   static TableView New(unsigned int initialRows, unsigned int initialColumns);
 241
 242   /**
 243    * @brief Downcasts a handle to TableView handle.
 244    *
 245    * If handle points to a TableView, the downcast produces valid handle.
 246    * If not, the returned handle is left uninitialized.
 247    * @SINCE_1_0.0
 248    * @param[in] handle Handle to an object
 249    * @return Handle to a TableView or an uninitialized handle
 250    */
 251   static TableView DownCast(BaseHandle handle);
 252
 253   /**
 254    * @brief Adds a child to the table.
 255    * If the row or column index is outside the table, the table gets resized bigger.
 256    * @SINCE_1_0.0
 257    * @param[in] child The child to add
 258    * @param[in] position The position for the child
 259    * @return @c true if the addition succeeded, @c false if the cell is already occupied
 260    * @pre The child actor has been initialized.
 261    */
 262   bool AddChild(Actor child, CellPosition position);
 263
 264   /**
 265    * @brief Returns a child from the given layout position.
 266    * @SINCE_1_0.0
 267    * @param[in] position The position in the table
 268    * @return Child that was in the cell or an uninitialized handle
 269    * @note If there is no child in this position this method returns an uninitialized.
 270    * Actor handle
 271    */
 272   Actor GetChildAt(CellPosition position);
 273
 274   /**
 275    * @brief Removes a child from the given layout position.
 276    * @SINCE_1_0.0
 277    * @param[in] position The position for the child to remove
 278    * @return Child that was removed or an uninitialized handle
 279    * @note If there is no child in this position, this method does nothing.
 280    */
 281   Actor RemoveChildAt(CellPosition position);
 282
 283   /**
 284    * @brief Finds the child's layout position.
 285    * @SINCE_1_0.0
 286    * @param[in] child The child to search for
 287    * @param[out] position The position for the child
 288    * @return true if the child was included in this TableView
 289    */
 290   bool FindChildPosition(Actor child, CellPosition& position);
 291
 292   /**
 293    * @brief Inserts a new row to given index.
 294    * @SINCE_1_0.0
 295    * @param[in] rowIndex The rowIndex of the new row
 296    */
 297   void InsertRow(unsigned int rowIndex);
 298
 299   /**
 300    * @brief Deletes a row from the given index.
 301    * Removed elements are deleted.
 302    * @SINCE_1_0.0
 303    * @param[in] rowIndex The rowIndex of the row to delete
 304    */
 305   void DeleteRow(unsigned int rowIndex);
 306
 307   /**
 308    * @brief Deletes a row from the given index.
 309    * @SINCE_1_0.0
 310    * @param[in] rowIndex The rowIndex of the row to delete
 311    * @param[out] removed The removed elements
 312    */
 313   void DeleteRow(unsigned int rowIndex, std::vector<Actor>& removed);
 314
 315   /**
 316    * @brief Inserts a new column to the given index.
 317    * @SINCE_1_0.0
 318    * @param[in] columnIndex The columnIndex of the new column
 319    */
 320   void InsertColumn(unsigned int columnIndex);
 321
 322   /**
 323    * @brief Deletes a column from the given index.
 324    * Removed elements are deleted.
 325    * @SINCE_1_0.0
 326    * @param[in] columnIndex The columnIndex of the column to delete
 327    */
 328   void DeleteColumn(unsigned int columnIndex);
 329
 330   /**
 331    * @brief Deletes a column from the given index.
 332    * @SINCE_1_0.0
 333    * @param[in] columnIndex The columnIndex of the column to delete
 334    * @param[out] removed The removed elements
 335    */
 336   void DeleteColumn(unsigned int columnIndex, std::vector<Actor>& removed);
 337
 338   /**
 339    * @brief Resizes the TableView.
 340    * @SINCE_1_0.0
 341    * @param[in] rows The rows for the table
 342    * @param[in] columns The columns for the table
 343    * @note If the new size is smaller than old,
 344    * superfluous actors get removed. If you want to relayout removed children,
 345    * use the variant that returns the removed Actors and reinsert them into the table.
 346    * If an actor spans to a removed row or column, it gets removed from the table.
 347    */
 348   void Resize(unsigned int rows, unsigned int columns);
 349
 350   /**
 351    * @brief Resizes the TableView.
 352    * @SINCE_1_0.0
 353    * @param[in] rows The rows for the table
 354    * @param[in] columns The columns for the table
 355    * @param[out] removed The removed actor handles
 356    * @note If the new size is smaller than old, superfluous actors get removed.
 357    * If an actor spans to a removed row or column it gets removed from the table.
 358    */
 359   void Resize(unsigned int rows, unsigned int columns, std::vector<Actor>& removed);
 360
 361   /**
 362    * @brief Sets horizontal and vertical padding between cells.
 363    * @SINCE_1_0.0
 364    * @param[in] padding Width and height
 365    */
 366   void SetCellPadding(Size padding);
 367
 368   /**
 369    * @brief Gets the current padding as width and height.
 370    * @SINCE_1_0.0
 371    * @return The current padding as width and height
 372    */
 373   Size GetCellPadding();
 374
 375   /**
 376    * @brief Specifies this row as fitting its height to its children.
 377    *
 378    * @SINCE_1_0.0
 379    * @param[in] rowIndex The row to set
 380    */
 381   void SetFitHeight(unsigned int rowIndex);
 382
 383   /**
 384    * @brief Checks if the row is a fit row.
 385    *
 386    * @SINCE_1_0.0
 387    * @param[in] rowIndex The row to check
 388    * @return Return true if the row is fit
 389    */
 390   bool IsFitHeight(unsigned int rowIndex) const;
 391
 392   /**
 393    * @brief Specifies this column as fitting its width to its children.
 394    *
 395    * @SINCE_1_0.0
 396    * @param[in] columnIndex The column to set
 397    */
 398   void SetFitWidth(unsigned int columnIndex);
 399
 400   /**
 401    * @brief Checks if the column is a fit column.
 402    *
 403    * @SINCE_1_0.0
 404    * @param[in] columnIndex The column to check
 405    * @return Return true if the column is fit
 406    */
 407   bool IsFitWidth(unsigned int columnIndex) const;
 408
 409   /**
 410    * @brief Sets a row to have fixed height.
 411    * Setting a fixed height of 0 has no effect.
 412    * @SINCE_1_0.0
 413    * @param rowIndex The rowIndex for row with fixed height
 414    * @param height The height in world coordinate units
 415    * @pre The row rowIndex must exist.
 416    */
 417   void SetFixedHeight(unsigned int rowIndex, float height);
 418
 419   /**
 420    * @brief Gets a row's fixed height.
 421    * @SINCE_1_0.0
 422    * @param[in] rowIndex The row index with fixed height
 423    * @return height The height in world coordinate units
 424    * @pre The row rowIndex must exist.
 425    * @note The returned value is valid if it has been set before.
 426    */
 427   float GetFixedHeight(unsigned int rowIndex) const;
 428
 429   /**
 430    * @brief Sets a row to have relative height. Relative height means percentage of
 431    * the remainder of the table height after subtracting Padding and Fixed height rows.
 432    * Setting a relative height of 0 has no effect.
 433    * @SINCE_1_0.0
 434    * @param rowIndex The rowIndex for row with relative height
 435    * @param heightPercentage between 0.0f and 1.0f
 436    * @pre The row rowIndex must exist.
 437    */
 438   void SetRelativeHeight(unsigned int rowIndex, float heightPercentage);
 439
 440   /**
 441    * @brief Gets a row's relative height.
 442    * @SINCE_1_0.0
 443    * @param[in] rowIndex The row index with relative height
 444    * @return Height in percentage units, between 0.0f and 1.0f
 445    * @pre The row rowIndex must exist.
 446    * @note The returned value is valid if it has been set before.
 447    */
 448   float GetRelativeHeight(unsigned int rowIndex) const;
 449
 450   /**
 451    * @brief Sets a column to have fixed width.
 452    * Setting a fixed width of 0 has no effect.
 453    * @SINCE_1_0.0
 454    * @param columnIndex The columnIndex for column with fixed width
 455    * @param width The width in world coordinate units
 456    * @pre The column columnIndex must exist.
 457    */
 458   void SetFixedWidth(unsigned int columnIndex, float width);
 459
 460   /**
 461    * @brief Gets a column's fixed width.
 462    * @SINCE_1_0.0
 463    * @param[in] columnIndex The column index with fixed width
 464    * @return Width in world coordinate units
 465    * @pre The column columnIndex must exist.
 466    * @note The returned value is valid if it has been set before.
 467    */
 468   float GetFixedWidth(unsigned int columnIndex) const;
 469
 470   /**
 471    * @brief Sets a column to have relative width. Relative width means percentage of
 472    * the remainder of table width after subtracting Padding and Fixed width columns.
 473    * Setting a relative width of 0 has no effect.
 474    * @SINCE_1_0.0
 475    * @param columnIndex The columnIndex for column with fixed width
 476    * @param widthPercentage The widthPercentage between 0.0f and 1.0f
 477    * @pre The column columnIndex must exist.
 478    */
 479   void SetRelativeWidth(unsigned int columnIndex, float widthPercentage);
 480
 481   /**
 482    * @brief Gets a column's relative width.
 483    * @SINCE_1_0.0
 484    * @param[in] columnIndex The column index with relative width
 485    * @return Width in percentage units, between 0.0f and 1.0f
 486    * @pre The column columnIndex must exist.
 487    * @note The returned value is valid if it has been set before.
 488    */
 489   float GetRelativeWidth(unsigned int columnIndex) const;
 490
 491   /**
 492    * @brief Gets the amount of rows in the table.
 493    * @SINCE_1_0.0
 494    * @return The amount of rows in the table
 495    */
 496   unsigned int GetRows();
 497
 498   /**
 499    * @brief Gets the amount of columns in the table.
 500    * @SINCE_1_0.0
 501    * @return The amount of columns in the table
 502    */
 503   unsigned int GetColumns();
 504
 505   /**
 506    * @brief Sets the alignment on a cell.
 507    *
 508    * Cells without calling this function have the default values of LEFT and TOP respectively.
 509    *
 510    * @SINCE_1_0.0
 511    * @param[in] position The cell to set alignment on
 512    * @param[in] horizontal The horizontal alignment
 513    * @param[in] vertical The vertical alignment
 514    */
 515   void SetCellAlignment(CellPosition position, HorizontalAlignment::Type horizontal, VerticalAlignment::Type vertical);
 516
 517 public: // Not intended for application developers
 518   /// @cond internal
 519   /**
 520    * @brief Creates a handle using the Toolkit::Internal implementation.
 521    * @SINCE_1_0.0
 522    * @param[in] implementation The Control implementation
 523    */
 524   DALI_INTERNAL TableView(Internal::TableView& implementation);
 525
 526   /**
 527    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 528    * @SINCE_1_0.0
 529    * @param[in] internal A pointer to the internal CustomActor
 530    */
 531   explicit DALI_INTERNAL TableView(Dali::Internal::CustomActor* internal);
 532   /// @endcond
 533 };
 534
 535 /**
 536  * @}
 537  */
 538 } // namespace Toolkit
 539
 540 } // namespace Dali
 541
 542 #endif // DALI_TOOLKIT_TABLE_VIEW_H