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