1 #ifndef __DALI_TOOLKIT_TABLE_VIEW_H__
2 #define __DALI_TOOLKIT_TABLE_VIEW_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 // http://floralicense.org/license/
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.
21 #include <dali/public-api/common/dali-vector.h>
22 #include <dali-toolkit/public-api/controls/control.h>
24 namespace Dali DALI_IMPORT_API
30 namespace Internal DALI_INTERNAL
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.
41 class TableView : public Control
46 * Structure to specify layout position for child actor
51 * Constructor to initialise values to defaults for convenience
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 )
59 unsigned int rowIndex;
60 unsigned int columnIndex;
62 unsigned int columnSpan;
66 * Create a TableView handle; this can be initialised with TableView::New()
67 * Calling member functions with an uninitialised handle is not allowed.
72 * Copy constructor. Creates another handle that points to the same real object
73 * @param handle to copy from
75 TableView( const TableView& handle );
78 * Assignment operator. Changes this handle to point to another real object
80 TableView& operator=( const TableView& handle );
84 * Dali::Object derived classes typically do not contain member data.
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.
94 static TableView New( unsigned int initialRows, unsigned int initialColumns );
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
102 static TableView DownCast( BaseHandle handle );
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
112 bool AddChild( Actor child, CellPosition position );
115 * Returns a child from the given layout position
116 * Note! if there is no child in this position this method returns an uninitialized
118 * @param[in] position in the table
119 * @return child that was in the cell or an uninitialized handle
121 Actor GetChildAt( CellPosition position );
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
129 Actor RemoveChildAt( CellPosition position );
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
137 bool FindChildPosition( Actor child, CellPosition& position );
140 * Insert a new row to given index
141 * @param [in] rowIndex of the new row
143 void InsertRow( unsigned int rowIndex );
146 * Delete a row from given index
147 * Removed elements are deleted
148 * @param [in] rowIndex of the row to delete
150 void DeleteRow( unsigned int rowIndex );
153 * Delete a row from given index
154 * @param [in] rowIndex of the row to delete
155 * @param [out] removed elements
157 void DeleteRow( unsigned int rowIndex, std::vector<Actor>& removed );
160 * Insert a new column to given index
161 * @param [in] columnIndex of the new column
163 void InsertColumn( unsigned int columnIndex );
166 * Delete a column from given index.
167 * Removed elements are deleted
168 * @param [in] columnIndex of the column to delete
170 void DeleteColumn( unsigned int columnIndex );
173 * Delete a column from given index
174 * @param [in] columnIndex of the column to delete
175 * @param [out] removed elements
177 void DeleteColumn( unsigned int columnIndex, std::vector<Actor>& removed );
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
187 void Resize( unsigned int rows, unsigned int columns );
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
197 void Resize( unsigned int rows, unsigned int columns, std::vector<Actor>& removed );
200 * Set horizontal and vertical padding between cells
201 * @param[in] padding width and height
203 void SetCellPadding( Size padding );
206 * @return the current padding as width and height
208 Size GetCellPadding();
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
217 void SetFixedHeight( unsigned int rowIndex, float height );
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.
225 float GetFixedHeight( unsigned int rowIndex ) const;
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
235 void SetRelativeHeight( unsigned int rowIndex, float heightPercentage );
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.
243 float GetRelativeHeight( unsigned int rowIndex ) const;
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
252 void SetFixedWidth( unsigned int columnIndex, float width );
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.
260 float GetFixedWidth( unsigned int columnIndex ) const;
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
270 void SetRelativeWidth( unsigned int columnIndex, float widthPercentage );
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.
278 float GetRelativeWidth( unsigned int columnIndex ) const;
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.
285 void SetLayoutAnimationDuration( float duration );
288 * Gets the layout animation duration for add, remove and relayout
289 * @return duration for the layout animations
291 float GetLayoutAnimationDuration();
294 * @return the amount of rows in the table
296 unsigned int GetRows();
299 * @return the amount of columns in the table
301 unsigned int GetColumns();
303 public: // Not intended for application developers
306 * Creates a handle using the Toolkit::Internal implementation.
307 * @param[in] implementation The Control implementation.
309 TableView(Internal::TableView& implementation);
312 * Allows the creation of this Control from an Internal::CustomActor pointer.
313 * @param[in] internal A pointer to the internal CustomActor.
315 TableView( Dali::Internal::CustomActor* internal );
318 } // namespace Toolkit
322 #endif // __DALI_TOOLKIT_TABLE_VIEW_H__