2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0/
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FUiCtrlGroupContainer.h
20 * @brief This is the header file for the %GroupContainer class.
22 * This header file contains the declarations of the %GroupContainer class.
24 #ifndef _FUI_CTRL_GROUP_CONTAINER_H_
25 #define _FUI_CTRL_GROUP_CONTAINER_H_
27 #include <FBaseTypes.h>
28 #include <FUiContainer.h>
30 namespace Tizen { namespace Ui { namespace Controls
33 * @class GroupContainer
34 * @brief This class defines common behavior for a %GroupContainer container.
38 * The %GroupContainer class displays child controls in grouping look. It is a concrete implementation of the Container class.
41 class _OSP_EXPORT_ GroupContainer
42 : public Tizen::Ui::Container
46 * The object is not fully constructed after this constructor is called. @n
47 * For full construction, the %Construct() method must be called right after calling this constructor.
54 * This polymorphic destructor should be overridden if required. @n
55 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
59 virtual ~GroupContainer(void);
62 * Initializes this instance of %GroupContainer with the specified parameters.
66 * @return An error code
67 * @param[in] rect The location and size of the %GroupContainer control as an instance of Rectangle
68 * @param[in] rowCount The number of rows
69 * @param[in] columnCount The number of columns
70 * @param[in] lineWidth Width of the grid lines to draw
71 * @exception E_SUCCESS The method is successful.
72 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
73 * The width or height of @c rect or @c rowCount or @c columnnCount is negative or the value of @c lineWidth is @c 0 or negative.
74 * @exception E_OPERATION_FAILED The operation has failed.
75 * @remarks The available space for controls is less than the width or height of the container by the total width or height of the grid lines.
77 result Construct(const Tizen::Graphics::Rectangle& rect, int rowCount, int columnCount, int lineWidth = 1);
80 * Initializes this instance of %GroupContainer with the specified parameters.
84 * @return An error code
85 * @param[in] rect The location and size of the %GroupContainer control as an instance of FloatRectangle
86 * @param[in] rowCount The number of rows
87 * @param[in] columnCount The number of columns
88 * @param[in] lineWidth Width of the grid lines to draw
89 * @exception E_SUCCESS The method is successful.
90 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
91 * The width or height of @c rect or @c rowCount or @c columnnCount is negative or the value of @c lineWidth is @c 0 or negative.
92 * @exception E_OPERATION_FAILED The operation has failed.
93 * @remarks The available space for controls is less than the width or height of the container by the total width or height of the grid lines.
95 result Construct(const Tizen::Graphics::FloatRectangle& rect, int rowCount, int columnCount, float lineWidth = 1.0f);
98 * Adds a control at a specified row and column index.
102 * @return An error code
103 * @param[in] control The control to add to the container
104 * @param[in] rowIndex The row index of the cell
105 * @param[in] columnIndex The column index of the cell
106 * @exception E_SUCCESS The method is successful.
107 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
108 * @exception E_INVALID_ARG A specified input parameter @c control is invalid.
109 * @exception E_INVALID_OPERATION The cell specified by @c rowIndex and @c columnIndex is already bound to another control.
112 * - If a control is being added to the merged cells, the row index and column index of a representative cell should be given.
113 * - The control to add should be allocated in heap memory, and the ownership of the control is transferred to the platform.
115 result AddControlAt(Control& control, int rowIndex, int columnIndex);
118 * Gets the control at a specified cell index in the GroupContainer.
122 * @return The control at a specified index of the list, @n
123 * else @c null if the cell index is not valid or no control is added
124 * @param[in] rowIndex The row index of the cell
125 * @param[in] columnIndex The column index of the cell
126 * @exception E_SUCCESS The method is successful.
127 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
128 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
129 * @exception E_INVALID_OPERATION No control has been bound to the specified cell.
130 * @remarks When you get the control from the merged cell, the row index and column index of a representative cell should be given.
132 const Tizen::Ui::Control* GetControlAt(int rowIndex, int columnIndex) const;
135 * Gets the control at a specified cell index in the GroupContainer.
139 * @return The control at a specified index of the list, @n
140 * else @c null if the cell index is not valid or no control is added
141 * @param[in] rowIndex The row index of the cell
142 * @param[in] columnIndex The column index of the cell
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
145 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
146 * @exception E_INVALID_OPERATION No control has been bound to the specified cell.
147 * @remarks When you get the control from the merged cells, the row index and column index of a representative cell should be given.
149 Tizen::Ui::Control* GetControlAt(int rowIndex, int columnIndex);
152 * Removes a specified control from a specified row and column index
156 * @return An error code
157 * @param[in] rowIndex The row index of the control to remove
158 * @param[in] columnIndex The column index of the control to remove
159 * @exception E_SUCCESS The method is successful.
160 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
161 * @exception E_OPERATION_FAILED The operation has failed.
162 * @exception E_INVALID_OPERATION No control has been bound to the specified cell.
164 * - When you remove the control from the merged cell, the row index and column index of a representative cell should be given.
165 * - The removed child control is deleted from the memory. Before it is removed from the container, OnTerminating()
166 * of the child control is called.
167 * @see Tizen::Ui::Control::OnTerminating()
169 result RemoveControlAt (int rowIndex, int columnIndex);
172 * Sets the width of a column.
176 * @return An error code
177 * @param[in] columnIndex The column index
178 * @param[in] width The new width of the column
179 * @exception E_SUCCESS The method is successful.
180 * @exception E_OUT_OF_RANGE The specified @c columnIndex is greater than the number of elements or less than @c 0.
181 * @exception E_INVALID_ARG The specified @c width must be greater than or equal to @c 0.
184 result SetColumnWidth(int columnIndex, int width);
187 * Sets the width of a column.
191 * @return An error code
192 * @param[in] columnIndex The column index
193 * @param[in] width The new width of the column
194 * @exception E_SUCCESS The method is successful.
195 * @exception E_OUT_OF_RANGE The specified @c columnIndex is greater than the number of elements or less than @c 0.
196 * @exception E_INVALID_ARG The specified @c width must be greater than or equal to @c 0.0f.
199 result SetColumnWidth(int columnIndex, float width);
202 * Gets the width of a column.
206 * @return The width of the column
207 * @param[in] columnIndex The column index
208 * @exception E_SUCCESS The method is successful.
209 * @exception E_OUT_OF_RANGE The specified @c columnIndex is greater than the number of elements or less than @c 0.
211 int GetColumnWidth(int columnIndex) const;
214 * Gets the width of a column.
218 * @return The width of the column
219 * @param[in] columnIndex The column index
220 * @exception E_SUCCESS The method is successful.
221 * @exception E_OUT_OF_RANGE The specified @c columnIndex is greater than the number of elements or less than @c 0.
223 float GetColumnWidthF(int columnIndex) const;
226 * Sets the height of a row.
230 * @return An error code
231 * @param[in] rowIndex The row index
232 * @param[in] height The new height of the row
233 * @exception E_SUCCESS The method is successful.
234 * @exception E_OUT_OF_RANGE The specified @c rowIndex is greater than the number of elements or less than @c 0.
235 * @exception E_INVALID_ARG The specified @c height must be greater than or equal to @c 0.
238 result SetRowHeight(int rowIndex, int height);
241 * Sets the height of a row.
245 * @return An error code
246 * @param[in] rowIndex The row index
247 * @param[in] height The new height of the row
248 * @exception E_SUCCESS The method is successful.
249 * @exception E_OUT_OF_RANGE The specified @c rowIndex is greater than the number of elements or less than @c 0.
250 * @exception E_INVALID_ARG The specified @c height must be greater than or equal to @c 0.
253 result SetRowHeight(int rowIndex, float height);
256 * Gets the height of a row.
260 * @return The height of the row
261 * @param[in] rowIndex The row index
262 * @exception E_SUCCESS The method is successful.
263 * @exception E_OUT_OF_RANGE The specified @c rowIndex is greater than the number of elements or less than @c 0.
266 int GetRowHeight(int rowIndex) const;
269 * Gets the height of a row.
273 * @return The height of the row
274 * @param[in] rowIndex The row index
275 * @exception E_SUCCESS The method is successful.
276 * @exception E_OUT_OF_RANGE The specified @c rowIndex is greater than the number of elements or less than @c 0.
279 float GetRowHeightF(int rowIndex) const;
282 * Merges the cells for a given row and column index.
286 * @return An error code
287 * @param[in] rowStartIndex The start index of the row from which the merge happens
288 * @param[in] columnStartIndex The start index of the column from which the merge happens
289 * @param[in] rowCount The number of cells to merge along the row
290 * @param[in] columnCount The number of cells to merge along the column
291 * @exception E_SUCCESS The method is successful.
292 * @exception E_INVALID_ARG One or more cells in the specified range is(are) already merged.
293 * @exception E_OUT_OF_RANGE The specified @c rowStartIndex or @c columnStartIndex is greater than the number of elements or less than @c 0
295 * - When the cells are merged, the top-left cell will play the role of representative cell on behalf of merged cells.
296 * - To manipulate the merge cell, the row index and column index of the representative cell has to be given. Merging cells
297 * with the merged cell is allowed, but the newly merged cell should completely contain the all cells to merge.
299 result Merge(int rowStartIndex, int columnStartIndex, int rowCount, int columnCount);
302 * Enables/disables resizing of the control in a cell
306 * @return An error code
307 * @param[in] rowIndex The row index of the row in which the control is resized
308 * @param[in] columnIndex The column index of the column in which the control is resized
309 * @param[in] enable boolean value to enable or disable the resizing of control
310 * @exception E_SUCCESS The method is successful.
311 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
314 result SetChildResizingEnabled(int rowIndex, int columnIndex, bool enable);
317 * Sets the margin of a cell
321 * @return An error code
322 * @param[in] rowIndex The row index of the cell
323 * @param[in] columnIndex The column index of the cell
324 * @param[in] leftMargin The left margin
325 * @param[in] rightMargin The right margin
326 * @param[in] topMargin The top margin
327 * @param[in] bottomMargin The bottom margin
328 * @exception E_SUCCESS The method is successful.
329 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
330 * @exception E_INVALID_ARG The specified @c leftMargin or @c topMargin or @c rightMargin or @c bottomMargin must be greater than or equal to @c 0.
331 * @remarks The default margin value is @c 2.0f logical pixel.
333 result SetMargin(int rowIndex, int columnIndex, int leftMargin, int rightMargin, int topMargin, int bottomMargin);
336 * Sets the margin of a cell
340 * @return An error code
341 * @param[in] rowIndex The row index of the cell
342 * @param[in] columnIndex The column index of the cell
343 * @param[in] leftMargin The left margin
344 * @param[in] rightMargin The right margin
345 * @param[in] topMargin The top margin
346 * @param[in] bottomMargin The bottom margin
347 * @exception E_SUCCESS The method is successful.
348 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
349 * @exception E_INVALID_ARG The specified @c leftMargin or @c topMargin or @c rightMargin or @c bottomMargin must be greater than or equal to @c 0.0f.
350 * @remarks The default margin value is 2.0f logical pixel.
352 result SetMargin(int rowIndex, int columnIndex, float leftMargin, float rightMargin, float topMargin, float bottomMargin);
355 * Splits the merged cells
359 * @return An error code
360 * @param[in] rowIndex The row index of the representative cell of the merged cells
361 * @param[in] columnIndex The column index of the representative cell of the merged cells
362 * @exception E_SUCCESS The method is successful.
363 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
364 * @exception E_INVALID_ARG The specified row and column index are not those of the representative cell of the merged cells.
366 result Split(int rowIndex, int columnIndex);
369 * Gets the bounds of a specified cell.
373 * @return An instance of the Tizen::Graphics::Rectangle that represents the position of top-left corner,
374 * the width, and the height of the cell, @n else Rectangle(0, 0, -1, -1) if an error occurs
375 * @param[in] rowIndex The row index of the cell
376 * @param[in] columnIndex The column index of the cell
377 * @exception E_SUCCESS The method is successful.
378 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
380 Tizen::Graphics::Rectangle GetBoundsAt(int rowIndex, int columnIndex) const;
383 * Gets the bounds of a specified cell.
387 * @return An instance of the Tizen::Graphics::FloatRectangle that represents the position of top-left corner,
388 * the width, and the height of the cell, @n else Rectangle(0.0f, 0.0f, -1.0f, -1.0f) if an error occurs
389 * @param[in] rowIndex The row index of the cell
390 * @param[in] columnIndex The column index of the cell
391 * @exception E_SUCCESS The method is successful.
392 * @exception E_OUT_OF_RANGE The specified @c rowIndex or @c columnIndex is greater than the number of elements or less than @c 0.
394 Tizen::Graphics::FloatRectangle GetBoundsAtF(int rowIndex, int columnIndex) const;
397 * Enables/disables stretchable or shrinkable property of a column
401 * @return An error code
402 * @param[in] columnIndex The column index of the cell
403 * @param[in] stretchable boolean value to set stretchable or shrinkable property
404 * @exception E_SUCCESS The method is successful.
405 * @exception E_OUT_OF_RANGE The specified @c columnIndex is greater than the number of elements or less than @c 0.
407 result SetColumnStretchable(int columnIndex, bool stretchable);
410 * Checks whether the column is stretchable or shrinkable
414 * @return @c true if the column is stretchable or shrinkable
416 * @param[in] columnIndex The column index of the cell
417 * @exception E_SUCCESS The method is successful.
418 * @exception E_OUT_OF_RANGE The specified @c columnIndex is greater than the number of elements or less than @c 0.
420 bool IsColumnStretchable(int columnIndex) const;
423 * Enables/disables stretchable or shrinkable property of a row
427 * @return An error code
428 * @param[in] rowIndex The row index of the cell
429 * @param[in] stretchable boolean value to set stretchable or shrinkable property
430 * @exception E_SUCCESS The method is successful.
431 * @exception E_OUT_OF_RANGE The specified @c rowIndex is greater than the number of elements or less than @c 0.
433 result SetRowStretchable(int rowIndex, bool stretchable);
436 * Checks whether the row is stretchable or shrinkable
440 * @return @c true if the row is stretchable or shrinkable
442 * @param[in] rowIndex The row index of the cell
443 * @exception E_SUCCESS The method is successful.
444 * @exception E_OUT_OF_RANGE The specified @c rowIndex is greater than the number of elements or less than @c 0.
446 bool IsRowStretchable(int rowIndex) const;
449 * Gets the background color of the %GroupContainer control.
453 * @return The background color, @n
454 * else RGBA(0, 0, 0, 0) if an error occurs
456 Tizen::Graphics::Color GetBackgroundColor(void) const;
459 * Sets the background color of the %GroupContainer control.
463 * @param[in] color The background color
465 void SetBackgroundColor(const Tizen::Graphics::Color& color);
468 * Gets the row and column divider line color of the %GroupContainer control.
472 * @return The row and column divider line color, @n
473 * else RGBA(0, 0, 0, 255) if line color is not set.
475 Tizen::Graphics::Color GetLineColor(void) const;
478 * Sets the row and column divider line color of the %GroupContainer control.
482 * @param[in] color The line color
484 void SetLineColor(const Tizen::Graphics::Color& color);
488 // This method is for internal use only. Using this method can cause behavioral, security-related,
489 // and consistency-related issues in the application.
491 // Following method is reserved and may change its name at any time without
496 virtual void GroupContainer_Reserved1(void) {}
499 // This method is for internal use only. Using this method can cause behavioral, security-related,
500 // and consistency-related issues in the application.
502 // Following method is reserved and may change its name at any time without
507 virtual void GroupContainer_Reserved2(void) {}
510 // This method is for internal use only. Using this method can cause behavioral, security-related,
511 // and consistency-related issues in the application.
513 // Following method is reserved and may change its name at any time without
518 virtual void GroupContainer_Reserved3(void) {}
521 friend class _GroupContainerImpl;
524 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
528 GroupContainer(const GroupContainer& rhs);
531 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
533 GroupContainer& operator =(const GroupContainer& rhs);
537 }}} //Tizen::Ui::Controls
539 #endif // _FUI_CTRL_GROUP_CONTAINER_H_