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  *          The text attributes correspond to CSS attributes where possible,
 178  *          keys and values are delimited from one another via ":", and
 179  *          the delimiter between key/value pairs is ";". Thus
 180  *          "font-size:10;foreground-color:0,0,0" would be a valid
 181  *          return string.
 182  *
 183  * Returns: a text string describing the attributes occurring within the
 184  *          attribute run containing @offset, encoded as UTF-8.
 185  **/
 186 char *
 187 AccessibleText_getAttributes (AccessibleText *obj,
 188                               long int offset,
 189                               long int *startOffset,
 190                               long int *endOffset)
 191 {
 192   CORBA_long retStartOffset, retEndOffset;
 193   char *retval;
 194
 195   if (obj == NULL)
 196     {
 197       *startOffset = *endOffset = -1;
 198       return NULL;
 199     }
 200
 201   retval = Accessibility_Text_getAttributes (CSPI_OBJREF (obj),
 202                                       offset,
 203                                       &retStartOffset,
 204                                       &retEndOffset,
 205                                       cspi_ev ());
 206
 207   if (!cspi_check_ev ("getAttributes"))
 208     {
 209       *startOffset = *endOffset = -1;
 210       retval = NULL;
 211     }
 212   else
 213     {
 214       *startOffset = retStartOffset;
 215       *endOffset   = retEndOffset;
 216     }
 217
 218   return retval;
 219 }
 220
 221 /**
 222  * AccessibleText_setCaretOffset:
 223  * @obj: a pointer to the #AccessibleText object on which to operate.
 224  * @newOffset: the offset to which the text caret is to be moved.
 225  *
 226  * Set the text caret position for an #AccessibleText object.
 227  *
 228  * Returns: #TRUE if successful, #FALSE otherwise.
 229  **/
 230 SPIBoolean
 231 AccessibleText_setCaretOffset (AccessibleText *obj,
 232                                long int newOffset)
 233 {
 234   SPIBoolean retval;
 235
 236   cspi_return_val_if_fail (obj != NULL, FALSE);
 237
 238   retval =
 239     Accessibility_Text_setCaretOffset (CSPI_OBJREF (obj),
 240                                        newOffset, cspi_ev ());
 241
 242   cspi_return_val_if_ev ("setCaretOffset", FALSE);
 243
 244   return retval;
 245 }
 246
 247 /**
 248  * AccessibleText_getTextBeforeOffset:
 249  * @obj: a pointer to the #AccessibleText object on which to operate.
 250  * @offset: a long integer indicating the offset from which the delimiter
 251  *        search is based.
 252  * @type: an #AccessibleTextBoundaryType indicating whether the desired
 253  *       text string is a word, sentence, line, or attribute run.
 254  * @startOffset: a pointer to a long integer which is assigned the
 255  *       starting offset of the returned string, relative to the
 256  *       original #AccessibleText.
 257  * @endOffset: a pointer to a long integer which is assigned the
 258  *       ending offset of the returned string, relative to the original
 259  *       #AccessibleText.
 260  *
 261  * Get delimited text from an #AccessibleText object which precedes a given
 262  *          text offset.
 263  *
 264  * Returns: a UTF-8 string representing the delimited text, both of whose
 265  *          delimiting boundaries are before the current offset, or
 266  *          an empty string if no such text exists.
 267  **/
 268 char *
 269 AccessibleText_getTextBeforeOffset (AccessibleText *obj,
 270                                     long int offset,
 271                                     AccessibleTextBoundaryType type,
 272                                     long int *startOffset,
 273                                     long int *endOffset)
 274 {
 275   char *retval;
 276   CORBA_long retStartOffset, retEndOffset;
 277
 278   if (obj == NULL)
 279     {
 280       *startOffset = *endOffset = -1;
 281       return NULL;
 282     }
 283
 284   retval = Accessibility_Text_getTextBeforeOffset (CSPI_OBJREF (obj),
 285                                            offset,
 286                         get_accessible_text_boundary_type (type),
 287                                            &retStartOffset, &retEndOffset,
 288                                            cspi_ev ());
 289   if (!cspi_check_ev ("getTextBeforeOffset"))
 290     {
 291       *startOffset = *endOffset = -1;
 292       retval = NULL;
 293     }
 294   else
 295     {
 296       *startOffset = retStartOffset;
 297       *endOffset = retEndOffset;
 298     }
 299   return retval;
 300 }
 301
 302 /**
 303  * AccessibleText_getTextAtOffset:
 304  * @obj: a pointer to the #AccessibleText object on which to operate.
 305  * @offset: a long integer indicating the offset from which the delimiter
 306  *        search is based.
 307  * @type: an #AccessibleTextBoundaryType indicating whether the desired
 308  *       text string is a word, sentence, line, or attribute run.
 309  * @startOffset: a pointer to a long integer which is assigned the
 310  *       starting offset of the returned string, relative to the
 311  *       original #AccessibleText.
 312  * @endOffset: a pointer to a long integer which is assigned the
 313  *       ending offset of the returned string, relative to the original
 314  *       #AccessibleText.
 315  *
 316  * Get delimited text from an #AccessibleText object which includes a given
 317  *          text offset.
 318  *
 319  * Returns: a UTF-8 string representing the delimited text, whose
 320  *          delimiting boundaries bracket the current offset, or
 321  *          an empty string if no such text exists.
 322  **/
 323 char *
 324 AccessibleText_getTextAtOffset (AccessibleText *obj,
 325                                 long int offset,
 326                                 AccessibleTextBoundaryType type,
 327                                 long int *startOffset, long int *endOffset)
 328 {
 329   CORBA_long corbaStartOffset;
 330   CORBA_long corbaEndOffset;
 331   char      *retval;
 332
 333   if (obj == NULL)
 334     {
 335       *startOffset = *endOffset = -1;
 336       return NULL;
 337     }
 338
 339   retval = Accessibility_Text_getTextAtOffset (CSPI_OBJREF (obj),
 340                                                offset,
 341                           get_accessible_text_boundary_type (type),
 342                                                &corbaStartOffset,
 343                                                &corbaEndOffset,
 344                                                cspi_ev ());
 345
 346   if (!cspi_check_ev ("getTextAtOffset"))
 347     {
 348       *startOffset = *endOffset = -1;
 349       retval = NULL;
 350     }
 351   else
 352     {
 353       *startOffset = corbaStartOffset;
 354       *endOffset   = corbaEndOffset;
 355     }
 356   return retval;
 357 }
 358
 359 /**
 360  * AccessibleText_getTextAfterOffset:
 361  * @obj: a pointer to the #AccessibleText object on which to operate.
 362  * @offset: a long integer indicating the offset from which the delimiter
 363  *        search is based.
 364  * @type: an #AccessibleTextBoundaryType indicating whether the desired
 365  *       text string is a word, sentence, line, or attribute run.
 366  * @startOffset: a pointer to a long integer which is assigned the
 367  *       starting offset of the returned string, relative to the
 368  *       original #AccessibleText.
 369  * @endOffset: a pointer to a long integer which is assigned the
 370  *       ending offset of the returned string, relative to the original
 371  *       #AccessibleText.
 372  *
 373  * Get delimited text from an #AccessibleText object which follows a given
 374  *          text offset.
 375  *
 376  * Returns: a UTF-8 string representing the delimited text, both of whose
 377  *          delimiting boundaries are after or inclusive of the current
 378  *          offset, or an empty string if no such text exists.
 379  **/
 380 char *
 381 AccessibleText_getTextAfterOffset (AccessibleText *obj,
 382                                    long int offset,
 383                                    AccessibleTextBoundaryType type,
 384                                    long int *startOffset, long int *endOffset)
 385 {
 386   char *retval;
 387   CORBA_long retStartOffset, retEndOffset;
 388
 389   if (obj == NULL)
 390     {
 391       *startOffset = *endOffset = -1;
 392       return NULL;
 393     }
 394
 395   retval = Accessibility_Text_getTextAfterOffset (CSPI_OBJREF (obj),
 396                                            offset,
 397                              get_accessible_text_boundary_type (type),
 398                                            &retStartOffset, &retEndOffset,
 399                                            cspi_ev ());
 400
 401   if (!cspi_check_ev ("getTextAfterOffset"))
 402     {
 403       *startOffset = *endOffset = -1;
 404       retval = NULL;
 405     }
 406   else
 407     {
 408       *startOffset = retStartOffset;
 409       *endOffset   = retEndOffset;
 410     }
 411   return retval;
 412 }
 413
 414 /**
 415  * AccessibleText_getCharacterAtOffset:
 416  * @obj: a pointer to the #AccessibleText object on which to operate.
 417  * @offset: a long integer indicating the text offset where the desired
 418  *          character is located.
 419  *
 420  * Get the character at a given offset for an #AccessibleText object.
 421  *
 422  * Returns: an #unsigned long integer which represents the
 423  *        UCS-4 unicode code point of the given character, or
 424  *        0xFFFFFFFF if the character in question cannot be represented
 425  *        in the UCS-4 encoding.
 426  **/
 427 unsigned long
 428 AccessibleText_getCharacterAtOffset (AccessibleText *obj,
 429                                      long int offset)
 430 {
 431   long retval;
 432
 433   cspi_return_val_if_fail (obj != NULL, -1);
 434
 435   retval =
 436     Accessibility_Text_getCharacterAtOffset (CSPI_OBJREF (obj),
 437                                              offset,
 438                                              cspi_ev ());
 439
 440   cspi_return_val_if_ev ("getCharacterAtOffset", -1);
 441
 442   return retval;
 443 }
 444
 445 /**
 446  * AccessibleText_getCharacterExtents:
 447  * @obj: a pointer to the #AccessibleText object on which to operate.
 448  * @offset: an integer indicating the offset of the text character for
 449  *        whom boundary information is requested.
 450  * @x: a pointer to a long integer into which the nominal x coordinate
 451  *     of the corresponding glyph will be returned.
 452  * @y:a pointer to a long integer into which the nominal y coordinate
 453  *     of the corresponding glyph will be returned.
 454  * @width:a pointer to a long integer into which the width
 455  *     of the corresponding glyph will be returned.
 456  * @height: a pointer to a long integer into which the height
 457  *     of the corresponding glyph will be returned.
 458  * @type: an #AccessibleCoordType indicating the coordinate system to use
 459  *        for the returned values.
 460  *
 461  * Get the bounding box containing the glyph representing
 462  *        the character at a particular text offset.
 463  **/
 464 void
 465 AccessibleText_getCharacterExtents (AccessibleText *obj,
 466                                     long int offset,
 467                                     long int *x,
 468                                     long int *y,
 469                                     long int *width,
 470                                     long int *height,
 471                                     AccessibleCoordType type)
 472 {
 473   CORBA_long retX, retY, retWidth, retHeight;
 474
 475   if (obj == NULL)
 476     {
 477       *x = *y = -1;
 478       *width = *height = -1;
 479       return;
 480     }
 481
 482   Accessibility_Text_getCharacterExtents (CSPI_OBJREF (obj),
 483                                           offset,
 484                                           &retX,
 485                                           &retY,
 486                                           &retWidth,
 487                                           &retHeight,
 488                                           type, cspi_ev ());
 489
 490   if (!cspi_check_ev ("getCharacterExtents"))
 491     {
 492       *x = *y = -1;
 493       *width = *height = -1;
 494     }
 495   else
 496     {
 497       *x = retX;
 498       *y = retY;
 499       *width = retWidth;
 500       *height = retHeight;
 501     }
 502 }
 503
 504 /**
 505  * AccessibleText_getOffsetAtPoint:
 506  * @obj: a pointer to the #AccessibleText object on which to operate.
 507  * @x: the x coordinate of the point to be queried.
 508  * @y: the y coordinate of the point to be queried.
 509  * @type: an #AccessibleCoordType indicating the coordinate system in which
 510  *       the values should be returned.
 511  *
 512  * Get the bounding box for a glyph at a certain #AccessibleText offset.
 513  *
 514  * Returns: the offset (as a long integer) at the point (@x, @y)
 515  *       in the specified coordinate system.
 516  *
 517  **/
 518 long
 519 AccessibleText_getOffsetAtPoint (AccessibleText *obj,
 520                                  long int x,
 521                                  long int y,
 522                                  AccessibleCoordType type)
 523 {
 524   long retval;
 525
 526   cspi_return_val_if_fail (obj != NULL, -1);
 527
 528   retval =
 529     Accessibility_Text_getOffsetAtPoint (CSPI_OBJREF (obj),
 530                                          x,
 531                                          y,
 532                                          type, cspi_ev ());
 533
 534   cspi_return_val_if_ev ("getOffsetAtPoint", -1);
 535
 536   return retval;
 537 }
 538
 539 /**
 540  * AccessibleText_getNSelections:
 541  * @obj: a pointer to the #AccessibleText object on which to operate.
 542  *
 543  * Get the number of active non-contiguous selections for an
 544  *          #AccessibleText object.
 545  *
 546  * Returns: a long integer indicating the current
 547  *          number of non-contiguous text selections active
 548  *          within an #AccessibleText object.
 549  **/
 550 long
 551 AccessibleText_getNSelections (AccessibleText *obj)
 552 {
 553   long retval;
 554
 555   cspi_return_val_if_fail (obj != NULL, -1);
 556
 557   retval =
 558     Accessibility_Text_getNSelections (CSPI_OBJREF (obj), cspi_ev ());
 559
 560   cspi_return_val_if_ev ("getNSelections", -1);
 561
 562   return retval;
 563 }
 564
 565 /**
 566  * AccessibleText_getSelection:
 567  * @obj: a pointer to the #AccessibleText object on which to operate.
 568  * @selectionNum: an integer indicating which selection to query.
 569  * @startOffset: a pointer to a long integer into which the start offset
 570  *           of the selection will be returned.
 571  * @endOffset: a pointer to a long integer into which the start offset
 572  *           of the selection will be returned.
 573  *
 574  * Get the bounds of the @selectionNum-th active text selection for an
 575  *         #AccessibleText object.
 576  **/
 577 void
 578 AccessibleText_getSelection (AccessibleText *obj,
 579                              long int selectionNum,
 580                              long int *startOffset,
 581                              long int *endOffset)
 582 {
 583   CORBA_long retStartOffset, retEndOffset;
 584
 585   if (obj == NULL)
 586     {
 587       *endOffset = *startOffset = -1;
 588       return;
 589     }
 590
 591   Accessibility_Text_getSelection (CSPI_OBJREF (obj),
 592                                    selectionNum,
 593                                    &retStartOffset, &retEndOffset,
 594                                    cspi_ev ());
 595
 596   if (!cspi_check_ev ("getSelection"))
 597     {
 598       *startOffset = *endOffset = -1;
 599     }
 600   else
 601     {
 602       *startOffset = retStartOffset;
 603       *endOffset   = retEndOffset;
 604     }
 605 }
 606
 607 /**
 608  * AccessibleText_addSelection:
 609  * @obj: a pointer to the #AccessibleText object on which to operate.
 610  * @startOffset: the starting offset of the desired new selection.
 611  * @endOffset: the offset of the first character after the new selection.
 612  *
 613  * Select some text (add a text selection) in an #AccessibleText object.
 614  *
 615  * Returns: #TRUE if successful, #FALSE otherwise.
 616  **/
 617 SPIBoolean
 618 AccessibleText_addSelection (AccessibleText *obj,
 619                              long int startOffset, long int endOffset)
 620 {
 621   SPIBoolean retval;
 622
 623   cspi_return_val_if_fail (obj != NULL, FALSE);
 624
 625   retval =
 626     Accessibility_Text_addSelection (
 627       CSPI_OBJREF (obj), startOffset,
 628       endOffset, cspi_ev ());
 629
 630   cspi_return_val_if_ev ("addSelection", FALSE);
 631
 632   return retval;
 633 }
 634
 635 /**
 636  * AccessibleText_removeSelection:
 637  * @obj: a pointer to the #AccessibleText object on which to operate.
 638  * @selectionNum: an integer indicating which (possibly of several)
 639  *         text selection to remove.
 640  *
 641  * De-select a text selection.
 642  *
 643  * Returns: #TRUE if successful, #FALSE otherwise.
 644  **/
 645 SPIBoolean
 646 AccessibleText_removeSelection (AccessibleText *obj,
 647                                 long int selectionNum)
 648 {
 649   SPIBoolean retval;
 650
 651   cspi_return_val_if_fail (obj != NULL, FALSE);
 652
 653   retval =
 654     Accessibility_Text_removeSelection (
 655       CSPI_OBJREF (obj), selectionNum, cspi_ev ());
 656
 657   cspi_return_val_if_ev ("removeSelection", FALSE);
 658
 659   return retval;
 660 }
 661
 662 /**
 663  * AccessibleText_setSelection:
 664  * @obj: a pointer to the #AccessibleText object on which to operate.
 665  * @selectionNum: a zero-offset index indicating which text selection to modify.
 666  * @startOffset: a long int, the new starting offset for the selection.
 667  * @endOffset: a long int, the desired new offset of the first character
 668  *             after the selection.
 669  *
 670  * Change the bounds of an existing #AccessibleText text selection.
 671  *
 672  * Returns: #TRUE if successful, #FALSE otherwise.
 673  **/
 674 SPIBoolean
 675 AccessibleText_setSelection (AccessibleText *obj,
 676                              long int selectionNum,
 677                              long int startOffset,
 678                              long int endOffset)
 679 {
 680   SPIBoolean retval;
 681
 682   cspi_return_val_if_fail (obj != NULL, FALSE);
 683
 684   retval = Accessibility_Text_setSelection (CSPI_OBJREF (obj),
 685                                    selectionNum,
 686                                    startOffset,
 687                                    endOffset, cspi_ev ());
 688
 689   cspi_return_val_if_ev ("setSelection", FALSE);
 690
 691   return retval;
 692 }
 693
 694
 695