X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Ftable-view%2Ftable-view.h;h=c73d8d05b321adef1c075db81e53832a51c16cb1;hp=3f199a5c4d745b77242a57e989647de1c4d11986;hb=b694e7e2ae624e206e1548b1a863c554eb9cd4d7;hpb=1844e9a1b878629f4987aea536660e3a70962c8c diff --git a/dali-toolkit/public-api/controls/table-view/table-view.h b/dali-toolkit/public-api/controls/table-view/table-view.h index 3f199a5..c73d8d0 100644 --- a/dali-toolkit/public-api/controls/table-view/table-view.h +++ b/dali-toolkit/public-api/controls/table-view/table-view.h @@ -1,8 +1,8 @@ -#ifndef __DALI_TOOLKIT_TABLE_VIEW_H__ -#define __DALI_TOOLKIT_TABLE_VIEW_H__ +#ifndef DALI_TOOLKIT_TABLE_VIEW_H +#define DALI_TOOLKIT_TABLE_VIEW_H /* - * Copyright (c) 2015 Samsung Electronics Co., Ltd. + * Copyright (c) 2019 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -74,21 +74,21 @@ class TableView; * "url": "{DALI_IMAGE_DIR}gallery-small-1.jpg" * }, * "properties": { - * "cellIndex":[1,1], // property to specify the top-left cell this child occupies, if not set, the first available cell is used - * "rowSpan":3, // property to specify how many rows this child occupies, if not set, default value is 1 - * "columnSpan": 2, // property to specify how many columns this child occupies, if nor set, default value is 1 - * "cellHorizontalAlignment": "left", // property to specify how to align horizontally inside the cells, if not set, default value is 'left' - * "cellVerticalAlignment": "center" // property to specify how to align vertically inside the cells, if not set, default value is 'top' + * "cellIndex":[1,1], // Property to specify the top-left cell this child occupies, if not set, the first available cell is used + * "rowSpan":3, // Property to specify how many rows this child occupies, if not set, default value is 1 + * "columnSpan": 2, // Property to specify how many columns this child occupies, if nor set, default value is 1 + * "cellHorizontalAlignment": "left", // Property to specify how to align horizontally inside the cells, if not set, default value is 'left' + * "cellVerticalAlignment": "center" // Property to specify how to align vertically inside the cells, if not set, default value is 'top' * } * @endcode * @SINCE_1_0.0 */ -class DALI_IMPORT_API TableView : public Control +class DALI_TOOLKIT_API TableView : public Control { public: /** - * @brief The start and end property ranges for this control. + * @brief Enumeration for the start and end property ranges for this control. * @SINCE_1_0.0 */ enum PropertyRange @@ -101,7 +101,7 @@ public: }; /** - * @brief An enumeration of properties belonging to the TableView class. + * @brief Enumeration for the instance of properties belonging to the TableView class. * * LayoutRows: set the height of the rows. * It has the format as follows in script: @@ -128,6 +128,11 @@ public: */ struct Property { + /** + * @brief Enumeration for the instance of properties belonging to the TableView class. + * + * @SINCE_1_0.0 + */ enum { ROWS = PROPERTY_START_INDEX, ///< name "rows", type unsigned int @SINCE_1_0.0 @@ -139,11 +144,15 @@ public: }; /** - * @brief An enumeration of child properties belonging to the TableView class. + * @brief Enumeration for the instance of child properties belonging to the TableView class. * @SINCE_1_1.36 */ struct ChildProperty { + /** + * @brief Enumeration for the instance of child properties belonging to the TableView class. + * @SINCE_1_1.36 + */ enum { CELL_INDEX = CHILD_PROPERTY_START_INDEX, ///< name "cellIndex", The top-left cell this child occupies, if not set, the first available cell is used, type VECTOR2 @SINCE_1_1.36 @@ -155,7 +164,7 @@ public: }; /** - * @brief Describes how the size of a row / column been set + * @brief Enumeration for describing how the size of a row / column has been set. * @SINCE_1_0.0 */ enum LayoutPolicy @@ -167,14 +176,18 @@ public: }; /** - * @brief Structure to specify layout position for child actor + * @brief Structure to specify layout position for child actor. * @SINCE_1_0.0 */ struct CellPosition { /** - * @brief Constructor to initialise values to defaults for convenience + * @brief Constructor to initialise values to defaults for convenience. * @SINCE_1_0.0 + * @param[in] rowIndex The row index initialized + * @param[in] columnIndex The column index initialized + * @param[in] rowSpan The row span initialized + * @param[in] columnSpan The column span initialized */ CellPosition( unsigned int rowIndex = 0, unsigned int columnIndex = 0, unsigned int rowSpan = 1, unsigned int columnSpan = 1 ) @@ -189,27 +202,29 @@ public: }; /** - * @brief Create a TableView handle; this can be initialised with TableView::New() - * Calling member functions with an uninitialised handle is not allowed. + * @brief Creates a TableView handle; this can be initialized with TableView::New(). + * Calling member functions with an uninitialized handle is not allowed. * @SINCE_1_0.0 */ TableView(); /** - * @brief Copy constructor. Creates another handle that points to the same real object + * @brief Copy constructor. Creates another handle that points to the same real object. * @SINCE_1_0.0 - * @param handle to copy from + * @param[in] handle Handle to copy from */ TableView( const TableView& handle ); /** - * @brief Assignment operator. Changes this handle to point to another real object + * @brief Assignment operator. Changes this handle to point to another real object. * @SINCE_1_0.0 + * @param[in] handle Handle to an object + * @return A reference to this */ TableView& operator=( const TableView& handle ); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. * @SINCE_1_0.0 @@ -217,150 +232,149 @@ public: ~TableView(); /** - * @brief Create the TableView control. + * @brief Creates the TableView control. * @SINCE_1_0.0 * @param[in] initialRows for the table * @param[in] initialColumns for the table - * @return A handle to the TableView control. + * @return A handle to the TableView control */ static TableView New( unsigned int initialRows, unsigned int initialColumns ); /** - * @brief Downcast a handle to TableView handle. + * @brief Downcasts a handle to TableView handle. * - * If handle points to a TableView the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * If handle points to a TableView, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. * @SINCE_1_0.0 * @param[in] handle Handle to an object - * @return handle to a TableView or an uninitialized handle + * @return Handle to a TableView or an uninitialized handle */ static TableView DownCast( BaseHandle handle ); /** - * @brief Adds a child to the table - * If the row or column index is outside the table, the table gets resized bigger + * @brief Adds a child to the table. + * If the row or column index is outside the table, the table gets resized bigger. * @SINCE_1_0.0 - * @param[in] child to add - * @param[in] position for the child - * @return true if the addition succeeded, false if the cell is already occupied + * @param[in] child The child to add + * @param[in] position The position for the child + * @return @c true if the addition succeeded, @c false if the cell is already occupied * @pre The child actor has been initialized. */ bool AddChild( Actor child, CellPosition position ); /** - * @brief Returns a child from the given layout position + * @brief Returns a child from the given layout position. * @SINCE_1_0.0 - * @param[in] position in the table - * @return child that was in the cell or an uninitialized handle + * @param[in] position The position in the table + * @return Child that was in the cell or an uninitialized handle * @note If there is no child in this position this method returns an uninitialized. * Actor handle */ Actor GetChildAt( CellPosition position ); /** - * @brief Removes a child from the given layout position + * @brief Removes a child from the given layout position. * @SINCE_1_0.0 - * @param[in] position for the child to remove - * @return child that was removed or an uninitialized handle - * @note If there is no child in this position this method does nothing. + * @param[in] position The position for the child to remove + * @return Child that was removed or an uninitialized handle + * @note If there is no child in this position, this method does nothing. */ Actor RemoveChildAt( CellPosition position ); /** - * @brief Finds the childs layout position + * @brief Finds the child's layout position. * @SINCE_1_0.0 - * @param[in] child to search for - * @param[out] position for the child + * @param[in] child The child to search for + * @param[out] position The position for the child * @return true if the child was included in this TableView */ bool FindChildPosition( Actor child, CellPosition& position ); /** - * @brief Insert a new row to given index + * @brief Inserts a new row to given index. * @SINCE_1_0.0 - * @param [in] rowIndex of the new row + * @param[in] rowIndex The rowIndex of the new row */ void InsertRow( unsigned int rowIndex ); /** - * @brief Delete a row from given index - * Removed elements are deleted + * @brief Deletes a row from the given index. + * Removed elements are deleted. * @SINCE_1_0.0 - * @param [in] rowIndex of the row to delete + * @param[in] rowIndex The rowIndex of the row to delete */ void DeleteRow( unsigned int rowIndex ); /** - * @brief Delete a row from given index + * @brief Deletes a row from the given index. * @SINCE_1_0.0 - * @param [in] rowIndex of the row to delete - * @param [out] removed elements + * @param[in] rowIndex The rowIndex of the row to delete + * @param[out] removed The removed elements */ void DeleteRow( unsigned int rowIndex, std::vector& removed ); /** - * @brief Insert a new column to given index + * @brief Inserts a new column to the given index. * @SINCE_1_0.0 - * @param [in] columnIndex of the new column + * @param[in] columnIndex The columnIndex of the new column */ void InsertColumn( unsigned int columnIndex ); /** - * @brief Delete a column from given index. - * Removed elements are deleted + * @brief Deletes a column from the given index. + * Removed elements are deleted. * @SINCE_1_0.0 - * @param [in] columnIndex of the column to delete + * @param[in] columnIndex The columnIndex of the column to delete */ void DeleteColumn( unsigned int columnIndex ); /** - * @brief Delete a column from given index + * @brief Deletes a column from the given index. * @SINCE_1_0.0 - * @param [in] columnIndex of the column to delete - * @param [out] removed elements + * @param[in] columnIndex The columnIndex of the column to delete + * @param[out] removed The removed elements */ void DeleteColumn( unsigned int columnIndex, std::vector& removed ); /** - * @brief Resize the TableView. + * @brief Resizes the TableView. * @SINCE_1_0.0 - * @param[in] rows for the table - * @param[in] columns for the table + * @param[in] rows The rows for the table + * @param[in] columns The columns for the table * @note If the new size is smaller than old, * superfluous actors get removed. If you want to relayout removed children, * use the variant that returns the removed Actors and reinsert them into the table. - * If an actor spans to a removed row or column it gets removed from the table. + * If an actor spans to a removed row or column, it gets removed from the table. */ void Resize( unsigned int rows, unsigned int columns ); /** - * @brief Resize the TableView. + * @brief Resizes the TableView. * @SINCE_1_0.0 - * @param[in] rows for the table - * @param[in] columns for the table - * @param[out] removed actor handles - * @note If the new size is smaller than old, - * superfluous actors get removed. + * @param[in] rows The rows for the table + * @param[in] columns The columns for the table + * @param[out] removed The removed actor handles + * @note If the new size is smaller than old, superfluous actors get removed. * If an actor spans to a removed row or column it gets removed from the table. */ void Resize( unsigned int rows, unsigned int columns, std::vector& removed ); /** - * @brief Set horizontal and vertical padding between cells + * @brief Sets horizontal and vertical padding between cells. * @SINCE_1_0.0 - * @param[in] padding width and height + * @param[in] padding Width and height */ void SetCellPadding( Size padding ); /** - * @brief Get the current padding as width and height. + * @brief Gets the current padding as width and height. * @SINCE_1_0.0 - * @return the current padding as width and height + * @return The current padding as width and height */ Size GetCellPadding(); /** - * @brief Specify this row as fitting its height to its children + * @brief Specifies this row as fitting its height to its children. * * @SINCE_1_0.0 * @param[in] rowIndex The row to set @@ -368,7 +382,7 @@ public: void SetFitHeight( unsigned int rowIndex ); /** - * @brief Is the row a fit row + * @brief Checks if the row is a fit row. * * @SINCE_1_0.0 * @param[in] rowIndex The row to check @@ -377,7 +391,7 @@ public: bool IsFitHeight( unsigned int rowIndex ) const; /** - * @brief Specify this column as fitting its width to its children + * @brief Specifies this column as fitting its width to its children. * * @SINCE_1_0.0 * @param[in] columnIndex The column to set @@ -385,7 +399,7 @@ public: void SetFitWidth( unsigned int columnIndex ); /** - * @brief Is the column a fit column + * @brief Checks if the column is a fit column. * * @SINCE_1_0.0 * @param[in] columnIndex The column to check @@ -394,11 +408,11 @@ public: bool IsFitWidth( unsigned int columnIndex ) const; /** - * @brief Sets a row to have fixed height - * Setting a fixed height of 0 has no effect + * @brief Sets a row to have fixed height. + * Setting a fixed height of 0 has no effect. * @SINCE_1_0.0 - * @param rowIndex for row with fixed height - * @param height in world coordinate units + * @param rowIndex The rowIndex for row with fixed height + * @param height The height in world coordinate units * @pre The row rowIndex must exist. */ void SetFixedHeight( unsigned int rowIndex, float height ); @@ -406,7 +420,8 @@ public: /** * @brief Gets a row's fixed height. * @SINCE_1_0.0 - * @return height in world coordinate units. + * @param[in] rowIndex The row index with fixed height + * @return height The height in world coordinate units * @pre The row rowIndex must exist. * @note The returned value is valid if it has been set before. */ @@ -414,10 +429,10 @@ public: /** * @brief Sets a row to have relative height. Relative height means percentage of - * the remainder of the table height after subtracting Padding and Fixed height rows - * Setting a relative height of 0 has no effect + * the remainder of the table height after subtracting Padding and Fixed height rows. + * Setting a relative height of 0 has no effect. * @SINCE_1_0.0 - * @param rowIndex for row with relative height + * @param rowIndex The rowIndex for row with relative height * @param heightPercentage between 0.0f and 1.0f * @pre The row rowIndex must exist. */ @@ -426,18 +441,19 @@ public: /** * @brief Gets a row's relative height. * @SINCE_1_0.0 - * @return height in percentage units, between 0.0f and 1.0f. + * @param[in] rowIndex The row index with relative height + * @return Height in percentage units, between 0.0f and 1.0f * @pre The row rowIndex must exist. * @note The returned value is valid if it has been set before. */ float GetRelativeHeight( unsigned int rowIndex ) const; /** - * @brief Sets a column to have fixed width - * Setting a fixed width of 0 has no effect + * @brief Sets a column to have fixed width. + * Setting a fixed width of 0 has no effect. * @SINCE_1_0.0 - * @param columnIndex for column with fixed width - * @param width in world coordinate units + * @param columnIndex The columnIndex for column with fixed width + * @param width The width in world coordinate units * @pre The column columnIndex must exist. */ void SetFixedWidth( unsigned int columnIndex, float width ); @@ -445,7 +461,8 @@ public: /** * @brief Gets a column's fixed width. * @SINCE_1_0.0 - * @return width in world coordinate units. + * @param[in] columnIndex The column index with fixed width + * @return Width in world coordinate units * @pre The column columnIndex must exist. * @note The returned value is valid if it has been set before. */ @@ -453,11 +470,11 @@ public: /** * @brief Sets a column to have relative width. Relative width means percentage of - * the remainder of table width after subtracting Padding and Fixed width columns - * Setting a relative width of 0 has no effect + * the remainder of table width after subtracting Padding and Fixed width columns. + * Setting a relative width of 0 has no effect. * @SINCE_1_0.0 - * @param columnIndex for column with fixed width - * @param widthPercentage between 0.0f and 1.0f + * @param columnIndex The columnIndex for column with fixed width + * @param widthPercentage The widthPercentage between 0.0f and 1.0f * @pre The column columnIndex must exist. */ void SetRelativeWidth( unsigned int columnIndex, float widthPercentage ); @@ -465,7 +482,8 @@ public: /** * @brief Gets a column's relative width. * @SINCE_1_0.0 - * @return width in percentage units, between 0.0f and 1.0f. + * @param[in] columnIndex The column index with relative width + * @return Width in percentage units, between 0.0f and 1.0f * @pre The column columnIndex must exist. * @note The returned value is valid if it has been set before. */ @@ -474,44 +492,46 @@ public: /** * @brief Gets the amount of rows in the table. * @SINCE_1_0.0 - * @return the amount of rows in the table + * @return The amount of rows in the table */ unsigned int GetRows(); /** * @brief Gets the amount of columns in the table. * @SINCE_1_0.0 - * @return the amount of columns in the table + * @return The amount of columns in the table */ unsigned int GetColumns(); /** - * @brief Set the alignment on a cell. + * @brief Sets the alignment on a cell. * * Cells without calling this function have the default values of LEFT and TOP respectively. * * @SINCE_1_0.0 - * @param[in] position The cell to set alignment on. - * @param[in] horizontal The horizontal alignment. - * @param[in] vertical The vertical alignment. + * @param[in] position The cell to set alignment on + * @param[in] horizontal The horizontal alignment + * @param[in] vertical The vertical alignment */ void SetCellAlignment( CellPosition position, HorizontalAlignment::Type horizontal, VerticalAlignment::Type vertical ); public: // Not intended for application developers + /// @cond internal /** * @brief Creates a handle using the Toolkit::Internal implementation. * @SINCE_1_0.0 - * @param[in] implementation The Control implementation. + * @param[in] implementation The Control implementation */ DALI_INTERNAL TableView(Internal::TableView& implementation); /** * @brief Allows the creation of this Control from an Internal::CustomActor pointer. * @SINCE_1_0.0 - * @param[in] internal A pointer to the internal CustomActor. + * @param[in] internal A pointer to the internal CustomActor */ explicit DALI_INTERNAL TableView( Dali::Internal::CustomActor* internal ); + /// @endcond }; /** @@ -521,4 +541,4 @@ public: // Not intended for application developers } // namespace Dali -#endif // __DALI_TOOLKIT_TABLE_VIEW_H__ +#endif // DALI_TOOLKIT_TABLE_VIEW_H