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