6cb308760335f704f99a03b1e8f8ae6523cc4f8d
[platform/core/uifw/at-spi2-atk.git] / cspi / spi_table.c
1 /*
2  * AT-SPI - Assistive Technology Service Provider Interface
3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
4  *
5  * Copyright 2001 Sun Microsystems Inc.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Library General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Library General Public License for more details.
16  *
17  * You should have received a copy of the GNU Library General Public
18  * License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20  * Boston, MA 02111-1307, USA.
21  */
22
23 #include <stdlib.h> /* for malloc */
24 #include <cspi/spi-private.h>
25
26 /**
27  * AccessibleTable_ref:
28  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
29  *
30  * Increment the reference count for an #AccessibleTable object.
31  **/
32 void
33 AccessibleTable_ref (AccessibleTable *obj)
34 {
35   cspi_object_ref (obj);
36 }
37
38 /**
39  * AccessibleTable_unref:
40  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
41  *
42  * Decrement the reference count for an #AccessibleTable object.
43  **/
44 void
45 AccessibleTable_unref (AccessibleTable *obj)
46 {
47   cspi_object_unref (obj);
48 }
49
50 /**
51  * AccessibleTable_getCaption:
52  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
53  *
54  * Get an accessible representation of the caption for an #AccessibleTable.
55  *
56  * Returns: an #Accessible object that serves as the table's caption.
57  **/
58 Accessible *
59 AccessibleTable_getCaption (AccessibleTable *obj)
60 {
61   return cspi_object_add (
62     Accessibility_Table__get_caption (CSPI_OBJREF (obj), cspi_ev ()));
63 }
64
65 /**
66  * AccessibleTable_getSummary:
67  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
68  *
69  * Get an accessible object which summarizes the contents of an #AccessibleTable.
70  *
71  * Returns: an #Accessible object that serves as the table's summary (often a
72  *          reduced #AccessibleTable).
73  **/
74 Accessible *
75 AccessibleTable_getSummary (AccessibleTable *obj)
76 {
77   return cspi_object_add (
78     Accessibility_Table__get_summary (CSPI_OBJREF (obj), cspi_ev ()));
79 }
80
81 /**
82  * AccessibleTable_getNRows:
83  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
84  *
85  * Get the number of rows in an #AccessibleTable,
86  *        exclusive of any rows that are programmatically hidden, but inclusive
87  *        of rows that may be outside of the current scrolling window or viewport.
88  *
89  * Returns: a #long integer indicating the number of rows in the table.
90  **/
91 long
92 AccessibleTable_getNRows (AccessibleTable *obj)
93 {
94   long retval;
95
96   cspi_return_val_if_fail (obj != NULL, -1);
97
98   retval =
99     Accessibility_Table__get_nRows (CSPI_OBJREF (obj), cspi_ev ());
100           
101   cspi_return_val_if_ev ("getNRows", -1);
102
103   return retval;
104           
105 }
106
107 /**
108  * AccessibleTable_getNColumns:
109  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
110  *
111  * Get the number of columns in an #AccessibleTable,
112  *        exclusive of any columns that are programmatically hidden, but inclusive
113  *        of columns that may be outside of the current scrolling window or viewport.
114  *
115  * Returns: a #long integer indicating the number of columns in the table.
116  **/
117 long
118 AccessibleTable_getNColumns (AccessibleTable *obj)
119 {
120   long retval;
121
122   cspi_return_val_if_fail (obj != NULL, -1);
123
124   retval =
125     Accessibility_Table__get_nColumns (CSPI_OBJREF (obj), cspi_ev ());
126           
127   cspi_return_val_if_ev ("", -1);
128
129   return retval;
130 }
131
132 /**
133  * AccessibleTable_getAccessibleAt:
134  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
135  * @row: the specified table row, zero-indexed.
136  * @column: the specified table column, zero-indexed.
137  *
138  * Get the table cell at the specified row and column indices.
139  *          To get the accessible object at a particular (x, y) screen coordinate,
140  *          use #Accessible_getAccessibleAtPoint ().
141  *
142  * Returns: an #Accessible object representing the specified table cell.
143  **/
144 Accessible *
145 AccessibleTable_getAccessibleAt (AccessibleTable *obj,
146                                  long int row,
147                                  long int column)
148 {
149   return cspi_object_add (
150     Accessibility_Table_getAccessibleAt (
151       CSPI_OBJREF (obj), (CORBA_long) row,
152       (CORBA_long) column, cspi_ev ()));
153 }
154
155 /**
156  * AccessibleTable_getIndexAt:
157  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
158  * @row: the specified table row, zero-indexed.
159  * @column: the specified table column, zero-indexed.
160  *
161  * Get the 1-D child index corresponding to the specified 2-D row and column indices.
162  *          To get the accessible object at a particular (x, y) screen coordinate,
163  *          use #Accessible_getAccessibleAtPoint ().
164  * @see #AccessibleTable_getRowAtIndex(), #AccessibleTable_getColumnAtIndex()
165  *
166  * Returns: a long integer which serves as the index of a specified cell in the
167  *          table, in a form usable by #Accessible_getChildAtIndex().
168  **/
169 long
170 AccessibleTable_getIndexAt (AccessibleTable *obj,
171                             long int row,
172                             long int column)
173 {
174   long retval;
175
176   cspi_return_val_if_fail (obj != NULL, -1);
177
178   retval =
179     Accessibility_Table_getIndexAt (
180       CSPI_OBJREF (obj), (CORBA_long) row,
181       (CORBA_long) column, cspi_ev ());
182           
183   cspi_return_val_if_ev ("getIndexAt", -1);
184
185   return retval;
186 }
187
188 /**
189  * AccessibleTable_getRowAtIndex:
190  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
191  * @index: the specified child index, zero-indexed.
192  *
193  * Get the table row index occupied by the child at a particular 1-D child index.
194  *
195  * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getColumnAtIndex()
196  *
197  * Returns: a long integer indicating the first row spanned by the child of a
198  *          table, at the specified 1-D (zero-offset) @index.
199  **/
200 long
201 AccessibleTable_getRowAtIndex (AccessibleTable *obj,
202                                long index)
203 {
204   long retval;
205
206   cspi_return_val_if_fail (obj != NULL, -1);
207
208   retval =
209     Accessibility_Table_getRowAtIndex (CSPI_OBJREF (obj),
210                                        (CORBA_long) index, cspi_ev ());
211           
212   cspi_return_val_if_ev ("", -1);
213
214   return retval;
215 }
216
217 /**
218  * AccessibleTable_getColumnAtIndex:
219  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
220  * @index: the specified child index, zero-indexed.
221  *
222  * Get the table column index occupied by the child at a particular 1-D child index.
223  *
224  * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getRowAtIndex()
225  *
226  * Returns: a long integer indicating the first column spanned by the child of a
227  *          table, at the specified 1-D (zero-offset) @index.
228  **/
229 long
230 AccessibleTable_getColumnAtIndex (AccessibleTable *obj,
231                                   long index)
232 {
233   long retval;
234
235   cspi_return_val_if_fail (obj != NULL, -1);
236
237   retval =
238     Accessibility_Table_getColumnAtIndex (CSPI_OBJREF (obj),
239                                           (CORBA_long) index, cspi_ev ());
240           
241   cspi_return_val_if_ev ("getColumnAtIndex", -1);
242
243   return retval;
244 }
245
246 /**
247  * AccessibleTable_getRowDescription:
248  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
249  * @row: the specified table row, zero-indexed.
250  *
251  * Get a text description of a particular table row.  This differs from
252  * AccessibleTable_getRowHeader, which returns an #Accessible.
253  *
254  * Returns: a UTF-8 string describing the specified table row, if available.
255  **/
256 char *
257 AccessibleTable_getRowDescription (AccessibleTable *obj,
258                                    long int         row)
259 {
260   char *retval;
261
262   cspi_return_val_if_fail (obj != NULL, NULL);
263
264   retval =
265     Accessibility_Table_getRowDescription (CSPI_OBJREF (obj),
266                                            (CORBA_long) row, cspi_ev ());
267           
268   cspi_return_val_if_ev ("getRowDescription", NULL);
269
270   return retval;
271 }
272
273 /**
274  * AccessibleTable_getColumnDescription:
275  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
276  * @column: the specified table column, zero-indexed.
277  *
278  * Get a text description of a particular table column.  This differs from
279  * AccessibleTable_getColumnHeader, which returns an #Accessible.
280  *
281  * Returns: a UTF-8 string describing the specified table column, if available.
282  **/
283 char *
284 AccessibleTable_getColumnDescription (AccessibleTable *obj,
285                                       long int         column)
286 {
287   char *retval;
288
289   cspi_return_val_if_fail (obj != NULL, NULL);
290
291   retval =
292     Accessibility_Table_getColumnDescription (CSPI_OBJREF (obj),
293                                               (CORBA_long) column, cspi_ev ());
294
295   cspi_return_val_if_ev ("getColumnDescription", NULL);
296
297   return retval;
298 }
299
300 /**
301  * AccessibleTable_getRowExtentAt:
302  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
303  * @row: the specified table row, zero-indexed.
304  * @column: the specified table column, zero-indexed.
305  *
306  * Get the number of rows spanned by the table cell at the specific row and column.
307  * (some tables can have cells which span multiple rows and/or columns).
308  *
309  * Returns: a long integer indicating the number of rows spanned by the specified cell.
310  **/
311 long
312 AccessibleTable_getRowExtentAt (AccessibleTable *obj,
313                                 long int         row,
314                                 long int         column)
315 {
316   long retval;
317
318   cspi_return_val_if_fail (obj != NULL, -1);
319
320   retval =
321     Accessibility_Table_getRowExtentAt (
322       CSPI_OBJREF (obj), (CORBA_long) row,
323       (CORBA_long) column, cspi_ev ());
324           
325   cspi_return_val_if_ev ("getRowExtentAt", -1);
326
327   return retval;
328 }
329
330 /**
331  * AccessibleTable_getColumnExtentAt:
332  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
333  * @row: the specified table row, zero-indexed.
334  * @column: the specified table column, zero-indexed.
335  *
336  * Get the number of columns spanned by the table cell at the specific row and column.
337  * (some tables can have cells which span multiple rows and/or columns).
338  *
339  * Returns: a long integer indicating the number of columns spanned by the specified cell.
340  **/
341 long
342 AccessibleTable_getColumnExtentAt (AccessibleTable *obj,
343                                    long int         row,
344                                    long int         column)
345 {
346   long retval;
347
348   cspi_return_val_if_fail (obj != NULL, -1);
349
350   retval =
351     Accessibility_Table_getColumnExtentAt (
352       CSPI_OBJREF (obj), (CORBA_long) row,
353       (CORBA_long) column, cspi_ev ());
354           
355   cspi_return_val_if_ev ("getColumnExtentAt", -1);
356
357   return retval;
358 }
359
360 /**
361  * AccessibleTable_getRowHeader:
362  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
363  * @row: the specified table row, zero-indexed.
364  *
365  * Get the header associated with a table row, if available.  This differs from
366  * AccessibleTable_getRowDescription, which returns a string.
367  *
368  * Returns: a #Accessible representatin of the specified table row, if available.
369  **/
370 Accessible *
371 AccessibleTable_getRowHeader (AccessibleTable *obj,
372                               long int         row)
373 {
374   return cspi_object_add (
375     Accessibility_Table_getRowHeader (CSPI_OBJREF (obj),
376                                       (CORBA_long) row, cspi_ev ()));
377 }
378
379 /**
380  * AccessibleTable_getColumnHeader:
381  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
382  * @column: the specified table column, zero-indexed.
383  *
384  * Get the header associated with a table column, if available.  This differs from
385  * AccessibleTable_getColumnDescription, which returns a string.
386  *
387  * Returns: a #Accessible representatin of the specified table column, if available.
388  **/
389 Accessible *
390 AccessibleTable_getColumnHeader (AccessibleTable *obj,
391                                  long int column)
392 {
393   return cspi_object_add (
394     Accessibility_Table_getColumnHeader (CSPI_OBJREF (obj),
395                                       (CORBA_long) column, cspi_ev ()));
396 }
397
398 /**
399  * AccessibleTable_getNSelectedRows:
400  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
401  *
402  * Query a table to find out how many rows are currently selected.  Not all tables
403  *  support row selection.
404  *
405  * Returns: a long integer indicating the number of rows currently selected.
406  **/
407 long
408 AccessibleTable_getNSelectedRows (AccessibleTable *obj)
409 {
410   long retval;
411
412   cspi_return_val_if_fail (obj != NULL, -1);
413
414   retval =
415     Accessibility_Table__get_nSelectedRows (CSPI_OBJREF (obj), cspi_ev ());
416           
417   cspi_return_val_if_ev ("getNSelectedRows", -1);
418
419   return retval;
420 }
421
422 static long
423 cspi_long_seq_to_array (Accessibility_LongSeq *seq, long int **array)
424 {
425   long *j, length, i;
426
427   if (!cspi_check_ev ("getSelectionItems"))
428     {
429       *array = NULL;
430       return 0;
431     }
432
433   length = seq->_length;
434
435   j = *array = malloc (sizeof (long) * length);
436
437   for (i = 0; i < length; i++)
438     {
439       j[i] = seq->_buffer [i];
440     }
441
442   CORBA_free (seq);
443
444   return length;
445 }
446
447 /**
448  * AccessibleTable_getSelectedRows:
449  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
450  * @selectedRows: a doubly indirected pointer which will be set to the address
451  *       of an array of long integers, specifying which rows are currently selected.
452  *
453  * Query a table for a list of indices of rows which are currently selected.
454  *
455  * Returns: a long integer indicating the length of the array returned in @selectedRows.
456  **/
457 long
458 AccessibleTable_getSelectedRows (AccessibleTable *obj,
459                                  long int       **selectedRows)
460 {
461   Accessibility_LongSeq *rows;
462
463   *selectedRows = NULL;
464
465   cspi_return_val_if_fail (obj != NULL, 0);
466
467   rows = Accessibility_Table_getSelectedRows (CSPI_OBJREF (obj), cspi_ev ());
468
469   return cspi_long_seq_to_array (rows, selectedRows);
470 }
471
472 /**
473  * AccessibleTable_getNSelectedColumns:
474  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
475  *
476  * Query a table to find out how many columnss are currently selected.  Not all tables
477  *  support column selection.
478  *
479  * Returns: a long integer indicating the number of columns currently selected.
480  **/
481 long
482 AccessibleTable_getNSelectedColumns (AccessibleTable *obj)
483 {
484   long retval;
485
486   cspi_return_val_if_fail (obj != NULL, -1);
487
488   retval =
489     Accessibility_Table__get_nSelectedColumns (CSPI_OBJREF (obj), cspi_ev ());
490           
491   cspi_return_val_if_ev ("getNSelectedColumns", -1);
492
493   return retval;
494 }
495
496 /**
497  * AccessibleTable_getSelectedColumns:
498  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
499  * @selectedColumns: a doubly indirected pointer which will be set to the address
500  *       of an array of long integers, specifying which columns are currently selected.
501  *
502  * Query a table for a list of indices of columns which are currently selected.
503  *       Not all tables support column selection.
504  *
505  * Returns: a long integer indicating the length of the array returned in @selectedColumns.
506  **/
507 long
508 AccessibleTable_getSelectedColumns (AccessibleTable *obj,
509                                     long int       **selectedColumns)
510 {
511   Accessibility_LongSeq *columns;
512
513   *selectedColumns = NULL;
514
515   cspi_return_val_if_fail (obj != NULL, 0);
516
517   columns = Accessibility_Table_getSelectedColumns (CSPI_OBJREF (obj), cspi_ev ());
518
519   return cspi_long_seq_to_array (columns, selectedColumns);
520 }
521
522 /**
523  * AccessibleTable_isRowSelected:
524  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
525  * @row:
526  *
527  * Determine whether a table row is selected.  Not all tables support row selection.
528  *
529  * Returns: #TRUE if the specified row is currently selected, #FALSE if not.
530  **/
531 SPIBoolean
532 AccessibleTable_isRowSelected (AccessibleTable *obj,
533                                long int         row)
534 {
535   SPIBoolean retval;
536
537   cspi_return_val_if_fail (obj != NULL, FALSE);
538
539   retval =
540     Accessibility_Table_isRowSelected (CSPI_OBJREF (obj),
541                                        (CORBA_long) row, cspi_ev ());
542
543   cspi_return_val_if_ev ("isRowSelected", FALSE);
544
545   return retval;
546 }
547
548 /**
549  * AccessibleTable_isColumnSelected:
550  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
551  * @column:
552  *
553  * Determine whether specified table column is selected.
554  * Not all tables support column selection.
555  *
556  * Returns: #TRUE if the specified column is currently selected, #FALSE if not.
557  **/
558 SPIBoolean
559 AccessibleTable_isColumnSelected (AccessibleTable *obj,
560                                   long int         column)
561 {
562   SPIBoolean retval;
563
564   cspi_return_val_if_fail (obj != NULL, FALSE);
565
566   retval =
567     Accessibility_Table_isColumnSelected (CSPI_OBJREF (obj),
568                                           (CORBA_long) column, cspi_ev ());
569           
570   cspi_return_val_if_ev ("isColumnSelected", FALSE);
571
572   return retval;
573 }
574
575 /**
576  * AccessibleTable_addRowSelection:
577  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
578  * @row:
579  *
580  * Select the specified row, adding it to the current row selection.
581  * Not all tables support row selection.
582  *
583  * Returns: #TRUE if the specified row was successfully selected, #FALSE if not.
584  **/
585 SPIBoolean
586 AccessibleTable_addRowSelection (AccessibleTable *obj,
587                                  long int         row)
588 {
589   SPIBoolean retval;
590
591   cspi_return_val_if_fail (obj != NULL, FALSE);
592
593   retval =
594     Accessibility_Table_addRowSelection (CSPI_OBJREF (obj),
595                                          (CORBA_long) row, cspi_ev ());
596           
597   cspi_return_val_if_ev ("addRowSelection", FALSE);
598
599   return retval;
600 }
601
602 /**
603  * AccessibleTable_addColumnSelection:
604  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
605  * @column:
606  *
607  * Select the specified column, adding it to the current column selection.
608  * Not all tables support column selection.
609  *
610  * Returns: #TRUE if the specified column was successfully selected, #FALSE if not.
611  **/
612 SPIBoolean
613 AccessibleTable_addColumnSelection (AccessibleTable *obj,
614                                     long int         column)
615 {
616   SPIBoolean retval;
617
618   cspi_return_val_if_fail (obj != NULL, FALSE);
619
620   retval =
621     Accessibility_Table_addColumnSelection (CSPI_OBJREF (obj),
622                                             (CORBA_long) column, cspi_ev ());
623           
624   cspi_return_val_if_ev ("addColumnSelection", FALSE);
625
626   return retval;
627 }
628
629 /**
630  * AccessibleTable_removeRowSelection:
631  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
632  * @row:
633  *
634  * De-select the specified row, removing it to the current row selection.
635  * Not all tables support row selection.
636  *
637  * Returns: #TRUE if the specified row was successfully de-selected, #FALSE if not.
638  **/
639 SPIBoolean
640 AccessibleTable_removeRowSelection (AccessibleTable *obj,
641                                     long int         row)
642 {
643   SPIBoolean retval;
644
645   cspi_return_val_if_fail (obj != NULL, FALSE);
646
647   retval =
648     Accessibility_Table_removeRowSelection (CSPI_OBJREF (obj),
649                                             (CORBA_long) row, cspi_ev ());
650           
651   cspi_return_val_if_ev ("removeRowSelection", FALSE);
652
653   return retval;
654 }
655
656 /**
657  * AccessibleTable_removeColumnSelection:
658  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
659  * @column:
660  *
661  * De-select the specified column, removing it to the current column selection.
662  * Not all tables support column selection.
663  *
664  * Returns: #TRUE if the specified column was successfully de-selected, #FALSE if not.
665  **/
666 SPIBoolean
667 AccessibleTable_removeColumnSelection (AccessibleTable *obj,
668                                        long int         column)
669 {
670   SPIBoolean retval;
671
672   cspi_return_val_if_fail (obj != NULL, FALSE);
673
674   retval =
675     Accessibility_Table_removeColumnSelection (CSPI_OBJREF (obj),
676                                                (CORBA_long) column, cspi_ev ());
677           
678   cspi_return_val_if_ev ("removeColumnSelection", FALSE);
679
680   return retval;
681 }
682
683 /**
684  * AccessibleTable_isSelected:
685  * @obj: a pointer to the #AccessibleTable implementor on which to operate.
686  * @row:
687  * @column:
688  *
689  * Determine whether the cell at a specific row and column is selected.
690  *
691  * Returns: #TRUE if the specified cell is currently selected, #FALSE if not.
692  **/
693 SPIBoolean
694 AccessibleTable_isSelected (AccessibleTable *obj,
695                             long int row,
696                             long int column)
697 {
698   SPIBoolean retval;
699
700   cspi_return_val_if_fail (obj != NULL, FALSE);
701
702   retval =
703     Accessibility_Table_isSelected (CSPI_OBJREF (obj),
704                                     (CORBA_long) row,
705                                     (CORBA_long) column, cspi_ev ());
706           
707   cspi_return_val_if_ev ("isSelected", FALSE);
708
709   return retval;
710 }
711