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