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    * Virtual destructor.
  85    * Dali::Object derived classes typically do not contain member data.
  86    */
  87   virtual ~TableView();
  88
  89   /**
  90    * Create the TableView control.
  91    * @param[in] initialRows for the table
  92    * @param[in] initialColumns for the table
  93    * @return A handle to the TableView control.
  94    */
  95   static TableView New( unsigned int initialRows, unsigned int initialColumns );
  96
  97   /**
  98    * Downcast an Object handle to TableView. If handle points to a TableView the
  99    * downcast produces valid handle. If not the returned handle is left uninitialized.
 100    * @param[in] handle Handle to an object
 101    * @return handle to a TableView or an uninitialized handle
 102    */
 103   static TableView DownCast( BaseHandle handle );
 104
 105   /**
 106    * Adds a child to the table
 107    * If the row or column index is outside the table, the table gets resized bigger
 108    * @pre The child actor has been initialized.
 109    * @param[in] child to add
 110    * @param[in] position for the child
 111    * @return true if the addition succeeded, false if the cell is already occupied
 112    */
 113   bool AddChild( Actor child, CellPosition position );
 114
 115   /**
 116    * Returns a child from the given layout position
 117    * Note! if there is no child in this position this method returns an uninitialized
 118    * Actor handle
 119    * @param[in] position in the table
 120    * @return child that was in the cell or an uninitialized handle
 121    */
 122   Actor GetChildAt( CellPosition position );
 123
 124   /**
 125    * Removes a child from the given layout position
 126    * Note! if there is no child in this position this method does nothing
 127    * @param[in] position for the child to remove
 128    * @return child that was removed or an uninitialized handle
 129    */
 130   Actor RemoveChildAt( CellPosition position );
 131
 132   /**
 133    * Finds the childs layout position
 134    * @param[in] child to search for
 135    * @param[out] position for the child
 136    * @return true if the child was included in this TableView
 137    */
 138   bool FindChildPosition( Actor child, CellPosition& position );
 139
 140   /**
 141    * Insert a new row to given index
 142    * @param [in] rowIndex of the new row
 143    */
 144   void InsertRow( unsigned int rowIndex );
 145
 146   /**
 147    * Delete a row from given index
 148    * Removed elements are deleted
 149    * @param [in] rowIndex of the row to delete
 150    */
 151   void DeleteRow( unsigned int rowIndex );
 152
 153   /**
 154    * Delete a row from given index
 155    * @param [in] rowIndex of the row to delete
 156    * @param [out] removed elements
 157    */
 158   void DeleteRow( unsigned int rowIndex, std::vector<Actor>& removed );
 159
 160   /**
 161    * Insert a new column to given index
 162    * @param [in] columnIndex of the new column
 163    */
 164   void InsertColumn( unsigned int columnIndex );
 165
 166   /**
 167    * Delete a column from given index.
 168    * Removed elements are deleted
 169    * @param [in] columnIndex of the column to delete
 170    */
 171   void DeleteColumn( unsigned int columnIndex );
 172
 173   /**
 174    * Delete a column from given index
 175    * @param [in] columnIndex of the column to delete
 176    * @param [out] removed elements
 177    */
 178   void DeleteColumn( unsigned int columnIndex, std::vector<Actor>& removed );
 179
 180   /**
 181    * Resize the TableView. Note! if the new size is smaller than old,
 182    * superfluous actors get removed. If you want to relayout removed children,
 183    * use the variant that returns the removed Actors and reinsert them into the table
 184    * If an actor spans to a removed row or column it gets removed from the table
 185    * @param[in] rows for the table
 186    * @param[in] columns for the table
 187    */
 188   void Resize( unsigned int rows, unsigned int columns );
 189
 190   /**
 191    * Resize the TableView. Note! if the new size is smaller than old,
 192    * superfluous actors get removed.
 193    * If an actor spans to a removed row or column it gets removed from the table
 194    * @param[in] rows for the table
 195    * @param[in] columns for the table
 196    * @param[out] removed actor handles
 197    */
 198   void Resize( unsigned int rows, unsigned int columns, std::vector<Actor>& removed );
 199
 200   /**
 201    * Set horizontal and vertical padding between cells
 202    * @param[in] padding width and height
 203    */
 204   void SetCellPadding( Size padding );
 205
 206   /**
 207    * @return the current padding as width and height
 208    */
 209   Size GetCellPadding();
 210
 211   /**
 212    * Sets a row to have fixed height
 213    * Setting a fixed height of 0 has no effect
 214    * @pre The row rowIndex must exist.
 215    * @param rowIndex for row with fixed height
 216    * @param height in world coordinate units
 217    */
 218   void SetFixedHeight( unsigned int rowIndex, float height );
 219
 220   /**
 221    * Gets a row's fixed height.
 222    * Note! The returned value is valid if it has been set before.
 223    * @pre The row rowIndex must exist.
 224    * @return height in world coordinate units.
 225    */
 226   float GetFixedHeight( unsigned int rowIndex ) const;
 227
 228   /**
 229    * Sets a row to have relative height. Relative height means percentage of
 230    * the remainder of the table height after subtracting Padding and Fixed height rows
 231    * Setting a relative height of 0 has no effect
 232    * @pre The row rowIndex must exist.
 233    * @param rowIndex for row with relative height
 234    * @param heightPercentage between 0.0f and 1.0f
 235    */
 236   void SetRelativeHeight( unsigned int rowIndex, float heightPercentage );
 237
 238   /**
 239    * Gets a row's relative height.
 240    * Note! The returned value is valid if it has been set before.
 241    * @pre The row rowIndex must exist.
 242    * @return height in percentage units, between 0.0f and 1.0f.
 243    */
 244   float GetRelativeHeight( unsigned int rowIndex ) const;
 245
 246   /**
 247    * Sets a column to have fixed width
 248    * Setting a fixed width of 0 has no effect
 249    * @pre The column columnIndex must exist.
 250    * @param columnIndex for column with fixed width
 251    * @param width in world coordinate units
 252    */
 253   void SetFixedWidth( unsigned int columnIndex, float width );
 254
 255   /**
 256    * Gets a column's fixed width.
 257    * Note! The returned value is valid if it has been set before.
 258    * @pre The column columnIndex must exist.
 259    * @return width in world coordinate units.
 260    */
 261   float GetFixedWidth( unsigned int columnIndex ) const;
 262
 263   /**
 264    * Sets a column to have relative width. Relative width means percentage of
 265    * the remainder of table width after subtracting Padding and Fixed width columns
 266    * Setting a relative width of 0 has no effect
 267    * @pre The column columnIndex must exist.
 268    * @param columnIndex for column with fixed width
 269    * @param widthPercentage between 0.0f and 1.0f
 270    */
 271   void SetRelativeWidth( unsigned int columnIndex, float widthPercentage );
 272
 273   /**
 274    * Gets a column's relative width.
 275    * Note! The returned value is valid if it has been set before.
 276    * @pre The column columnIndex must exist.
 277    * @return width in percentage units, between 0.0f and 1.0f.
 278    */
 279   float GetRelativeWidth( unsigned int columnIndex ) const;
 280
 281   /**
 282    * Sets the layout animation duration for add, remove and relayout
 283    * @param duration for the layout animations
 284    * @note The default duration is 0.0f.
 285    */
 286   void SetLayoutAnimationDuration( float duration );
 287
 288   /**
 289    * Gets the layout animation duration for add, remove and relayout
 290    * @return duration for the layout animations
 291    */
 292   float GetLayoutAnimationDuration();
 293
 294   /**
 295    * @return the amount of rows in the table
 296    */
 297   unsigned int GetRows();
 298
 299   /**
 300    * @return the amount of columns in the table
 301    */
 302   unsigned int GetColumns();
 303
 304 public: // Not intended for application developers
 305
 306   /**
 307    * Creates a handle using the Toolkit::Internal implementation.
 308    * @param[in]  implementation  The Control implementation.
 309    */
 310   TableView(Internal::TableView& implementation);
 311
 312   /**
 313    * Allows the creation of this Control from an Internal::CustomActor pointer.
 314    * @param[in]  internal  A pointer to the internal CustomActor.
 315    */
 316   TableView( Dali::Internal::CustomActor* internal );
 317 };
 318
 319 } // namespace Toolkit
 320
 321 } // namespace Dali
 322
 323 #endif // __DALI_TOOLKIT_TABLE_VIEW_H__