dali-toolkit/public-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) 2015 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/common/vector-wrapper.h>
  23 #include <dali/public-api/actors/actor-enumerations.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/controls/control.h>
  27
  28 namespace Dali
  29 {
  30
  31 namespace Toolkit
  32 {
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class TableView;
  37 }
  38
  39 /**
  40  * TableView is a layout container for aligning child actors in a grid like layout.
  41  * TableView constrains the x and y position and width and height of the child actors.
  42  * z position and depth are left intact so that 3D model actors can also be laid out
  43  * in a grid without loosing their depth scaling.
  44  */
  45 class DALI_IMPORT_API TableView : public Control
  46 {
  47 public:
  48
  49   /**
  50    * @brief The start and end property ranges for this control.
  51    */
  52   enum PropertyRange
  53   {
  54     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
  55     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices
  56   };
  57
  58   /**
  59    * @brief An enumeration of properties belonging to the TableView class.
  60    *
  61    * LayoutRows: set the height of the rows.
  62    * It has the format as follows in script:
  63    * @code
  64    * "layout-rows":
  65       {
  66         "0": { "policy": "fixed", "value": 40 },       //@see SetFixedHight
  67         "2": { "policy": "relative", "value": 0.33 }   //@see SetRelativeHeight
  68       }
  69    * @endcode
  70    *
  71    * LayoutColumns: set the height of the rows.
  72    * It has the format as follows in script:
  73    * @code
  74    * "layout-columns":
  75       {
  76         "0": { "policy": "fixed", "value": 40 },       //@see SetFixedWidth
  77         "2": { "policy": "relative", "value": 0.33 }   //@see SetRelativeWidth
  78       }
  79    * @endcode
  80    */
  81   struct Property
  82   {
  83     enum
  84     {
  85       ROWS = PROPERTY_START_INDEX, ///< name "rows",           type unsigned int
  86       COLUMNS,                     ///< name "columns",        type unsigned int
  87       CELL_PADDING,                ///< name "cell-padding",   type Vector2
  88       LAYOUT_ROWS,                 ///< name "layout-rows",    type Map
  89       LAYOUT_COLUMNS,              ///< name "layout-columns", type Map
  90     };
  91   };
  92
  93   // Custom properties for where to put the actor, these properties should be registered to the child which would be added to the table
  94   static const std::string CELL_INDICES_PROPERTY_NAME;           ///< Property, name "cell-indices", type Vector2
  95   static const std::string ROW_SPAN_PROPERTY_NAME;               ///< Property, name "row-span",     type float (Currently builder is unable to differentiate integer and float from Json string)
  96   static const std::string COLUMN_SPAN_PROPERTY_NAME;            ///< Property, name "column-span",  type float (Currently builder is unable to differentiate integer and float from Json string)
  97
  98   /**
  99    * @brief Describes how the size of a row / column been set
 100    */
 101   enum LayoutPolicy
 102   {
 103     FIXED,      ///< Fixed with the given value.
 104     RELATIVE,   ///< Calculated as percentage of the remainder after subtracting Padding and Fixed height/width
 105     FILL        ///< Get the remainder of the 100% (after subtracting Padding, Fixed and Relative height/ width) divided evenly between 'fill' rows/columns
 106   };
 107
 108   /**
 109    * Structure to specify layout position for child actor
 110    */
 111   struct CellPosition
 112   {
 113     /**
 114      * Constructor to initialise values to defaults for convenience
 115      */
 116     CellPosition( unsigned int rowIndex = 0, unsigned int columnIndex = 0,
 117                     unsigned int rowSpan = 1, unsigned int columnSpan = 1 )
 118     : rowIndex( rowIndex ), columnIndex( columnIndex ),
 119       rowSpan( rowSpan ), columnSpan( columnSpan )
 120     { }
 121
 122     unsigned int rowIndex;
 123     unsigned int columnIndex;
 124     unsigned int rowSpan;
 125     unsigned int columnSpan;
 126   };
 127
 128   /**
 129    * Create a TableView handle; this can be initialised with TableView::New()
 130    * Calling member functions with an uninitialised handle is not allowed.
 131    */
 132   TableView();
 133
 134   /**
 135    * Copy constructor. Creates another handle that points to the same real object
 136    * @param handle to copy from
 137    */
 138   TableView( const TableView& handle );
 139
 140   /**
 141    * Assignment operator. Changes this handle to point to another real object
 142    */
 143   TableView& operator=( const TableView& handle );
 144
 145   /**
 146    * @brief Destructor
 147    *
 148    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 149    */
 150   ~TableView();
 151
 152   /**
 153    * Create the TableView control.
 154    * @param[in] initialRows for the table
 155    * @param[in] initialColumns for the table
 156    * @return A handle to the TableView control.
 157    */
 158   static TableView New( unsigned int initialRows, unsigned int initialColumns );
 159
 160   /**
 161    * Downcast an Object handle to TableView. If handle points to a TableView the
 162    * downcast produces valid handle. If not the returned handle is left uninitialized.
 163    * @param[in] handle Handle to an object
 164    * @return handle to a TableView or an uninitialized handle
 165    */
 166   static TableView DownCast( BaseHandle handle );
 167
 168   /**
 169    * Adds a child to the table
 170    * If the row or column index is outside the table, the table gets resized bigger
 171    * @pre The child actor has been initialized.
 172    * @param[in] child to add
 173    * @param[in] position for the child
 174    * @return true if the addition succeeded, false if the cell is already occupied
 175    */
 176   bool AddChild( Actor child, CellPosition position );
 177
 178   /**
 179    * Returns a child from the given layout position
 180    * Note! if there is no child in this position this method returns an uninitialized
 181    * Actor handle
 182    * @param[in] position in the table
 183    * @return child that was in the cell or an uninitialized handle
 184    */
 185   Actor GetChildAt( CellPosition position );
 186
 187   /**
 188    * Removes a child from the given layout position
 189    * Note! if there is no child in this position this method does nothing
 190    * @param[in] position for the child to remove
 191    * @return child that was removed or an uninitialized handle
 192    */
 193   Actor RemoveChildAt( CellPosition position );
 194
 195   /**
 196    * Finds the childs layout position
 197    * @param[in] child to search for
 198    * @param[out] position for the child
 199    * @return true if the child was included in this TableView
 200    */
 201   bool FindChildPosition( Actor child, CellPosition& position );
 202
 203   /**
 204    * Insert a new row to given index
 205    * @param [in] rowIndex of the new row
 206    */
 207   void InsertRow( unsigned int rowIndex );
 208
 209   /**
 210    * Delete a row from given index
 211    * Removed elements are deleted
 212    * @param [in] rowIndex of the row to delete
 213    */
 214   void DeleteRow( unsigned int rowIndex );
 215
 216   /**
 217    * Delete a row from given index
 218    * @param [in] rowIndex of the row to delete
 219    * @param [out] removed elements
 220    */
 221   void DeleteRow( unsigned int rowIndex, std::vector<Actor>& removed );
 222
 223   /**
 224    * Insert a new column to given index
 225    * @param [in] columnIndex of the new column
 226    */
 227   void InsertColumn( unsigned int columnIndex );
 228
 229   /**
 230    * Delete a column from given index.
 231    * Removed elements are deleted
 232    * @param [in] columnIndex of the column to delete
 233    */
 234   void DeleteColumn( unsigned int columnIndex );
 235
 236   /**
 237    * Delete a column from given index
 238    * @param [in] columnIndex of the column to delete
 239    * @param [out] removed elements
 240    */
 241   void DeleteColumn( unsigned int columnIndex, std::vector<Actor>& removed );
 242
 243   /**
 244    * Resize the TableView. Note! if the new size is smaller than old,
 245    * superfluous actors get removed. If you want to relayout removed children,
 246    * use the variant that returns the removed Actors and reinsert them into the table
 247    * If an actor spans to a removed row or column it gets removed from the table
 248    * @param[in] rows for the table
 249    * @param[in] columns for the table
 250    */
 251   void Resize( unsigned int rows, unsigned int columns );
 252
 253   /**
 254    * Resize the TableView. Note! if the new size is smaller than old,
 255    * superfluous actors get removed.
 256    * If an actor spans to a removed row or column it gets removed from the table
 257    * @param[in] rows for the table
 258    * @param[in] columns for the table
 259    * @param[out] removed actor handles
 260    */
 261   void Resize( unsigned int rows, unsigned int columns, std::vector<Actor>& removed );
 262
 263   /**
 264    * Set horizontal and vertical padding between cells
 265    * @param[in] padding width and height
 266    */
 267   void SetCellPadding( Size padding );
 268
 269   /**
 270    * @return the current padding as width and height
 271    */
 272   Size GetCellPadding();
 273
 274   /**
 275    * @brief Specify this row as fitting its height to its children
 276    *
 277    * @param[in] rowIndex The row to set
 278    */
 279   void SetFitHeight( unsigned int rowIndex );
 280
 281   /**
 282    * @brief Is the row a fit row
 283    *
 284    * @param[in] rowIndex The row to check
 285    * @return Return true if the row is fit
 286    */
 287   bool IsFitHeight( unsigned int rowIndex ) const;
 288
 289   /**
 290    * @brief Specify this column as fitting its width to its children
 291    *
 292    * @param[in] columnIndex The column to set
 293    */
 294   void SetFitWidth( unsigned int columnIndex );
 295
 296   /**
 297    * @brief Is the column a fit column
 298    *
 299    * @param[in] columnIndex The column to check
 300    * @return Return true if the column is fit
 301    */
 302   bool IsFitWidth( unsigned int columnIndex ) const;
 303
 304   /**
 305    * Sets a row to have fixed height
 306    * Setting a fixed height of 0 has no effect
 307    * @pre The row rowIndex must exist.
 308    * @param rowIndex for row with fixed height
 309    * @param height in world coordinate units
 310    */
 311   void SetFixedHeight( unsigned int rowIndex, float height );
 312
 313   /**
 314    * Gets a row's fixed height.
 315    * Note! The returned value is valid if it has been set before.
 316    * @pre The row rowIndex must exist.
 317    * @return height in world coordinate units.
 318    */
 319   float GetFixedHeight( unsigned int rowIndex ) const;
 320
 321   /**
 322    * Sets a row to have relative height. Relative height means percentage of
 323    * the remainder of the table height after subtracting Padding and Fixed height rows
 324    * Setting a relative height of 0 has no effect
 325    * @pre The row rowIndex must exist.
 326    * @param rowIndex for row with relative height
 327    * @param heightPercentage between 0.0f and 1.0f
 328    */
 329   void SetRelativeHeight( unsigned int rowIndex, float heightPercentage );
 330
 331   /**
 332    * Gets a row's relative height.
 333    * Note! The returned value is valid if it has been set before.
 334    * @pre The row rowIndex must exist.
 335    * @return height in percentage units, between 0.0f and 1.0f.
 336    */
 337   float GetRelativeHeight( unsigned int rowIndex ) const;
 338
 339   /**
 340    * Sets a column to have fixed width
 341    * Setting a fixed width of 0 has no effect
 342    * @pre The column columnIndex must exist.
 343    * @param columnIndex for column with fixed width
 344    * @param width in world coordinate units
 345    */
 346   void SetFixedWidth( unsigned int columnIndex, float width );
 347
 348   /**
 349    * Gets a column's fixed width.
 350    * Note! The returned value is valid if it has been set before.
 351    * @pre The column columnIndex must exist.
 352    * @return width in world coordinate units.
 353    */
 354   float GetFixedWidth( unsigned int columnIndex ) const;
 355
 356   /**
 357    * Sets a column to have relative width. Relative width means percentage of
 358    * the remainder of table width after subtracting Padding and Fixed width columns
 359    * Setting a relative width of 0 has no effect
 360    * @pre The column columnIndex must exist.
 361    * @param columnIndex for column with fixed width
 362    * @param widthPercentage between 0.0f and 1.0f
 363    */
 364   void SetRelativeWidth( unsigned int columnIndex, float widthPercentage );
 365
 366   /**
 367    * Gets a column's relative width.
 368    * Note! The returned value is valid if it has been set before.
 369    * @pre The column columnIndex must exist.
 370    * @return width in percentage units, between 0.0f and 1.0f.
 371    */
 372   float GetRelativeWidth( unsigned int columnIndex ) const;
 373
 374   /**
 375    * @return the amount of rows in the table
 376    */
 377   unsigned int GetRows();
 378
 379   /**
 380    * @return the amount of columns in the table
 381    */
 382   unsigned int GetColumns();
 383
 384   /**
 385    * @brief Set the alignment on a cell
 386    *
 387    * @param[in] position The cell to set alignment on
 388    * @param[in] horizontal The horizontal alignment
 389    * @param[in] vertical The vertical alignment
 390    */
 391   void SetCellAlignment( CellPosition position, HorizontalAlignment::Type horizontal, VerticalAlignment::Type vertical );
 392
 393 public: // Not intended for application developers
 394
 395   /**
 396    * Creates a handle using the Toolkit::Internal implementation.
 397    * @param[in]  implementation  The Control implementation.
 398    */
 399   DALI_INTERNAL TableView(Internal::TableView& implementation);
 400
 401   /**
 402    * Allows the creation of this Control from an Internal::CustomActor pointer.
 403    * @param[in]  internal  A pointer to the internal CustomActor.
 404    */
 405   explicit DALI_INTERNAL TableView( Dali::Internal::CustomActor* internal );
 406 };
 407
 408 } // namespace Toolkit
 409
 410 } // namespace Dali
 411
 412 #endif // __DALI_TOOLKIT_TABLE_VIEW_H__