cspi/spi_text.c

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001, 2002 Sun Microsystems Inc.,
   6  * Copyright 2001, 2002 Ximian, Inc.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #include <cspi/spi-private.h>
  25
  26 static Accessibility_TEXT_BOUNDARY_TYPE
  27 get_accessible_text_boundary_type (AccessibleTextBoundaryType type)
  28 {
  29   switch (type)
  30     {
  31     case SPI_TEXT_BOUNDARY_CHAR:
  32       return Accessibility_TEXT_BOUNDARY_CHAR;
  33       break;
  34     case SPI_TEXT_BOUNDARY_CURSOR_POS:
  35       /* FixME */
  36       return Accessibility_TEXT_BOUNDARY_CHAR;
  37       break;
  38     case SPI_TEXT_BOUNDARY_WORD_START:
  39       return Accessibility_TEXT_BOUNDARY_WORD_START;
  40       break;
  41     case SPI_TEXT_BOUNDARY_WORD_END:
  42       return Accessibility_TEXT_BOUNDARY_WORD_END;
  43       break;
  44     case SPI_TEXT_BOUNDARY_SENTENCE_START:
  45       return Accessibility_TEXT_BOUNDARY_SENTENCE_START;
  46       break;
  47     case SPI_TEXT_BOUNDARY_SENTENCE_END:
  48       return Accessibility_TEXT_BOUNDARY_SENTENCE_END;
  49       break;
  50     case SPI_TEXT_BOUNDARY_LINE_START:
  51       return Accessibility_TEXT_BOUNDARY_LINE_START;
  52       break;
  53     case SPI_TEXT_BOUNDARY_LINE_END:
  54       return Accessibility_TEXT_BOUNDARY_LINE_END;
  55       break;
  56     case SPI_TEXT_BOUNDARY_ATTRIBUTE_RANGE:
  57       /* Fixme */
  58       return Accessibility_TEXT_BOUNDARY_CHAR;
  59       break;
  60     }
  61 }
  62
  63
  64 /**
  65  * AccessibleText_ref:
  66  * @obj: a pointer to the #AccessibleText object on which to operate.
  67  *
  68  * Increment the reference count for an #AccessibleText object.
  69  **/
  70 void
  71 AccessibleText_ref (AccessibleText *obj)
  72 {
  73   cspi_object_ref (obj);
  74 }
  75
  76 /**
  77  * AccessibleText_unref:
  78  * @obj: a pointer to the #Accessible object on which to operate.
  79  *
  80  * Decrement the reference count for an #AccessibleText object.
  81  **/
  82 void
  83 AccessibleText_unref (AccessibleText *obj)
  84 {
  85   cspi_object_unref (obj);
  86 }
  87
  88 /**
  89  * AccessibleText_getCharacterCount:
  90  * @obj: a pointer to the #AccessibleText object to query.
  91  *
  92  * Get the character count of an #AccessibleText object.
  93  *
  94  * Returns: a long integer indicating the total number of
  95  *              characters in the #AccessibleText object.
  96  **/
  97 long
  98 AccessibleText_getCharacterCount (AccessibleText *obj)
  99 {
 100   long retval;
 101
 102   cspi_return_val_if_fail (obj != NULL, -1);
 103
 104   retval = Accessibility_Text__get_characterCount (CSPI_OBJREF (obj), cspi_ev ());
 105
 106   cspi_return_val_if_ev ("getCharacterCount", -1);
 107
 108   return retval;
 109 }
 110
 111 /**
 112  * AccessibleText_getText:
 113  * @obj: a pointer to the #AccessibleText object to query.
 114  * @startOffset: a #long indicating the start of the desired text range.
 115  * @endOffset: a #long indicating the first character past the desired range.
 116  *
 117  * Get a range of text from an #AccessibleText object.  The number of bytes
 118  *          in the returned string may exceed endOffset-startOffset, since
 119  *          UTF-8 is a variable-width encoding.
 120  *
 121  * Returns: a text string containing characters from @startOffset
 122  *          to @endOffset-1, inclusive, encoded as UTF-8.
 123  **/
 124 char *
 125 AccessibleText_getText (AccessibleText *obj,
 126                         long int startOffset,
 127                         long int endOffset)
 128 {
 129   char *retval;
 130
 131   cspi_return_val_if_fail (obj != NULL, NULL);
 132
 133   retval =
 134     Accessibility_Text_getText (CSPI_OBJREF (obj),
 135                                 startOffset,
 136                                 endOffset,
 137                                 cspi_ev ());
 138
 139   cspi_return_val_if_ev ("getText", NULL);
 140
 141   return retval;
 142 }
 143
 144 /**
 145  * AccessibleText_getCaretOffset:
 146  * @obj: a pointer to the #AccessibleText object to query.
 147  *
 148  * Get the current offset of the text caret in an #AccessibleText object.
 149  *
 150  * Returns: a long integer indicating the current position of the text caret.
 151  **/
 152 long
 153 AccessibleText_getCaretOffset (AccessibleText *obj)
 154 {
 155   long retval;
 156
 157   cspi_return_val_if_fail (obj != NULL, -1);
 158
 159   retval =
 160     Accessibility_Text__get_caretOffset (CSPI_OBJREF (obj), cspi_ev ());
 161
 162   cspi_return_val_if_ev ("getCaretOffset", -1);
 163
 164   return retval;
 165 }
 166
 167 /**
 168  * AccessibleText_getAttributes:
 169  * @obj: a pointer to the #AccessibleText object to query.
 170  * @offset: a long integer indicating the offset from which the attribute
 171  *        search is based.
 172  * @startOffset: a #long indicating the start of the desired text range.
 173  * @endOffset: a #long indicating the first character past the desired range.
 174  *
 175  * Get the attributes applied to a range of text from an #AccessibleText
 176  *          object, and the bounds of the range.
 177  *
 178  * Returns: a text string describing the attributes occurring within the
 179  *          attribute run containing @offset, encoded as UTF-8 and
 180  *          delimited by ':'
 181  **/
 182 char *
 183 AccessibleText_getAttributes (AccessibleText *obj,
 184                               long int offset,
 185                               long int *startOffset,
 186                               long int *endOffset)
 187 {
 188   CORBA_long retStartOffset, retEndOffset;
 189   char *retval;
 190
 191   if (obj == NULL)
 192     {
 193       *startOffset = *endOffset = -1;
 194       return NULL;
 195     }
 196
 197   retval = Accessibility_Text_getAttributes (CSPI_OBJREF (obj),
 198                                       offset,
 199                                       &retStartOffset,
 200                                       &retEndOffset,
 201                                       cspi_ev ());
 202
 203   if (!cspi_check_ev ("getAttributes"))
 204     {
 205       *startOffset = *endOffset = -1;
 206       retval = NULL;
 207     }
 208   else
 209     {
 210       *startOffset = retStartOffset;
 211       *endOffset   = retEndOffset;
 212     }
 213
 214   return retval;
 215 }
 216
 217 /**
 218  * AccessibleText_setCaretOffset:
 219  * @obj: a pointer to the #AccessibleText object on which to operate.
 220  * @newOffset: the offset to which the text caret is to be moved.
 221  *
 222  * Set the text caret position for an #AccessibleText object.
 223  *
 224  * Returns: #TRUE if successful, #FALSE otherwise.
 225  **/
 226 SPIBoolean
 227 AccessibleText_setCaretOffset (AccessibleText *obj,
 228                                long int newOffset)
 229 {
 230   SPIBoolean retval;
 231
 232   cspi_return_val_if_fail (obj != NULL, FALSE);
 233
 234   retval =
 235     Accessibility_Text_setCaretOffset (CSPI_OBJREF (obj),
 236                                        newOffset, cspi_ev ());
 237
 238   cspi_return_val_if_ev ("setCaretOffset", FALSE);
 239
 240   return retval;
 241 }
 242
 243 /**
 244  * AccessibleText_getTextBeforeOffset:
 245  * @obj: a pointer to the #AccessibleText object on which to operate.
 246  * @offset: a long integer indicating the offset from which the delimiter
 247  *        search is based.
 248  * @type: an #AccessibleTextBoundaryType indicating whether the desired
 249  *       text string is a word, sentence, line, or attribute run.
 250  * @startOffset: a pointer to a long integer which is assigned the
 251  *       starting offset of the returned string, relative to the
 252  *       original #AccessibleText.
 253  * @endOffset: a pointer to a long integer which is assigned the
 254  *       ending offset of the returned string, relative to the original
 255  *       #AccessibleText.
 256  *
 257  * Get delimited text from an #AccessibleText object which precedes a given
 258  *          text offset.
 259  *
 260  * Returns: a UTF-8 string representing the delimited text, both of whose
 261  *          delimiting boundaries are before the current offset, or
 262  *          an empty string if no such text exists.
 263  **/
 264 char *
 265 AccessibleText_getTextBeforeOffset (AccessibleText *obj,
 266                                     long int offset,
 267                                     AccessibleTextBoundaryType type,
 268                                     long int *startOffset,
 269                                     long int *endOffset)
 270 {
 271   char *retval;
 272   CORBA_long retStartOffset, retEndOffset;
 273
 274   if (obj == NULL)
 275     {
 276       *startOffset = *endOffset = -1;
 277       return NULL;
 278     }
 279
 280   retval = Accessibility_Text_getTextBeforeOffset (CSPI_OBJREF (obj),
 281                                            offset,
 282                         get_accessible_text_boundary_type (type),
 283                                            &retStartOffset, &retEndOffset,
 284                                            cspi_ev ());
 285   if (!cspi_check_ev ("getTextBeforeOffset"))
 286     {
 287       *startOffset = *endOffset = -1;
 288       retval = NULL;
 289     }
 290   else
 291     {
 292       *startOffset = retStartOffset;
 293       *endOffset = retEndOffset;
 294     }
 295   return retval;
 296 }
 297
 298 /**
 299  * AccessibleText_getTextAtOffset:
 300  * @obj: a pointer to the #AccessibleText object on which to operate.
 301  * @offset: a long integer indicating the offset from which the delimiter
 302  *        search is based.
 303  * @type: an #AccessibleTextBoundaryType indicating whether the desired
 304  *       text string is a word, sentence, line, or attribute run.
 305  * @startOffset: a pointer to a long integer which is assigned the
 306  *       starting offset of the returned string, relative to the
 307  *       original #AccessibleText.
 308  * @endOffset: a pointer to a long integer which is assigned the
 309  *       ending offset of the returned string, relative to the original
 310  *       #AccessibleText.
 311  *
 312  * Get delimited text from an #AccessibleText object which includes a given
 313  *          text offset.
 314  *
 315  * Returns: a UTF-8 string representing the delimited text, whose
 316  *          delimiting boundaries bracket the current offset, or
 317  *          an empty string if no such text exists.
 318  **/
 319 char *
 320 AccessibleText_getTextAtOffset (AccessibleText *obj,
 321                                 long int offset,
 322                                 AccessibleTextBoundaryType type,
 323                                 long int *startOffset, long int *endOffset)
 324 {
 325   CORBA_long corbaStartOffset;
 326   CORBA_long corbaEndOffset;
 327   char      *retval;
 328
 329   if (obj == NULL)
 330     {
 331       *startOffset = *endOffset = -1;
 332       return NULL;
 333     }
 334
 335   retval = Accessibility_Text_getTextAtOffset (CSPI_OBJREF (obj),
 336                                                offset,
 337                           get_accessible_text_boundary_type (type),
 338                                                &corbaStartOffset,
 339                                                &corbaEndOffset,
 340                                                cspi_ev ());
 341
 342   if (!cspi_check_ev ("getTextAtOffset"))
 343     {
 344       *startOffset = *endOffset = -1;
 345       retval = NULL;
 346     }
 347   else
 348     {
 349       *startOffset = corbaStartOffset;
 350       *endOffset   = corbaEndOffset;
 351     }
 352   return retval;
 353 }
 354
 355 /**
 356  * AccessibleText_getTextAfterOffset:
 357  * @obj: a pointer to the #AccessibleText object on which to operate.
 358  * @offset: a long integer indicating the offset from which the delimiter
 359  *        search is based.
 360  * @type: an #AccessibleTextBoundaryType indicating whether the desired
 361  *       text string is a word, sentence, line, or attribute run.
 362  * @startOffset: a pointer to a long integer which is assigned the
 363  *       starting offset of the returned string, relative to the
 364  *       original #AccessibleText.
 365  * @endOffset: a pointer to a long integer which is assigned the
 366  *       ending offset of the returned string, relative to the original
 367  *       #AccessibleText.
 368  *
 369  * Get delimited text from an #AccessibleText object which follows a given
 370  *          text offset.
 371  *
 372  * Returns: a UTF-8 string representing the delimited text, both of whose
 373  *          delimiting boundaries are after or inclusive of the current
 374  *          offset, or an empty string if no such text exists.
 375  **/
 376 char *
 377 AccessibleText_getTextAfterOffset (AccessibleText *obj,
 378                                    long int offset,
 379                                    AccessibleTextBoundaryType type,
 380                                    long int *startOffset, long int *endOffset)
 381 {
 382   char *retval;
 383   CORBA_long retStartOffset, retEndOffset;
 384
 385   if (obj == NULL)
 386     {
 387       *startOffset = *endOffset = -1;
 388       return NULL;
 389     }
 390
 391   retval = Accessibility_Text_getTextAfterOffset (CSPI_OBJREF (obj),
 392                                            offset,
 393                              get_accessible_text_boundary_type (type),
 394                                            &retStartOffset, &retEndOffset,
 395                                            cspi_ev ());
 396
 397   if (!cspi_check_ev ("getTextAfterOffset"))
 398     {
 399       *startOffset = *endOffset = -1;
 400       retval = NULL;
 401     }
 402   else
 403     {
 404       *startOffset = retStartOffset;
 405       *endOffset   = retEndOffset;
 406     }
 407   return retval;
 408 }
 409
 410 /**
 411  * AccessibleText_getCharacterAtOffset:
 412  * @obj: a pointer to the #AccessibleText object on which to operate.
 413  * @offset: a long integer indicating the text offset where the desired
 414  *          character is located.
 415  *
 416  * Get the character at a given offset for an #AccessibleText object.
 417  *
 418  * Returns: an #unsigned long integer which represents the
 419  *        UCS-4 unicode code point of the given character, or
 420  *        0xFFFFFFFF if the character in question cannot be represented
 421  *        in the UCS-4 encoding.
 422  **/
 423 unsigned long
 424 AccessibleText_getCharacterAtOffset (AccessibleText *obj,
 425                                      long int offset)
 426 {
 427   long retval;
 428
 429   cspi_return_val_if_fail (obj != NULL, -1);
 430
 431   retval =
 432     Accessibility_Text_getCharacterAtOffset (CSPI_OBJREF (obj),
 433                                              offset,
 434                                              cspi_ev ());
 435
 436   cspi_return_val_if_ev ("getCharacterAtOffset", -1);
 437
 438   return retval;
 439 }
 440
 441 /**
 442  * AccessibleText_getCharacterExtents:
 443  * @obj: a pointer to the #AccessibleText object on which to operate.
 444  * @offset: an integer indicating the offset of the text character for
 445  *        whom boundary information is requested.
 446  * @x: a pointer to a long integer into which the nominal x coordinate
 447  *     of the corresponding glyph will be returned.
 448  * @y:a pointer to a long integer into which the nominal y coordinate
 449  *     of the corresponding glyph will be returned.
 450  * @width:a pointer to a long integer into which the width
 451  *     of the corresponding glyph will be returned.
 452  * @height: a pointer to a long integer into which the height
 453  *     of the corresponding glyph will be returned.
 454  * @type: an #AccessibleCoordType indicating the coordinate system to use
 455  *        for the returned values.
 456  *
 457  * Get the bounding box containing the glyph representing
 458  *        the character at a particular text offset.
 459  **/
 460 void
 461 AccessibleText_getCharacterExtents (AccessibleText *obj,
 462                                     long int offset,
 463                                     long int *x,
 464                                     long int *y,
 465                                     long int *width,
 466                                     long int *height,
 467                                     AccessibleCoordType type)
 468 {
 469   CORBA_long retX, retY, retWidth, retHeight;
 470
 471   if (obj == NULL)
 472     {
 473       *x = *y = -1;
 474       *width = *height = -1;
 475       return;
 476     }
 477
 478   Accessibility_Text_getCharacterExtents (CSPI_OBJREF (obj),
 479                                           offset,
 480                                           &retX,
 481                                           &retY,
 482                                           &retWidth,
 483                                           &retHeight,
 484                                           type, cspi_ev ());
 485
 486   if (!cspi_check_ev ("getCharacterExtents"))
 487     {
 488       *x = *y = -1;
 489       *width = *height = -1;
 490     }
 491   else
 492     {
 493       *x = retX;
 494       *y = retY;
 495       *width = retWidth;
 496       *height = retHeight;
 497     }
 498 }
 499
 500 /**
 501  * AccessibleText_getOffsetAtPoint:
 502  * @obj: a pointer to the #AccessibleText object on which to operate.
 503  * @x: the x coordinate of the point to be queried.
 504  * @y: the y coordinate of the point to be queried.
 505  * @type: an #AccessibleCoordType indicating the coordinate system in which
 506  *       the values should be returned.
 507  *
 508  * Get the bounding box for a glyph at a certain #AccessibleText offset.
 509  *
 510  * Returns: the offset (as a long integer) at the point (@x, @y)
 511  *       in the specified coordinate system.
 512  *
 513  **/
 514 long
 515 AccessibleText_getOffsetAtPoint (AccessibleText *obj,
 516                                  long int x,
 517                                  long int y,
 518                                  AccessibleCoordType type)
 519 {
 520   long retval;
 521
 522   cspi_return_val_if_fail (obj != NULL, -1);
 523
 524   retval =
 525     Accessibility_Text_getOffsetAtPoint (CSPI_OBJREF (obj),
 526                                          x,
 527                                          y,
 528                                          type, cspi_ev ());
 529
 530   cspi_return_val_if_ev ("getOffsetAtPoint", -1);
 531
 532   return retval;
 533 }
 534
 535 /**
 536  * AccessibleText_getNSelections:
 537  * @obj: a pointer to the #AccessibleText object on which to operate.
 538  *
 539  * Get the number of active non-contiguous selections for an
 540  *          #AccessibleText object.
 541  *
 542  * Returns: a long integer indicating the current
 543  *          number of non-contiguous text selections active
 544  *          within an #AccessibleText object.
 545  **/
 546 long
 547 AccessibleText_getNSelections (AccessibleText *obj)
 548 {
 549   long retval;
 550
 551   cspi_return_val_if_fail (obj != NULL, -1);
 552
 553   retval =
 554     Accessibility_Text_getNSelections (CSPI_OBJREF (obj), cspi_ev ());
 555
 556   cspi_return_val_if_ev ("getNSelections", -1);
 557
 558   return retval;
 559 }
 560
 561 /**
 562  * AccessibleText_getSelection:
 563  * @obj: a pointer to the #AccessibleText object on which to operate.
 564  * @selectionNum: an integer indicating which selection to query.
 565  * @startOffset: a pointer to a long integer into which the start offset
 566  *           of the selection will be returned.
 567  * @endOffset: a pointer to a long integer into which the start offset
 568  *           of the selection will be returned.
 569  *
 570  * Get the bounds of the @selectionNum-th active text selection for an
 571  *         #AccessibleText object.
 572  **/
 573 void
 574 AccessibleText_getSelection (AccessibleText *obj,
 575                              long int selectionNum,
 576                              long int *startOffset,
 577                              long int *endOffset)
 578 {
 579   CORBA_long retStartOffset, retEndOffset;
 580
 581   if (obj == NULL)
 582     {
 583       *endOffset = *startOffset = -1;
 584       return;
 585     }
 586
 587   Accessibility_Text_getSelection (CSPI_OBJREF (obj),
 588                                    selectionNum,
 589                                    &retStartOffset, &retEndOffset,
 590                                    cspi_ev ());
 591
 592   if (!cspi_check_ev ("getSelection"))
 593     {
 594       *startOffset = *endOffset = -1;
 595     }
 596   else
 597     {
 598       *startOffset = retStartOffset;
 599       *endOffset   = retEndOffset;
 600     }
 601 }
 602
 603 /**
 604  * AccessibleText_addSelection:
 605  * @obj: a pointer to the #AccessibleText object on which to operate.
 606  * @startOffset: the starting offset of the desired new selection.
 607  * @endOffset: the offset of the first character after the new selection.
 608  *
 609  * Select some text (add a text selection) in an #AccessibleText object.
 610  *
 611  * Returns: #TRUE if successful, #FALSE otherwise.
 612  **/
 613 SPIBoolean
 614 AccessibleText_addSelection (AccessibleText *obj,
 615                              long int startOffset, long int endOffset)
 616 {
 617   SPIBoolean retval;
 618
 619   cspi_return_val_if_fail (obj != NULL, FALSE);
 620
 621   retval =
 622     Accessibility_Text_addSelection (
 623       CSPI_OBJREF (obj), startOffset,
 624       endOffset, cspi_ev ());
 625
 626   cspi_return_val_if_ev ("addSelection", FALSE);
 627
 628   return retval;
 629 }
 630
 631 /**
 632  * AccessibleText_removeSelection:
 633  * @obj: a pointer to the #AccessibleText object on which to operate.
 634  * @selectionNum: an integer indicating which (possibly of several)
 635  *         text selection to remove.
 636  *
 637  * De-select a text selection.
 638  *
 639  * Returns: #TRUE if successful, #FALSE otherwise.
 640  **/
 641 SPIBoolean
 642 AccessibleText_removeSelection (AccessibleText *obj,
 643                                 long int selectionNum)
 644 {
 645   SPIBoolean retval;
 646
 647   cspi_return_val_if_fail (obj != NULL, FALSE);
 648
 649   retval =
 650     Accessibility_Text_removeSelection (
 651       CSPI_OBJREF (obj), selectionNum, cspi_ev ());
 652
 653   cspi_return_val_if_ev ("removeSelection", FALSE);
 654
 655   return retval;
 656 }
 657
 658 /**
 659  * AccessibleText_setSelection:
 660  * @obj: a pointer to the #AccessibleText object on which to operate.
 661  * @selectionNum: a zero-offset index indicating which text selection to modify.
 662  * @startOffset: a long int, the new starting offset for the selection.
 663  * @endOffset: a long int, the desired new offset of the first character
 664  *             after the selection.
 665  *
 666  * Change the bounds of an existing #AccessibleText text selection.
 667  *
 668  * Returns: #TRUE if successful, #FALSE otherwise.
 669  **/
 670 SPIBoolean
 671 AccessibleText_setSelection (AccessibleText *obj,
 672                              long int selectionNum,
 673                              long int startOffset,
 674                              long int endOffset)
 675 {
 676   SPIBoolean retval;
 677
 678   cspi_return_val_if_fail (obj != NULL, FALSE);
 679
 680   retval = Accessibility_Text_setSelection (CSPI_OBJREF (obj),
 681                                    selectionNum,
 682                                    startOffset,
 683                                    endOffset, cspi_ev ());
 684
 685   cspi_return_val_if_ev ("setSelection", FALSE);
 686
 687   return retval;
 688 }
 689
 690
 691