docs/tmpl/atkobject.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 AtkObject
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6 The base object class for the Accessibility Toolkit API.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 This class is the primary class for accessibility support via
  11 the Accessibility ToolKit (ATK).  Objects which are instances
  12 of #AtkObject (or instances of AtkObject-derived types) are
  13 queried for properties which relate basic (and generic) properties of a
  14 UI component such as name and description.  Instances of #AtkObject
  15 may also be queried as to whether they implement other ATK interfaces
  16 (e.g. #AtkAction, #AtkComponent, etc.), as appropriate to the role
  17 which a given UI component plays in a user interface.
  18 </para>
  19 <para>All UI components in an application which provide useful
  20 information or services to the user must provide corresponding
  21 #AtkObject instances on request (in GTK+, for instance, usually
  22 on a call to #gtk_widget_get_accessible ()), either via ATK support
  23 built into the toolkit for the widget class or ancestor class, or in
  24 the case of custom widgets, if the inherited #AtkObject implementation
  25 is insufficient, via instances of a new #AtkObject subclass.
  26 </para>
  27
  28 <!-- ##### SECTION See_Also ##### -->
  29 <para>
  30 See also: #AtkObjectFactory, #AtkRegistry.
  31 ( GTK+ users see also #GtkAccessible).
  32 </para>
  33
  34 <!-- ##### STRUCT AtkObject ##### -->
  35 <para>
  36 The AtkObject structure should not be accessed directly.
  37
  38 </para>
  39
  40
  41 <!-- ##### ENUM AtkRole ##### -->
  42 <para>
  43 </para>
  44
  45 @ATK_ROLE_INVALID:
  46 @ATK_ROLE_ACCEL_LABEL:
  47 @ATK_ROLE_ALERT:
  48 @ATK_ROLE_ANIMATION:
  49 @ATK_ROLE_ARROW:
  50 @ATK_ROLE_CALENDAR:
  51 @ATK_ROLE_CANVAS:
  52 @ATK_ROLE_CHECK_BOX:
  53 @ATK_ROLE_CHECK_MENU_ITEM:
  54 @ATK_ROLE_COLOR_CHOOSER:
  55 @ATK_ROLE_COLUMN_HEADER:
  56 @ATK_ROLE_COMBO_BOX:
  57 @ATK_ROLE_DATE_EDITOR:
  58 @ATK_ROLE_DESKTOP_ICON:
  59 @ATK_ROLE_DESKTOP_FRAME:
  60 @ATK_ROLE_DIAL:
  61 @ATK_ROLE_DIALOG:
  62 @ATK_ROLE_DIRECTORY_PANE:
  63 @ATK_ROLE_DRAWING_AREA:
  64 @ATK_ROLE_FILE_CHOOSER:
  65 @ATK_ROLE_FILLER:
  66 @ATK_ROLE_FONT_CHOOSER:
  67 @ATK_ROLE_FRAME:
  68 @ATK_ROLE_GLASS_PANE:
  69 @ATK_ROLE_HTML_CONTAINER:
  70 @ATK_ROLE_ICON:
  71 @ATK_ROLE_IMAGE:
  72 @ATK_ROLE_INTERNAL_FRAME:
  73 @ATK_ROLE_LABEL:
  74 @ATK_ROLE_LAYERED_PANE:
  75 @ATK_ROLE_LIST:
  76 @ATK_ROLE_LIST_ITEM:
  77 @ATK_ROLE_MENU:
  78 @ATK_ROLE_MENU_BAR:
  79 @ATK_ROLE_MENU_ITEM:
  80 @ATK_ROLE_OPTION_PANE:
  81 @ATK_ROLE_PAGE_TAB:
  82 @ATK_ROLE_PAGE_TAB_LIST:
  83 @ATK_ROLE_PANEL:
  84 @ATK_ROLE_PASSWORD_TEXT:
  85 @ATK_ROLE_POPUP_MENU:
  86 @ATK_ROLE_PROGRESS_BAR:
  87 @ATK_ROLE_PUSH_BUTTON:
  88 @ATK_ROLE_RADIO_BUTTON:
  89 @ATK_ROLE_RADIO_MENU_ITEM:
  90 @ATK_ROLE_ROOT_PANE:
  91 @ATK_ROLE_ROW_HEADER:
  92 @ATK_ROLE_SCROLL_BAR:
  93 @ATK_ROLE_SCROLL_PANE:
  94 @ATK_ROLE_SEPARATOR:
  95 @ATK_ROLE_SLIDER:
  96 @ATK_ROLE_SPLIT_PANE:
  97 @ATK_ROLE_SPIN_BUTTON:
  98 @ATK_ROLE_STATUSBAR:
  99 @ATK_ROLE_TABLE:
 100 @ATK_ROLE_TABLE_CELL:
 101 @ATK_ROLE_TABLE_COLUMN_HEADER:
 102 @ATK_ROLE_TABLE_ROW_HEADER:
 103 @ATK_ROLE_TEAR_OFF_MENU_ITEM:
 104 @ATK_ROLE_TERMINAL:
 105 @ATK_ROLE_TEXT:
 106 @ATK_ROLE_TOGGLE_BUTTON:
 107 @ATK_ROLE_TOOL_BAR:
 108 @ATK_ROLE_TOOL_TIP:
 109 @ATK_ROLE_TREE:
 110 @ATK_ROLE_TREE_TABLE:
 111 @ATK_ROLE_UNKNOWN:
 112 @ATK_ROLE_VIEWPORT:
 113 @ATK_ROLE_WINDOW:
 114 @ATK_ROLE_HEADER:
 115 @ATK_ROLE_FOOTER:
 116 @ATK_ROLE_PARAGRAPH:
 117 @ATK_ROLE_RULER:
 118 @ATK_ROLE_APPLICATION:
 119 @ATK_ROLE_AUTOCOMPLETE:
 120 @ATK_ROLE_LAST_DEFINED:
 121
 122 <!-- ##### FUNCTION atk_role_register ##### -->
 123 <para>
 124
 125 </para>
 126
 127 @name:
 128 @Returns:
 129
 130
 131 <!-- ##### ENUM AtkLayer ##### -->
 132 <para>
 133 </para>
 134
 135 @ATK_LAYER_INVALID:
 136 @ATK_LAYER_BACKGROUND:
 137 @ATK_LAYER_CANVAS:
 138 @ATK_LAYER_WIDGET:
 139 @ATK_LAYER_MDI:
 140 @ATK_LAYER_POPUP:
 141 @ATK_LAYER_OVERLAY:
 142 @ATK_LAYER_WINDOW:
 143
 144 <!-- ##### STRUCT AtkImplementor ##### -->
 145 <para>
 146 The AtkImplementor structure does not contain any fields.
 147
 148 </para>
 149
 150
 151 <!-- ##### STRUCT AtkPropertyValues ##### -->
 152 <para>
 153 The Atk PropertyValue structure is used when notifying a change in property.
 154 Currently, the only property for which old_value is used is
 155 accessible-state; for instance if there is a focus change the
 156 property change handler will be called for the object which lost the focus
 157 with the old_value containing the AtkState value corresponding to focused
 158 and the property change handler will be called for the object which
 159 received the focus with the new_value containing the AtkState value
 160 corresponding to focused.
 161
 162 </para>
 163
 164 @property_name:
 165 @old_value:
 166 @new_value:
 167
 168 <!-- ##### USER_FUNCTION AtkFunction ##### -->
 169 <para>
 170 An AtkFunction is a function definition used for padding which has been added
 171 to class and interface structures to allow for expansion in the future.
 172
 173 </para>
 174
 175 @data:
 176 @Returns:
 177
 178
 179 <!-- ##### USER_FUNCTION AtkPropertyChangeHandler ##### -->
 180 <para>
 181 An AtkPropertyChangeHandler is a function which is executed when an AtkObject's property changes value. It is specified in a call to
 182 atk_object_connect_property_change_handler().
 183 </para>
 184
 185 @Param1:
 186 @Param2:
 187
 188
 189 <!-- ##### FUNCTION atk_implementor_ref_accessible ##### -->
 190 <para>
 191
 192 </para>
 193
 194 @implementor:
 195 @Returns:
 196
 197
 198 <!-- ##### FUNCTION atk_object_get_name ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @accessible:
 204 @Returns:
 205
 206
 207 <!-- ##### FUNCTION atk_object_get_description ##### -->
 208 <para>
 209
 210 </para>
 211
 212 @accessible:
 213 @Returns:
 214
 215
 216 <!-- ##### FUNCTION atk_object_get_parent ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @accessible:
 222 @Returns:
 223
 224
 225 <!-- ##### FUNCTION atk_object_get_n_accessible_children ##### -->
 226 <para>
 227
 228 </para>
 229
 230 @accessible:
 231 @Returns:
 232
 233
 234 <!-- ##### FUNCTION atk_object_ref_accessible_child ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @accessible:
 240 @i:
 241 @Returns:
 242
 243
 244 <!-- ##### FUNCTION atk_object_ref_relation_set ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @accessible:
 250 @Returns:
 251
 252
 253 <!-- ##### FUNCTION atk_object_get_layer ##### -->
 254 <para>
 255
 256 </para>
 257
 258 @accessible:
 259 @Returns:
 260
 261
 262 <!-- ##### FUNCTION atk_object_get_mdi_zorder ##### -->
 263 <para>
 264
 265 </para>
 266
 267 @accessible:
 268 @Returns:
 269
 270
 271 <!-- ##### FUNCTION atk_object_get_role ##### -->
 272 <para>
 273
 274 </para>
 275
 276 @accessible:
 277 @Returns:
 278
 279
 280 <!-- ##### FUNCTION atk_object_ref_state_set ##### -->
 281 <para>
 282
 283 </para>
 284
 285 @accessible:
 286 @Returns:
 287
 288
 289 <!-- ##### FUNCTION atk_object_get_index_in_parent ##### -->
 290 <para>
 291
 292 </para>
 293
 294 @accessible:
 295 @Returns:
 296
 297
 298 <!-- ##### FUNCTION atk_object_set_name ##### -->
 299 <para>
 300
 301 </para>
 302
 303 @accessible:
 304 @name:
 305
 306
 307 <!-- ##### FUNCTION atk_object_set_description ##### -->
 308 <para>
 309
 310 </para>
 311
 312 @accessible:
 313 @description:
 314
 315
 316 <!-- ##### FUNCTION atk_object_set_parent ##### -->
 317 <para>
 318
 319 </para>
 320
 321 @accessible:
 322 @parent:
 323
 324
 325 <!-- ##### FUNCTION atk_object_set_role ##### -->
 326 <para>
 327
 328 </para>
 329
 330 @accessible:
 331 @role:
 332
 333
 334 <!-- ##### FUNCTION atk_object_connect_property_change_handler ##### -->
 335 <para>
 336
 337 </para>
 338
 339 @accessible:
 340 @handler:
 341 @Returns:
 342
 343
 344 <!-- ##### FUNCTION atk_object_remove_property_change_handler ##### -->
 345 <para>
 346
 347 </para>
 348
 349 @accessible:
 350 @handler_id:
 351
 352
 353 <!-- ##### FUNCTION atk_object_notify_state_change ##### -->
 354 <para>
 355
 356 </para>
 357
 358 @accessible:
 359 @state:
 360 @value:
 361
 362
 363 <!-- ##### FUNCTION atk_object_initialize ##### -->
 364 <para>
 365
 366 </para>
 367
 368 @accessible:
 369 @data:
 370
 371
 372 <!-- ##### FUNCTION atk_object_add_relationship ##### -->
 373 <para>
 374
 375 </para>
 376
 377 @object:
 378 @relationship:
 379 @target:
 380 @Returns:
 381
 382
 383 <!-- ##### FUNCTION atk_object_remove_relationship ##### -->
 384 <para>
 385
 386 </para>
 387
 388 @object:
 389 @relationship:
 390 @target:
 391 @Returns:
 392
 393
 394 <!-- ##### FUNCTION atk_role_get_name ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @role:
 400 @Returns:
 401
 402
 403 <!-- ##### FUNCTION atk_role_get_localized_name ##### -->
 404 <para>
 405
 406 </para>
 407
 408 @role:
 409 @Returns:
 410
 411
 412 <!-- ##### FUNCTION atk_role_for_name ##### -->
 413 <para>
 414
 415 </para>
 416
 417 @name:
 418 @Returns:
 419
 420
 421 <!-- ##### SIGNAL AtkObject::active-descendant-changed ##### -->
 422 <para>
 423
 424 </para>
 425
 426 @atkobject: the object which received the signal.
 427 @arg1:
 428
 429 <!-- ##### SIGNAL AtkObject::children-changed ##### -->
 430 <para>
 431 The children_changed signal supports two details, "add" and "remove" which
 432 indicate whether a child was added or removed
 433 </para>
 434
 435 @atkobject: the object which received the signal.
 436 @arg1: The index of the added or removed child
 437 @arg2: The child which was added or removed
 438
 439 <!-- ##### SIGNAL AtkObject::focus-event ##### -->
 440 <para>
 441
 442 </para>
 443
 444 @atkobject: the object which received the signal.
 445 @arg1: A boolean value which indicates whether or not the focus event is is or out.
 446
 447 <!-- ##### SIGNAL AtkObject::property-change ##### -->
 448 <para>
 449 This signal support a detail which identifies the property which has
 450 changed.
 451 </para>
 452
 453 @atkobject: the object which received the signal.
 454 @arg1: The new value of the property which changed.
 455
 456 <!-- ##### SIGNAL AtkObject::state-change ##### -->
 457 <para>
 458 This signal support, which may be any of the accessible state types.
 459 </para>
 460
 461 @atkobject: the object which received the signal.
 462 @arg1: The name of the state which has changed
 463 @arg2: A boolean which indicates whether the state has been set or unset.
 464
 465 <!-- ##### SIGNAL AtkObject::visible-data-changed ##### -->
 466 <para>
 467
 468 </para>
 469
 470 @atkobject: the object which received the signal.
 471
 472 <!-- ##### ARG AtkObject:accessible-component-layer ##### -->
 473 <para>
 474
 475 </para>
 476
 477 <!-- ##### ARG AtkObject:accessible-component-mdi-zorder ##### -->
 478 <para>
 479
 480 </para>
 481
 482 <!-- ##### ARG AtkObject:accessible-description ##### -->
 483 <para>
 484
 485 </para>
 486
 487 <!-- ##### ARG AtkObject:accessible-name ##### -->
 488 <para>
 489
 490 </para>
 491
 492 <!-- ##### ARG AtkObject:accessible-parent ##### -->
 493 <para>
 494
 495 </para>
 496
 497 <!-- ##### ARG AtkObject:accessible-role ##### -->
 498 <para>
 499
 500 </para>
 501
 502 <!-- ##### ARG AtkObject:accessible-table-caption ##### -->
 503 <para>
 504
 505 </para>
 506
 507 <!-- ##### ARG AtkObject:accessible-table-caption-object ##### -->
 508 <para>
 509
 510 </para>
 511
 512 <!-- ##### ARG AtkObject:accessible-table-column-description ##### -->
 513 <para>
 514
 515 </para>
 516
 517 <!-- ##### ARG AtkObject:accessible-table-column-header ##### -->
 518 <para>
 519
 520 </para>
 521
 522 <!-- ##### ARG AtkObject:accessible-table-row-description ##### -->
 523 <para>
 524
 525 </para>
 526
 527 <!-- ##### ARG AtkObject:accessible-table-row-header ##### -->
 528 <para>
 529
 530 </para>
 531
 532 <!-- ##### ARG AtkObject:accessible-table-summary ##### -->
 533 <para>
 534
 535 </para>
 536
 537 <!-- ##### ARG AtkObject:accessible-value ##### -->
 538 <para>
 539
 540 </para>
 541