base/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) 2014 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 // INTERNAL INCLUDES
  22 #include <dali/public-api/common/dali-vector.h>
  23 #include <dali-toolkit/public-api/controls/control.h>
  24
  25 namespace Dali DALI_IMPORT_API
  26 {
  27
  28 namespace Toolkit
  29 {
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33 class TableView;
  34 }
  35
  36 /**
  37  * TableView is a layout container for aligning child actors in a grid like layout.
  38  * TableView constrains the x and y position and width and height of the child actors.
  39  * z position and depth are left intact so that 3D model actors can also be laid out
  40  * in a grid without loosing their depth scaling.
  41  */
  42 class TableView : public Control
  43 {
  44 public:
  45
  46   /**
  47    * Structure to specify layout position for child actor
  48    */
  49   struct CellPosition
  50   {
  51     /**
  52      * Constructor to initialise values to defaults for convenience
  53      */
  54     CellPosition( unsigned int rowIndex = 0, unsigned int columnIndex = 0,
  55                     unsigned int rowSpan = 1, unsigned int columnSpan = 1 )
  56     : rowIndex( rowIndex ), columnIndex( columnIndex ),
  57       rowSpan( rowSpan ), columnSpan( columnSpan )
  58     { }
  59
  60     unsigned int rowIndex;
  61     unsigned int columnIndex;
  62     unsigned int rowSpan;
  63     unsigned int columnSpan;
  64   };
  65
  66   /**
  67    * Create a TableView handle; this can be initialised with TableView::New()
  68    * Calling member functions with an uninitialised handle is not allowed.
  69    */
  70   TableView();
  71
  72   /**
  73    * Copy constructor. Creates another handle that points to the same real object
  74    * @param handle to copy from
  75    */
  76   TableView( const TableView& handle );
  77
  78   /**
  79    * Assignment operator. Changes this handle to point to another real object
  80    */
  81   TableView& operator=( const TableView& handle );
  82
  83   /**
  84    * @brief Destructor
  85    *
  86    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  87    */
  88   ~TableView();
  89
  90   /**
  91    * Create the TableView control.
  92    * @param[in] initialRows for the table
  93    * @param[in] initialColumns for the table
  94    * @return A handle to the TableView control.
  95    */
  96   static TableView New( unsigned int initialRows, unsigned int initialColumns );
  97
  98   /**
  99    * Downcast an Object handle to TableView. If handle points to a TableView the
 100    * downcast produces valid handle. If not the returned handle is left uninitialized.
 101    * @param[in] handle Handle to an object
 102    * @return handle to a TableView or an uninitialized handle
 103    */
 104   static TableView DownCast( BaseHandle handle );
 105
 106   /**
 107    * Adds a child to the table
 108    * If the row or column index is outside the table, the table gets resized bigger
 109    * @pre The child actor has been initialized.
 110    * @param[in] child to add
 111    * @param[in] position for the child
 112    * @return true if the addition succeeded, false if the cell is already occupied
 113    */
 114   bool AddChild( Actor child, CellPosition position );
 115
 116   /**
 117    * Returns a child from the given layout position
 118    * Note! if there is no child in this position this method returns an uninitialized
 119    * Actor handle
 120    * @param[in] position in the table
 121    * @return child that was in the cell or an uninitialized handle
 122    */
 123   Actor GetChildAt( CellPosition position );
 124
 125   /**
 126    * Removes a child from the given layout position
 127    * Note! if there is no child in this position this method does nothing
 128    * @param[in] position for the child to remove
 129    * @return child that was removed or an uninitialized handle
 130    */
 131   Actor RemoveChildAt( CellPosition position );
 132
 133   /**
 134    * Finds the childs layout position
 135    * @param[in] child to search for
 136    * @param[out] position for the child
 137    * @return true if the child was included in this TableView
 138    */
 139   bool FindChildPosition( Actor child, CellPosition& position );
 140
 141   /**
 142    * Insert a new row to given index
 143    * @param [in] rowIndex of the new row
 144    */
 145   void InsertRow( unsigned int rowIndex );
 146
 147   /**
 148    * Delete a row from given index
 149    * Removed elements are deleted
 150    * @param [in] rowIndex of the row to delete
 151    */
 152   void DeleteRow( unsigned int rowIndex );
 153
 154   /**
 155    * Delete a row from given index
 156    * @param [in] rowIndex of the row to delete
 157    * @param [out] removed elements
 158    */
 159   void DeleteRow( unsigned int rowIndex, std::vector<Actor>& removed );
 160
 161   /**
 162    * Insert a new column to given index
 163    * @param [in] columnIndex of the new column
 164    */
 165   void InsertColumn( unsigned int columnIndex );
 166
 167   /**
 168    * Delete a column from given index.
 169    * Removed elements are deleted
 170    * @param [in] columnIndex of the column to delete
 171    */
 172   void DeleteColumn( unsigned int columnIndex );
 173
 174   /**
 175    * Delete a column from given index
 176    * @param [in] columnIndex of the column to delete
 177    * @param [out] removed elements
 178    */
 179   void DeleteColumn( unsigned int columnIndex, std::vector<Actor>& removed );
 180
 181   /**
 182    * Resize the TableView. Note! if the new size is smaller than old,
 183    * superfluous actors get removed. If you want to relayout removed children,
 184    * use the variant that returns the removed Actors and reinsert them into the table
 185    * If an actor spans to a removed row or column it gets removed from the table
 186    * @param[in] rows for the table
 187    * @param[in] columns for the table
 188    */
 189   void Resize( unsigned int rows, unsigned int columns );
 190
 191   /**
 192    * Resize the TableView. Note! if the new size is smaller than old,
 193    * superfluous actors get removed.
 194    * If an actor spans to a removed row or column it gets removed from the table
 195    * @param[in] rows for the table
 196    * @param[in] columns for the table
 197    * @param[out] removed actor handles
 198    */
 199   void Resize( unsigned int rows, unsigned int columns, std::vector<Actor>& removed );
 200
 201   /**
 202    * Set horizontal and vertical padding between cells
 203    * @param[in] padding width and height
 204    */
 205   void SetCellPadding( Size padding );
 206
 207   /**
 208    * @return the current padding as width and height
 209    */
 210   Size GetCellPadding();
 211
 212   /**
 213    * Sets a row to have fixed height
 214    * Setting a fixed height of 0 has no effect
 215    * @pre The row rowIndex must exist.
 216    * @param rowIndex for row with fixed height
 217    * @param height in world coordinate units
 218    */
 219   void SetFixedHeight( unsigned int rowIndex, float height );
 220
 221   /**
 222    * Gets a row's fixed height.
 223    * Note! The returned value is valid if it has been set before.
 224    * @pre The row rowIndex must exist.
 225    * @return height in world coordinate units.
 226    */
 227   float GetFixedHeight( unsigned int rowIndex ) const;
 228
 229   /**
 230    * Sets a row to have relative height. Relative height means percentage of
 231    * the remainder of the table height after subtracting Padding and Fixed height rows
 232    * Setting a relative height of 0 has no effect
 233    * @pre The row rowIndex must exist.
 234    * @param rowIndex for row with relative height
 235    * @param heightPercentage between 0.0f and 1.0f
 236    */
 237   void SetRelativeHeight( unsigned int rowIndex, float heightPercentage );
 238
 239   /**
 240    * Gets a row's relative height.
 241    * Note! The returned value is valid if it has been set before.
 242    * @pre The row rowIndex must exist.
 243    * @return height in percentage units, between 0.0f and 1.0f.
 244    */
 245   float GetRelativeHeight( unsigned int rowIndex ) const;
 246
 247   /**
 248    * Sets a column to have fixed width
 249    * Setting a fixed width of 0 has no effect
 250    * @pre The column columnIndex must exist.
 251    * @param columnIndex for column with fixed width
 252    * @param width in world coordinate units
 253    */
 254   void SetFixedWidth( unsigned int columnIndex, float width );
 255
 256   /**
 257    * Gets a column's fixed width.
 258    * Note! The returned value is valid if it has been set before.
 259    * @pre The column columnIndex must exist.
 260    * @return width in world coordinate units.
 261    */
 262   float GetFixedWidth( unsigned int columnIndex ) const;
 263
 264   /**
 265    * Sets a column to have relative width. Relative width means percentage of
 266    * the remainder of table width after subtracting Padding and Fixed width columns
 267    * Setting a relative width of 0 has no effect
 268    * @pre The column columnIndex must exist.
 269    * @param columnIndex for column with fixed width
 270    * @param widthPercentage between 0.0f and 1.0f
 271    */
 272   void SetRelativeWidth( unsigned int columnIndex, float widthPercentage );
 273
 274   /**
 275    * Gets a column's relative width.
 276    * Note! The returned value is valid if it has been set before.
 277    * @pre The column columnIndex must exist.
 278    * @return width in percentage units, between 0.0f and 1.0f.
 279    */
 280   float GetRelativeWidth( unsigned int columnIndex ) const;
 281
 282   /**
 283    * Sets the layout animation duration for add, remove and relayout
 284    * @param duration for the layout animations
 285    * @note The default duration is 0.0f.
 286    */
 287   void SetLayoutAnimationDuration( float duration );
 288
 289   /**
 290    * Gets the layout animation duration for add, remove and relayout
 291    * @return duration for the layout animations
 292    */
 293   float GetLayoutAnimationDuration();
 294
 295   /**
 296    * @return the amount of rows in the table
 297    */
 298   unsigned int GetRows();
 299
 300   /**
 301    * @return the amount of columns in the table
 302    */
 303   unsigned int GetColumns();
 304
 305 public: // Not intended for application developers
 306
 307   /**
 308    * Creates a handle using the Toolkit::Internal implementation.
 309    * @param[in]  implementation  The Control implementation.
 310    */
 311   TableView(Internal::TableView& implementation);
 312
 313   /**
 314    * Allows the creation of this Control from an Internal::CustomActor pointer.
 315    * @param[in]  internal  A pointer to the internal CustomActor.
 316    */
 317   TableView( Dali::Internal::CustomActor* internal );
 318 };
 319
 320 } // namespace Toolkit
 321
 322 } // namespace Dali
 323
 324 #endif // __DALI_TOOLKIT_TABLE_VIEW_H__