added use of non-preemptive keylistener to simple-at test.
[platform/core/uifw/at-spi2-atk.git] / cspi / spi_table.c
index 91d9f76..32a409a 100644 (file)
@@ -1,3 +1,12 @@
+/**
+ * AccessibleTable_ref:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ *
+ * Increment the reference count for an #AccessibleTable object.
+ *
+ * Returns: (no return code implemented yet).
+ *
+ **/
 int
 AccessibleTable_ref (AccessibleTable *obj)
 {
@@ -7,6 +16,15 @@ AccessibleTable_ref (AccessibleTable *obj)
 
 
 
+/**
+ * AccessibleTable_unref:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ *
+ * Decrement the reference count for an #AccessibleTable object.
+ *
+ * Returns: (no return code implemented yet).
+ *
+ **/
 int
 AccessibleTable_unref (AccessibleTable *obj)
 {
@@ -14,8 +32,15 @@ AccessibleTable_unref (AccessibleTable *obj)
   return 0;
 }
 
-
-
+/**
+ * AccessibleTable_getCaption:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ *
+ * Get an accessible representation of the caption for an #AccessibleTable.
+ *
+ * Returns: an #Accessible object that serves as the table's caption.
+ *
+ **/
 Accessible *
 AccessibleTable_getCaption (AccessibleTable *obj)
 {
@@ -25,6 +50,16 @@ AccessibleTable_getCaption (AccessibleTable *obj)
 
 
 
+/**
+ * AccessibleTable_getSummary:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ *
+ * Get an accessible object which summarizes the contents of an #AccessibleTable.
+ *
+ * Returns: an #Accessible object that serves as the table's summary (often a
+ *          reduced #AccessibleTable).
+ *
+ **/
 Accessible *
 AccessibleTable_getSummary (AccessibleTable *obj)
 {
@@ -34,6 +69,17 @@ AccessibleTable_getSummary (AccessibleTable *obj)
 
 
 
+/**
+ * AccessibleTable_getNRows:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ *
+ * Get the number of rows in an #AccessibleTable,
+ *        exclusive of any rows that are programmatically hidden, but inclusive
+ *        of rows that may be outside of the current scrolling window or viewport.
+ *
+ * Returns: a #long integer indicating the number of rows in the table.
+ *
+ **/
 long
 AccessibleTable_getNRows (AccessibleTable *obj)
 {
@@ -43,6 +89,17 @@ AccessibleTable_getNRows (AccessibleTable *obj)
 
 
 
+/**
+ * AccessibleTable_getNColumns:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ *
+ * Get the number of columns in an #AccessibleTable,
+ *        exclusive of any columns that are programmatically hidden, but inclusive
+ *        of columns that may be outside of the current scrolling window or viewport.
+ *
+ * Returns: a #long integer indicating the number of columns in the table.
+ *
+ **/
 long
 AccessibleTable_getNColumns (AccessibleTable *obj)
 {
@@ -51,10 +108,23 @@ AccessibleTable_getNColumns (AccessibleTable *obj)
 }
 
 
+/**
+ * AccessibleTable_getAccessibleAt:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @row: the specified table row, zero-indexed.
+ * @column: the specified table column, zero-indexed.
+ *
+ * Get the table cell at the specified row and column indices.
+ *          To get the accessible object at a particular (x, y) screen coordinate,
+ *          use #Accessible_getAccessibleAtPoint ().
+ *
+ * Returns: an #Accessible object representing the specified table cell.
+ *
+ **/
 Accessible *
 AccessibleTable_getAccessibleAt (AccessibleTable *obj,
-                                 long row,
-                                 long column)
+                                 long int row,
+                                 long int column)
 {
   return (Accessible *)
     Accessibility_Table_getAccessibleAt (*obj,
@@ -62,10 +132,25 @@ AccessibleTable_getAccessibleAt (AccessibleTable *obj,
 }
 
 
+/**
+ * AccessibleTable_getIndexAt:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @row: the specified table row, zero-indexed.
+ * @column: the specified table column, zero-indexed.
+ *
+ * Get the 1-D child index corresponding to the specified 2-D row and column indices.
+ *          To get the accessible object at a particular (x, y) screen coordinate,
+ *          use #Accessible_getAccessibleAtPoint ().
+ * @see #AccessibleTable_getRowAtIndex(), #AccessibleTable_getColumnAtIndex()
+ *
+ * Returns: a long integer which serves as the index of a specified cell in the
+ *          table, in a form usable by #Accessible_getChildAtIndex().
+ *
+ **/
 long
 AccessibleTable_getIndexAt (AccessibleTable *obj,
-                            long row,
-                            long column)
+                            long int row,
+                            long int column)
 {
   return (long)
     Accessibility_Table_getIndexAt (*obj,
@@ -74,6 +159,19 @@ AccessibleTable_getIndexAt (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_getRowAtIndex:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @index: the specified child index, zero-indexed.
+ *
+ * Get the table row index occupied by the child at a particular 1-D child index.
+ *
+ * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getColumnAtIndex()
+ *
+ * Returns: a long integer indicating the first row spanned by the child of a
+ *          table, at the specified 1-D (zero-offset) @index.
+ *
+ **/
 long
 AccessibleTable_getRowAtIndex (AccessibleTable *obj,
                                long index)
@@ -85,6 +183,19 @@ AccessibleTable_getRowAtIndex (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_getColumnAtIndex:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @index: the specified child index, zero-indexed.
+ *
+ * Get the table column index occupied by the child at a particular 1-D child index.
+ *
+ * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getRowAtIndex()
+ *
+ * Returns: a long integer indicating the first column spanned by the child of a
+ *          table, at the specified 1-D (zero-offset) @index.
+ *
+ **/
 long
 AccessibleTable_getColumnAtIndex (AccessibleTable *obj,
                                   long index)
@@ -96,9 +207,20 @@ AccessibleTable_getColumnAtIndex (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_getRowDescription:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @row: the specified table row, zero-indexed.
+ *
+ * Get a text description of a particular table row.  This differs from
+ * AccessibleTable_getRowHeader, which returns an #Accessible.
+ *
+ * Returns: a UTF-8 string describing the specified table row, if available.
+ *
+ **/
 char *
 AccessibleTable_getRowDescription (AccessibleTable *obj,
-                                  long row)
+                                  long int row)
 {
   return (char *)
     Accessibility_Table_getRowDescription (*obj,
@@ -107,9 +229,20 @@ AccessibleTable_getRowDescription (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_getColumnDescription:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @column: the specified table column, zero-indexed.
+ *
+ * Get a text description of a particular table column.  This differs from
+ * AccessibleTable_getColumnHeader, which returns an #Accessible.
+ *
+ * Returns: a UTF-8 string describing the specified table column, if available.
+ *
+ **/
 char *
 AccessibleTable_getColumnDescription (AccessibleTable *obj,
-                                     long column)
+                                     long int column)
 {
   return (char *)
     Accessibility_Table_getColumnDescription (*obj,
@@ -118,10 +251,22 @@ AccessibleTable_getColumnDescription (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_getRowExtentAt:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @row: the specified table row, zero-indexed.
+ * @column: the specified table column, zero-indexed.
+ *
+ * Get the number of rows spanned by the table cell at the specific row and column.
+ * (some tables can have cells which span multiple rows and/or columns).
+ *
+ * Returns: a long integer indicating the number of rows spanned by the specified cell.
+ *
+ **/
 long
 AccessibleTable_getRowExtentAt (AccessibleTable *obj,
-                                long row,
-                                long column)
+                                long int row,
+                                long int column)
 {
   return (long)
     Accessibility_Table_getRowExtentAt (*obj,
@@ -130,10 +275,22 @@ AccessibleTable_getRowExtentAt (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_getColumnExtentAt:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @row: the specified table row, zero-indexed.
+ * @column: the specified table column, zero-indexed.
+ *
+ * Get the number of columns spanned by the table cell at the specific row and column.
+ * (some tables can have cells which span multiple rows and/or columns).
+ *
+ * Returns: a long integer indicating the number of columns spanned by the specified cell.
+ *
+ **/
 long
 AccessibleTable_getColumnExtentAt (AccessibleTable *obj,
-                                   long row,
-                                   long column)
+                                   long int row,
+                                   long int column)
 {
   return (long)
     Accessibility_Table_getColumnExtentAt (*obj,
@@ -141,10 +298,20 @@ AccessibleTable_getColumnExtentAt (AccessibleTable *obj,
 }
 
 
-
+/**
+ * AccessibleTable_getRowHeader:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @row: the specified table row, zero-indexed.
+ *
+ * Get the header associated with a table row, if available.  This differs from
+ * AccessibleTable_getRowDescription, which returns a string.
+ *
+ * Returns: a #Accessible representatin of the specified table row, if available.
+ *
+ **/
 Accessible *
 AccessibleTable_getRowHeader (AccessibleTable *obj,
-                             long row)
+                             long int row)
 {
   return (Accessible *)
     Accessibility_Table_getRowHeader (*obj,
@@ -153,9 +320,20 @@ AccessibleTable_getRowHeader (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_getColumnHeader:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @column: the specified table column, zero-indexed.
+ *
+ * Get the header associated with a table column, if available.  This differs from
+ * AccessibleTable_getColumnDescription, which returns a string.
+ *
+ * Returns: a #Accessible representatin of the specified table column, if available.
+ *
+ **/
 Accessible *
 AccessibleTable_getColumnHeader (AccessibleTable *obj,
-                                long column)
+                                long int column)
 {
   return (Accessible *)
     Accessibility_Table_getColumnHeader (*obj,
@@ -163,7 +341,15 @@ AccessibleTable_getColumnHeader (AccessibleTable *obj,
 }
 
 
-
+/**
+ * AccessibleTable_getNSelectedRows:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ *
+ * Query a table to find out how many rows are currently selected.  Not all tables
+ *  support row selection.
+ *
+ * Returns: a long integer indicating the number of rows currently selected.
+ **/
 long
 AccessibleTable_getNSelectedRows (AccessibleTable *obj)
 {
@@ -173,9 +359,19 @@ AccessibleTable_getNSelectedRows (AccessibleTable *obj)
 
 
 
+/**
+ * AccessibleTable_getSelectedRows:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @selectedRows: a doubly indirected pointer which will be set to the address
+ *       of an array of long integers, specifying which rows are currently selected.
+ *
+ * Query a table for a list of indices of rows which are currently selected.
+ *
+ * Returns: a long integer indicating the length of the array returned in @selectedRows.
+ **/
 long
 AccessibleTable_getSelectedRows (AccessibleTable *obj,
-                                 long **selectedRows)
+                                 long int **selectedRows)
 {
   Accessibility_LongSeq *rows = Accessibility_Table_getSelectedRows (*obj, &ev);
   CORBA_long *i;
@@ -196,6 +392,15 @@ AccessibleTable_getSelectedRows (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_getNSelectedColumns:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ *
+ * Query a table to find out how many columnss are currently selected.  Not all tables
+ *  support column selection.
+ *
+ * Returns: a long integer indicating the number of columns currently selected.
+ **/
 long
 AccessibleTable_getNSelectedColumns (AccessibleTable *obj)
 {
@@ -204,9 +409,20 @@ AccessibleTable_getNSelectedColumns (AccessibleTable *obj)
 }
 
 
+/**
+ * AccessibleTable_getSelectedColumns:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @selectedColumns: a doubly indirected pointer which will be set to the address
+ *       of an array of long integers, specifying which columns are currently selected.
+ *
+ * Query a table for a list of indices of columns which are currently selected.
+ *       Not all tables support column selection.
+ *
+ * Returns: a long integer indicating the length of the array returned in @selectedColumns.
+ **/
 long
 AccessibleTable_getSelectedColumns (AccessibleTable *obj,
-                                    long **selectedColumns)
+                                    long int **selectedColumns)
 {
   Accessibility_LongSeq *columns = Accessibility_Table_getSelectedColumns (*obj, &ev);
   CORBA_long *i;
@@ -226,9 +442,19 @@ AccessibleTable_getSelectedColumns (AccessibleTable *obj,
 }
 
 
+/**
+ * AccessibleTable_isRowSelected:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @row:
+ *
+ * Determine whether a table row is selected.  Not all tables support row selection.
+ *
+ * Returns: #TRUE if the specified row is currently selected, #FALSE if not.
+ *
+ **/
 boolean
 AccessibleTable_isRowSelected (AccessibleTable *obj,
-                               long row)
+                               long int row)
 {
   return (boolean)
     Accessibility_Table_isRowSelected (*obj,
@@ -237,9 +463,20 @@ AccessibleTable_isRowSelected (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_isColumnSelected:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @column:
+ *
+ * Determine whether specified table column is selected.
+ * Not all tables support column selection.
+ *
+ * Returns: #TRUE if the specified column is currently selected, #FALSE if not.
+ *
+ **/
 boolean
 AccessibleTable_isColumnSelected (AccessibleTable *obj,
-                                  long column)
+                                  long int column)
 {
   return (boolean)
     Accessibility_Table_isColumnSelected (*obj,
@@ -248,12 +485,23 @@ AccessibleTable_isColumnSelected (AccessibleTable *obj,
 
 
 
+/**
+ * AccessibleTable_isSelected:
+ * @obj: a pointer to the #AccessibleTable implementor on which to operate.
+ * @row:
+ * @column:
+ *
+ * Determine whether the cell at a specific row and column is selected.
+ *
+ * Returns: #TRUE if the specified cell is currently selected, #FALSE if not.
+ *
+ **/
 boolean
 AccessibleTable_isSelected (AccessibleTable *obj,
-                            long row,
-                            long column)
+                            long int row,
+                            long int column)
 {
-return (boolean)
+  return (boolean)
   Accessibility_Table_isSelected (*obj,
                                  (CORBA_long) row, (CORBA_long) column, &ev);
 }