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