[NUI] Add descriptions of Accessibility Interfaces

- The descriptions of Accessibility Interfaces were missed because of the urgent tasks. - Now, need to add them for the next steps. Signed-off-by: Seoyeon Kim <[email protected]>
imfine98 · Sep 5, 2023 · 90a7b6c · 90a7b6c
1 parent 6267126
commit 90a7b6c
Show file tree

Hide file tree

Showing 6 changed files with 296 additions and 4 deletions.
diff --git a/src/Tizen.NUI/src/public/Accessibility/IAtspiEditableText.cs b/src/Tizen.NUI/src/public/Accessibility/IAtspiEditableText.cs
@@ -1,5 +1,5 @@
 /*
- * Copyright(c) 2022 Samsung Electronics Co., Ltd.
+ * Copyright(c) 2023 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.
@@ -20,21 +20,53 @@
 
 namespace Tizen.NUI.Accessibility
 {
+    /// <summary>
+    /// Interface representing objects which can store editable texts.
+    /// </summary>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public interface IAtspiEditableText : IAtspiText
     {
+        /// <summary>
+        /// Copies text in range to system clipboard.
+        /// </summary>
+        /// <param name="startPosition"> The index of first character </param>
+        /// <param name="endPosition"> The index of first character after the last one expected </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityCopyText(int startPosition, int endPosition);
 
+        /// <summary>
+        /// Cuts text in range to system clipboard.
+        /// </summary>
+        /// <param name="startPosition"> The index of first character </param>
+        /// <param name="endPosition"> The index of first character after the last one expected </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityCutText(int startPosition, int endPosition);
 
+        /// <summary>
+        /// Inserts text at startPosition.
+        /// </summary>
+        /// <param name="startPosition"> The index of first character </param>
+        /// <param name="text"> The text content </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityInsertText(int startPosition, string text);
 
+        /// <summary>
+        /// Replaces text with content.
+        /// </summary>
+        /// <param name="newContents"> The text content </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilitySetTextContents(string newContents);
 
+        /// <summary>
+        /// Deletes text in range.
+        /// </summary>
+        /// <param name="startPosition"> The index of first character </param>
+        /// <param name="endPosition"> The index of first character after the last one expected </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityDeleteText(int startPosition, int endPosition);
     }

diff --git a/src/Tizen.NUI/src/public/Accessibility/IAtspiSelection.cs b/src/Tizen.NUI/src/public/Accessibility/IAtspiSelection.cs
@@ -1,5 +1,5 @@
 /*
- * Copyright(c) 2022 Samsung Electronics Co., Ltd.
+ * Copyright(c) 2023 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.
@@ -21,30 +21,73 @@
 
 namespace Tizen.NUI.Accessibility
 {
+    /// <summary>
+    /// Interface representing objects which can store a set of selected items.
+    /// </summary>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public interface IAtspiSelection
     {
+        /// <summary>
+        /// Gets the number of selected children.
+        /// </summary>
+        /// <returns> The number of selected children (zero if none) </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetSelectedChildrenCount();
 
+        /// <summary>
+        /// Gets a specific selected child.
+        /// </summary>
+        /// <remarks>
+        /// <c>selectedChildIndex</c> refers to the list of selected children, not the list of all children.
+        /// </remarks>
+        /// <param name="selectedChildIndex"> The index of the selected child </param>
+        /// <returns> The selected child or nullptr if index is invalid </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         View AccessibilityGetSelectedChild(int selectedChildIndex);
 
+        /// <summary>
+        /// Selects a child.
+        /// </summary>
+        /// <param name="childIndex"> The index of the child </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilitySelectChild(int childIndex);
 
+        /// <summary>
+        /// Deselects a selected child.
+        /// </summary>
+        /// <param name="selectedChildIndex"> The index of the selected child </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityDeselectSelectedChild(int selectedChildIndex);
 
+        /// <summary>
+        /// Checks whether a child is selected.
+        /// </summary>
+        /// <param name="childIndex"> The index of the child </param>
+        /// <returns>< True if given child is selected, false otherwise /returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityIsChildSelected(int childIndex);
 
+        /// <summary>
+        /// Selects all children.
+        /// </summary>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilitySelectAll();
 
+        /// <summary>
+        /// Deselects all children.
+        /// </summary>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityClearSelection();
 
+        /// <summary>
+        /// Deselects a child.
+        /// </summary>
+        /// <param name="childIndex"> The index of the child. </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityDeselectChild(int childIndex);
     }

diff --git a/src/Tizen.NUI/src/public/Accessibility/IAtspiTable.cs b/src/Tizen.NUI/src/public/Accessibility/IAtspiTable.cs
@@ -22,72 +22,189 @@
 
 namespace Tizen.NUI.Accessibility
 {
+    /// <summary>
+    /// Interface representing a table.
+    /// </summary>
+    /// <remarks>
+    /// The selection methods extend the Selection interface, so both should be implemented by table and grid controls.
+    /// </remarks>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public interface IAtspiTable
     {
+        /// <summary>
+        /// Gets the number of rows.
+        /// </summary>
+        /// <returns> The number of rows </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetRowCount();
 
+        /// <summary>
+        /// Gets the number of columns.
+        /// </summary>
+        /// <returns> The number of columns </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetColumnCount();
 
+        /// <summary>
+        /// Gets the number of selected rows.
+        /// </summary>
+        /// <returns> The number of selected rows </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetSelectedRowCount();
 
+        /// <summary>
+        /// Gets the number of selected columns.
+        /// </summary>
+        /// <returns> The number of selected columns </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetSelectedColumnCount();
 
+        /// <summary>
+        /// Gets the table's caption.
+        /// </summary>
+        /// <returns> The caption or null </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         View AccessibilityGetCaption();
 
+        /// <summary>
+        /// Gets the table's summary.
+        /// </summary>
+        /// <returns> The summary or null </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         View AccessibilityGetSummary();
 
+        /// <summary>
+        /// Gets the cell at the specified position.
+        /// </summary>
+        /// <param name="row"> Row number </param>
+        /// <param name="column"> Column number </param>
+        /// <returns> The cell or null </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         IAtspiTableCell AccessibilityGetCell(int row, int column);
 
+        /// <summary>
+        /// Gets the one-dimensional index of a cell.
+        /// </summary>
+        /// <remarks>
+        /// The returned index should be such that:
+        ///  <code>
+        ///   GetChildAtIndex(GetChildIndex(row, column)) == GetCell(row, column)
+        ///  </code>
+        /// </remarks>
+        /// <param name="row"> Row number </param>
+        /// <param name="column"> Column number </param>
+        /// <returns> The one-dimensional index </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetChildIndex(int row, int column);
 
+        /// <summary>
+        /// Gets the position (row and column) of a cell.
+        /// </summary>
+        /// <param name="childIndex"> One-dimensional index of the cell </param>
+        /// <returns> A pair of integers (row index, column index) </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         Tuple<int, int> AccessibilityGetPositionByChildIndex(int childIndex);
 
+        /// <summary>
+        /// Gets the description of a row.
+        /// </summary>
+        /// <param name="row"> Row number </param>
+        /// <returns> The description of the row </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         string AccessibilityGetRowDescription(int row);
 
+        /// <summary>
+        /// Gets the description of a column.
+        /// </summary>
+        /// <param name="column"> Column number </param>
+        /// <returns> The description of the column </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         string AccessibilityGetColumnDescription(int column);
 
+        /// <summary>
+        /// Gets the header of a row.
+        /// </summary>
+        /// <param name="row"> Row number </param>
+        /// <returns> The row header or null </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         View AccessibilityGetRowHeader(int row);
 
+        /// <summary>
+        /// Gets the header of a column.
+        /// </summary>
+        /// <param name="column"> Column number </param>
+        /// <returns> The column header or null </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         View AccessibilityGetColumnHeader(int column);
 
+        /// <summary>
+        /// Gets all selected rows' numbers.
+        /// </summary>
+        /// <returns> Selected rows' numbers </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         IEnumerable<int> AccessibilityGetSelectedRows();
 
+        /// <summary>
+        /// Gets all selected columns' numbers.
+        /// </summary>
+        /// <returns> Selected columns' numbers </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         IEnumerable<int> AccessibilityGetSelectedColumns();
 
+        /// <summary>
+        /// Checks if a row is selected.
+        /// </summary>
+        /// <param name="row"> Row number </param>
+        /// <returns> True if the row is selected, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityIsRowSelected(int row);
 
+        /// <summary>
+        /// Checks if a column is selected.
+        /// </summary>
+        /// <param name="column"> Column number </param>
+        /// <returns> True if the column is selected, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityIsColumnSelected(int column);
 
+        /// <summary>
+        /// Checks if a cell is selected.
+        /// </summary>
+        /// <param name="row"> Row number of the cell </param>
+        /// <param name="column"> Column number of the cell </param>
+        /// <returns> True if the cell is selected, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityIsCellSelected(int row, int column);
 
+        /// <summary>
+        /// Selects a row.
+        /// </summary>
+        /// <param name="row"> Row number </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityAddRowSelection(int row);
 
+        /// <summary>
+        /// Selects a column.
+        /// </summary>
+        /// <param name="column"> Column number </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityAddColumnSelection(int column);
 
+        /// <summary>
+        /// Unselects a row.
+        /// </summary>
+        /// <param name="row"> Row number </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityRemoveRowSelection(int row);
 
+        /// <summary>
+        /// Unselects a column.
+        /// </summary>
+        /// <param name="column"> Column number </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityRemoveColumnSelection(int column);
     }

diff --git a/src/Tizen.NUI/src/public/Accessibility/IAtspiTableCell.cs b/src/Tizen.NUI/src/public/Accessibility/IAtspiTableCell.cs
@@ -20,18 +20,37 @@
 
 namespace Tizen.NUI.Accessibility
 {
+    /// <summary>
+    /// Interface representing a table cell.
+    /// </summary>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public interface IAtspiTableCell
     {
+        /// <summary>
+        /// Returns the table this cell belongs to.
+        /// </summary>
+        /// <returns> The table </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         IAtspiTable AccessibilityGetTable();
 
+        /// <summary>
+        /// Returns the position of this cell in the table.
+        /// </summary>
+        /// <returns> A pair of integers (row index, column index) </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         Tuple<int, int> AccessibilityGetCellPosition();
 
+        /// <summary>
+        /// Returns the number of rows occupied by this cell.
+        /// </summary>
+        /// <returns> The number of rows </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetCellRowSpan();
 
+        /// <summary>
+        /// Returns the number of columns occupied by this cell.
+        /// </summary>
+        /// <returns> The number of columns </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetCellColumnSpan();
     }