From: Seoyeon Kim <seoyeon2.kim@samsung.com>
Date: Wed, 30 Aug 2023 06:50:04 +0000 (+0900)
Subject: [NUI] Add descriptions of Accessibility Interfaces
X-Git-Tag: accepted/tizen/unified/20231205.024657~163
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=90a7b6ccba86860805c4e58995196c8cfa839258;p=platform%2Fcore%2Fcsapi%2Ftizenfx.git

[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 <seoyeon2.kim@samsung.com>
---

diff --git a/src/Tizen.NUI/src/public/Accessibility/IAtspiEditableText.cs b/src/Tizen.NUI/src/public/Accessibility/IAtspiEditableText.cs
index 4b6f538..c5b0c4e 100644
--- 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 @@ using System.ComponentModel;
 
 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
index 2e57407..38f1a66 100644
--- 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 @@ using Tizen.NUI.BaseComponents;
 
 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
index 5aa7b7b..6d2303c 100644
--- a/src/Tizen.NUI/src/public/Accessibility/IAtspiTable.cs
+++ b/src/Tizen.NUI/src/public/Accessibility/IAtspiTable.cs
@@ -22,72 +22,189 @@ using Tizen.NUI.BaseComponents;
 
 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
index 3dbc966..d70e11e 100644
--- a/src/Tizen.NUI/src/public/Accessibility/IAtspiTableCell.cs
+++ b/src/Tizen.NUI/src/public/Accessibility/IAtspiTableCell.cs
@@ -20,18 +20,37 @@ using System.ComponentModel;
 
 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();
     }
diff --git a/src/Tizen.NUI/src/public/Accessibility/IAtspiText.cs b/src/Tizen.NUI/src/public/Accessibility/IAtspiText.cs
index e610b89..53e5337 100644
--- a/src/Tizen.NUI/src/public/Accessibility/IAtspiText.cs
+++ b/src/Tizen.NUI/src/public/Accessibility/IAtspiText.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,33 +21,94 @@ using Tizen.NUI.BaseComponents;
 
 namespace Tizen.NUI.Accessibility
 {
+    /// <summary>
+    /// Interface representing objects which can store immutable texts.
+    /// </summary>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public interface IAtspiText
     {
+        /// <summary>
+        /// Gets stored text in given range.
+        /// </summary>
+        /// <param name="startOffset"> The index of first character </param>
+        /// <param name="endOffset"> The index of first character after the last one expected </param>
+        /// <returns> The substring of stored text </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         string AccessibilityGetText(int startOffset, int endOffset);
 
+        /// <summary>
+        /// Gets number of all stored characters.
+        /// </summary>
+        /// <returns> The number of characters </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetCharacterCount();
 
+        /// <summary>
+        /// Gets the cursor offset.
+        /// </summary>
+        /// <returns> Value of cursor offset </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         int AccessibilityGetCursorOffset();
 
+        /// <summary>
+        /// Sets the cursor offset.
+        /// </summary>
+        /// <param name="offset"> Cursor offset </param>
+        /// <returns> True if successful </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilitySetCursorOffset(int offset);
 
+        /// <summary>
+        /// Gets substring of stored text truncated in concrete gradation.
+        /// </summary>
+        /// <param name="offset"> The position in stored text </param>
+        /// <param name="boundary"> The enumeration describing text gradation </param>
+        /// <returns> Range structure containing acquired text and offsets in original string </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         AccessibilityRange AccessibilityGetTextAtOffset(int offset, AccessibilityTextBoundary boundary);
 
+        /// <summary>
+        /// Gets selected text.
+        /// </summary>
+        /// <remarks>
+        ///  Currently only one selection (i.e. with index = 0) is supported
+        /// </remarks>
+        /// <param name="selectionNumber"> The selection index </param>
+        /// <returns> Range structure containing acquired text and offsets in original string </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         AccessibilityRange AccessibilityGetSelection(int selectionNumber);
 
+        /// <summary>
+        /// Removes the whole selection.
+        /// </summary>
+        /// <remarks>
+        ///  Currently only one selection (i.e. with index = 0) is supported
+        /// </remarks>
+        /// <param name="selectionNumber"> The selection index </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilityRemoveSelection(int selectionNumber);
 
+        /// <summary>
+        /// Sets selected text.
+        /// </summary>
+        /// <remarks>
+        ///  Currently only one selection (i.e. with index = 0) is supported
+        /// </remarks>
+        /// <param name="selectionNumber"> The selection index </param>
+        /// <param name="startOffset"> The index of first character </param>
+        /// <param name="endOffset"> The index of first character after the last one expected </param>
+        /// <returns> True on success, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilitySetSelection(int selectionNumber, int startOffset, int endOffset);
 
+        /// <summary>
+        /// Gets the bounding box for text within a range in text.
+        /// </summary>
+        /// <param name="startOffset"> The index of first character </param>
+        /// <param name="endOffset"> The index of first character after the last one expected </param>
+        /// <param name="coordType"> The enumeration with type of coordinate system </param>
+        /// <returns> Rectangle giving the position and size of the specified range of text </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         Rectangle AccessibilityGetRangeExtents(int startOffset, int endOffset, AccessibilityCoordinateType coordType);
     }
diff --git a/src/Tizen.NUI/src/public/Accessibility/IAtspiValue.cs b/src/Tizen.NUI/src/public/Accessibility/IAtspiValue.cs
index a6fecb7..baa4bf8 100644
--- a/src/Tizen.NUI/src/public/Accessibility/IAtspiValue.cs
+++ b/src/Tizen.NUI/src/public/Accessibility/IAtspiValue.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,9 +20,16 @@ using System.ComponentModel;
 
 namespace Tizen.NUI.Accessibility
 {
+    /// <summary>
+    /// Interface representing objects which can store numeric value.
+    /// </summary>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public interface IAtspiValue
     {
+        /// <summary>
+        /// Gets the lowest possible value.
+        /// </summary>
+        /// <returns> The minimum value </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         double AccessibilityGetMinimum();
 
@@ -52,12 +59,25 @@ namespace Tizen.NUI.Accessibility
         [EditorBrowsable(EditorBrowsableState.Never)]
         string AccessibilityGetValueText();
 
+        /// <summary>
+        /// Gets the highest possible value.
+        /// </summary>
+        /// <returns> The highest value </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         double AccessibilityGetMaximum();
 
+        /// <summary>
+        /// Sets the current value.
+        /// </summary>
+        /// <param name="value"> The current value to set </param>
+        /// <returns> True if value could have been assigned, false otherwise </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         bool AccessibilitySetCurrent(double value);
 
+        /// <summary>
+        /// Gets the lowest increment that can be distinguished.
+        /// </summary>
+        /// <returns> The lowest increment </returns>
         [EditorBrowsable(EditorBrowsableState.Never)]
         double AccessibilityGetMinimumIncrement();
     }