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 <!-- ##### SECTION Stability_Level ##### -->
  35
  36
  37 <!-- ##### SECTION Image ##### -->
  38
  39
  40 <!-- ##### STRUCT AtkObject ##### -->
  41 <para>
  42 The AtkObject structure should not be accessed directly.
  43
  44 </para>
  45
  46
  47 <!-- ##### SIGNAL AtkObject::active-descendant-changed ##### -->
  48 <para>
  49 The "active-descendant-changed" signal is emitted by an object which has
  50 the state ATK_STATE_MANAGES_DESCENDANTS when the focus object in the
  51 object changes. For instance, a table will emit the signal when the cell
  52 in the table which has focus changes.
  53 </para>
  54
  55 @atkobject: the object which received the signal.
  56 @arg1: the newly focused object.
  57
  58 <!-- ##### SIGNAL AtkObject::children-changed ##### -->
  59 <para>
  60 The signal "children-changed" is emitted when a child is added or
  61 removed form an object. It supports two details: "add" and "remove"
  62 </para>
  63
  64 @atkobject: the object which received the signal.
  65 @arg1: The index of the added or removed child
  66 @arg2: A gpointer to the child AtkObject which was added or removed
  67
  68 <!-- ##### SIGNAL AtkObject::focus-event ##### -->
  69 <para>
  70 The signal "focus-event" is emitted when an object gains or loses focus.
  71 </para>
  72
  73 @atkobject: the object which received the signal.
  74 @arg1: A boolean value which indicates whether the object gained or lost focus.
  75
  76 <!-- ##### SIGNAL AtkObject::property-change ##### -->
  77 <para>
  78 The signal "property-change" is emitted when an object's property
  79 value changes. The detail identifies the name of the property whose
  80 value has changed.
  81 </para>
  82
  83 @atkobject: the object which received the signal.
  84 @arg1: The new value of the property which changed.
  85
  86 <!-- ##### SIGNAL AtkObject::state-change ##### -->
  87 <para>
  88 The "state-change" signal is emitted  when an object's state changes.
  89 The detail value identifies the state type which has changed.
  90 </para>
  91
  92 @atkobject: the object which received the signal.
  93 @arg1: The name of the state which has changed
  94 @arg2: A boolean which indicates whether the state has been set or unset.
  95
  96 <!-- ##### SIGNAL AtkObject::visible-data-changed ##### -->
  97 <para>
  98 The "visible-data-changed" signal is emitted when the visual appearance of
  99 the object changed.
 100 </para>
 101
 102 @atkobject: the object which received the signal.
 103
 104 <!-- ##### ARG AtkObject:accessible-component-layer ##### -->
 105 <para>
 106
 107 </para>
 108
 109 <!-- ##### ARG AtkObject:accessible-component-mdi-zorder ##### -->
 110 <para>
 111
 112 </para>
 113
 114 <!-- ##### ARG AtkObject:accessible-description ##### -->
 115 <para>
 116
 117 </para>
 118
 119 <!-- ##### ARG AtkObject:accessible-hypertext-nlinks ##### -->
 120 <para>
 121
 122 </para>
 123
 124 <!-- ##### ARG AtkObject:accessible-name ##### -->
 125 <para>
 126
 127 </para>
 128
 129 <!-- ##### ARG AtkObject:accessible-parent ##### -->
 130 <para>
 131
 132 </para>
 133
 134 <!-- ##### ARG AtkObject:accessible-role ##### -->
 135 <para>
 136
 137 </para>
 138
 139 <!-- ##### ARG AtkObject:accessible-table-caption ##### -->
 140 <para>
 141
 142 </para>
 143
 144 <!-- ##### ARG AtkObject:accessible-table-caption-object ##### -->
 145 <para>
 146
 147 </para>
 148
 149 <!-- ##### ARG AtkObject:accessible-table-column-description ##### -->
 150 <para>
 151
 152 </para>
 153
 154 <!-- ##### ARG AtkObject:accessible-table-column-header ##### -->
 155 <para>
 156
 157 </para>
 158
 159 <!-- ##### ARG AtkObject:accessible-table-row-description ##### -->
 160 <para>
 161
 162 </para>
 163
 164 <!-- ##### ARG AtkObject:accessible-table-row-header ##### -->
 165 <para>
 166
 167 </para>
 168
 169 <!-- ##### ARG AtkObject:accessible-table-summary ##### -->
 170 <para>
 171
 172 </para>
 173
 174 <!-- ##### ARG AtkObject:accessible-value ##### -->
 175 <para>
 176
 177 </para>
 178
 179 <!-- ##### ENUM AtkRole ##### -->
 180 <para>
 181 </para>
 182
 183 @ATK_ROLE_INVALID:
 184 @ATK_ROLE_ACCEL_LABEL:
 185 @ATK_ROLE_ALERT:
 186 @ATK_ROLE_ANIMATION:
 187 @ATK_ROLE_ARROW:
 188 @ATK_ROLE_CALENDAR:
 189 @ATK_ROLE_CANVAS:
 190 @ATK_ROLE_CHECK_BOX:
 191 @ATK_ROLE_CHECK_MENU_ITEM:
 192 @ATK_ROLE_COLOR_CHOOSER:
 193 @ATK_ROLE_COLUMN_HEADER:
 194 @ATK_ROLE_COMBO_BOX:
 195 @ATK_ROLE_DATE_EDITOR:
 196 @ATK_ROLE_DESKTOP_ICON:
 197 @ATK_ROLE_DESKTOP_FRAME:
 198 @ATK_ROLE_DIAL:
 199 @ATK_ROLE_DIALOG:
 200 @ATK_ROLE_DIRECTORY_PANE:
 201 @ATK_ROLE_DRAWING_AREA:
 202 @ATK_ROLE_FILE_CHOOSER:
 203 @ATK_ROLE_FILLER:
 204 @ATK_ROLE_FONT_CHOOSER:
 205 @ATK_ROLE_FRAME:
 206 @ATK_ROLE_GLASS_PANE:
 207 @ATK_ROLE_HTML_CONTAINER:
 208 @ATK_ROLE_ICON:
 209 @ATK_ROLE_IMAGE:
 210 @ATK_ROLE_INTERNAL_FRAME:
 211 @ATK_ROLE_LABEL:
 212 @ATK_ROLE_LAYERED_PANE:
 213 @ATK_ROLE_LIST:
 214 @ATK_ROLE_LIST_ITEM:
 215 @ATK_ROLE_MENU:
 216 @ATK_ROLE_MENU_BAR:
 217 @ATK_ROLE_MENU_ITEM:
 218 @ATK_ROLE_OPTION_PANE:
 219 @ATK_ROLE_PAGE_TAB:
 220 @ATK_ROLE_PAGE_TAB_LIST:
 221 @ATK_ROLE_PANEL:
 222 @ATK_ROLE_PASSWORD_TEXT:
 223 @ATK_ROLE_POPUP_MENU:
 224 @ATK_ROLE_PROGRESS_BAR:
 225 @ATK_ROLE_PUSH_BUTTON:
 226 @ATK_ROLE_RADIO_BUTTON:
 227 @ATK_ROLE_RADIO_MENU_ITEM:
 228 @ATK_ROLE_ROOT_PANE:
 229 @ATK_ROLE_ROW_HEADER:
 230 @ATK_ROLE_SCROLL_BAR:
 231 @ATK_ROLE_SCROLL_PANE:
 232 @ATK_ROLE_SEPARATOR:
 233 @ATK_ROLE_SLIDER:
 234 @ATK_ROLE_SPLIT_PANE:
 235 @ATK_ROLE_SPIN_BUTTON:
 236 @ATK_ROLE_STATUSBAR:
 237 @ATK_ROLE_TABLE:
 238 @ATK_ROLE_TABLE_CELL:
 239 @ATK_ROLE_TABLE_COLUMN_HEADER:
 240 @ATK_ROLE_TABLE_ROW_HEADER:
 241 @ATK_ROLE_TEAR_OFF_MENU_ITEM:
 242 @ATK_ROLE_TERMINAL:
 243 @ATK_ROLE_TEXT:
 244 @ATK_ROLE_TOGGLE_BUTTON:
 245 @ATK_ROLE_TOOL_BAR:
 246 @ATK_ROLE_TOOL_TIP:
 247 @ATK_ROLE_TREE:
 248 @ATK_ROLE_TREE_TABLE:
 249 @ATK_ROLE_UNKNOWN:
 250 @ATK_ROLE_VIEWPORT:
 251 @ATK_ROLE_WINDOW:
 252 @ATK_ROLE_HEADER:
 253 @ATK_ROLE_FOOTER:
 254 @ATK_ROLE_PARAGRAPH:
 255 @ATK_ROLE_RULER:
 256 @ATK_ROLE_APPLICATION:
 257 @ATK_ROLE_AUTOCOMPLETE:
 258 @ATK_ROLE_EDITBAR:
 259 @ATK_ROLE_EMBEDDED:
 260 @ATK_ROLE_ENTRY:
 261 @ATK_ROLE_CHART:
 262 @ATK_ROLE_CAPTION:
 263 @ATK_ROLE_DOCUMENT_FRAME:
 264 @ATK_ROLE_HEADING:
 265 @ATK_ROLE_PAGE:
 266 @ATK_ROLE_SECTION:
 267 @ATK_ROLE_REDUNDANT_OBJECT:
 268 @ATK_ROLE_FORM:
 269 @ATK_ROLE_LINK:
 270 @ATK_ROLE_INPUT_METHOD_WINDOW:
 271 @ATK_ROLE_LAST_DEFINED:
 272
 273 <!-- ##### FUNCTION atk_role_register ##### -->
 274 <para>
 275
 276 </para>
 277
 278 @name:
 279 @Returns:
 280
 281
 282 <!-- ##### ENUM AtkLayer ##### -->
 283 <para>
 284 </para>
 285
 286 @ATK_LAYER_INVALID:
 287 @ATK_LAYER_BACKGROUND:
 288 @ATK_LAYER_CANVAS:
 289 @ATK_LAYER_WIDGET:
 290 @ATK_LAYER_MDI:
 291 @ATK_LAYER_POPUP:
 292 @ATK_LAYER_OVERLAY:
 293 @ATK_LAYER_WINDOW:
 294
 295 <!-- ##### STRUCT AtkImplementor ##### -->
 296 <para>
 297 The AtkImplementor interface is implemented by objects for which AtkObject peers may be obtained via calls to iface->(ref_accessible)(implementor);
 298 </para>
 299
 300
 301 <!-- ##### STRUCT AtkPropertyValues ##### -->
 302 <para>
 303 The Atk PropertyValue structure is used when notifying a change in property.
 304 Currently, the only property for which old_value is used is
 305 accessible-state; for instance if there is a focus change the
 306 property change handler will be called for the object which lost the focus
 307 with the old_value containing the AtkState value corresponding to focused
 308 and the property change handler will be called for the object which
 309 received the focus with the new_value containing the AtkState value
 310 corresponding to focused.
 311
 312 </para>
 313
 314 @property_name:
 315 @old_value:
 316 @new_value:
 317
 318 <!-- ##### USER_FUNCTION AtkFunction ##### -->
 319 <para>
 320 An AtkFunction is a function definition used for padding which has been added
 321 to class and interface structures to allow for expansion in the future.
 322
 323 </para>
 324
 325 @data: a gpointer to parameter data.
 326 @Returns: Nothing useful, this is only a dummy prototype.
 327
 328
 329 <!-- ##### USER_FUNCTION AtkPropertyChangeHandler ##### -->
 330 <para>
 331 An AtkPropertyChangeHandler is a function which is executed when an AtkObject's property changes value. It is specified in a call to
 332 atk_object_connect_property_change_handler().
 333 </para>
 334
 335 @Param1:  an #AtkObject
 336 @Param2:  an #AtkPropertyValues
 337
 338
 339 <!-- ##### FUNCTION atk_implementor_ref_accessible ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @implementor:
 345 @Returns:
 346
 347
 348 <!-- ##### FUNCTION atk_object_get_name ##### -->
 349 <para>
 350
 351 </para>
 352
 353 @accessible:
 354 @Returns:
 355
 356
 357 <!-- ##### FUNCTION atk_object_get_description ##### -->
 358 <para>
 359
 360 </para>
 361
 362 @accessible:
 363 @Returns:
 364
 365
 366 <!-- ##### FUNCTION atk_object_get_parent ##### -->
 367 <para>
 368
 369 </para>
 370
 371 @accessible:
 372 @Returns:
 373
 374
 375 <!-- ##### FUNCTION atk_object_get_n_accessible_children ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @accessible:
 381 @Returns:
 382
 383
 384 <!-- ##### FUNCTION atk_object_ref_accessible_child ##### -->
 385 <para>
 386
 387 </para>
 388
 389 @accessible:
 390 @i:
 391 @Returns:
 392
 393
 394 <!-- ##### FUNCTION atk_object_ref_relation_set ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @accessible:
 400 @Returns:
 401
 402
 403 <!-- ##### FUNCTION atk_object_get_layer ##### -->
 404 <para>
 405
 406 </para>
 407
 408 @accessible:
 409 @Returns:
 410 @Deprecated: Use atk_component_get_layer instead.
 411
 412
 413 <!-- ##### FUNCTION atk_object_get_mdi_zorder ##### -->
 414 <para>
 415
 416 </para>
 417
 418 @accessible:
 419 @Returns:
 420 @Deprecated: Use atk_component_get_mdi_zorder instead.
 421
 422
 423 <!-- ##### FUNCTION atk_object_get_role ##### -->
 424 <para>
 425
 426 </para>
 427
 428 @accessible:
 429 @Returns:
 430
 431
 432 <!-- ##### FUNCTION atk_object_ref_state_set ##### -->
 433 <para>
 434
 435 </para>
 436
 437 @accessible:
 438 @Returns:
 439
 440
 441 <!-- ##### FUNCTION atk_object_get_index_in_parent ##### -->
 442 <para>
 443
 444 </para>
 445
 446 @accessible:
 447 @Returns:
 448
 449
 450 <!-- ##### FUNCTION atk_object_set_name ##### -->
 451 <para>
 452
 453 </para>
 454
 455 @accessible:
 456 @name:
 457
 458
 459 <!-- ##### FUNCTION atk_object_set_description ##### -->
 460 <para>
 461
 462 </para>
 463
 464 @accessible:
 465 @description:
 466
 467
 468 <!-- ##### FUNCTION atk_object_set_parent ##### -->
 469 <para>
 470
 471 </para>
 472
 473 @accessible:
 474 @parent:
 475
 476
 477 <!-- ##### FUNCTION atk_object_set_role ##### -->
 478 <para>
 479
 480 </para>
 481
 482 @accessible:
 483 @role:
 484
 485
 486 <!-- ##### FUNCTION atk_object_connect_property_change_handler ##### -->
 487 <para>
 488
 489 </para>
 490
 491 @accessible:
 492 @handler:
 493 @Returns:
 494
 495
 496 <!-- ##### FUNCTION atk_object_remove_property_change_handler ##### -->
 497 <para>
 498
 499 </para>
 500
 501 @accessible:
 502 @handler_id:
 503
 504
 505 <!-- ##### FUNCTION atk_object_notify_state_change ##### -->
 506 <para>
 507
 508 </para>
 509
 510 @accessible:
 511 @state:
 512 @value:
 513
 514
 515 <!-- ##### FUNCTION atk_object_initialize ##### -->
 516 <para>
 517
 518 </para>
 519
 520 @accessible:
 521 @data:
 522
 523
 524 <!-- ##### FUNCTION atk_object_add_relationship ##### -->
 525 <para>
 526
 527 </para>
 528
 529 @object:
 530 @relationship:
 531 @target:
 532 @Returns:
 533
 534
 535 <!-- ##### FUNCTION atk_object_remove_relationship ##### -->
 536 <para>
 537
 538 </para>
 539
 540 @object:
 541 @relationship:
 542 @target:
 543 @Returns:
 544
 545
 546 <!-- ##### FUNCTION atk_object_get_attributes ##### -->
 547 <para>
 548
 549 </para>
 550
 551 @accessible:
 552 @Returns:
 553
 554
 555 <!-- ##### FUNCTION atk_role_get_name ##### -->
 556 <para>
 557
 558 </para>
 559
 560 @role:
 561 @Returns:
 562
 563
 564 <!-- ##### FUNCTION atk_role_get_localized_name ##### -->
 565 <para>
 566
 567 </para>
 568
 569 @role:
 570 @Returns:
 571
 572
 573 <!-- ##### FUNCTION atk_role_for_name ##### -->
 574 <para>
 575
 576 </para>
 577
 578 @name:
 579 @Returns:
 580
 581