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_EDITBAR:
 121 @ATK_ROLE_EMBEDDED:
 122 @ATK_ROLE_LAST_DEFINED:
 123
 124 <!-- ##### FUNCTION atk_role_register ##### -->
 125 <para>
 126
 127 </para>
 128
 129 @name:
 130 @Returns:
 131
 132
 133 <!-- ##### ENUM AtkLayer ##### -->
 134 <para>
 135 </para>
 136
 137 @ATK_LAYER_INVALID:
 138 @ATK_LAYER_BACKGROUND:
 139 @ATK_LAYER_CANVAS:
 140 @ATK_LAYER_WIDGET:
 141 @ATK_LAYER_MDI:
 142 @ATK_LAYER_POPUP:
 143 @ATK_LAYER_OVERLAY:
 144 @ATK_LAYER_WINDOW:
 145
 146 <!-- ##### STRUCT AtkImplementor ##### -->
 147 <para>
 148 The AtkImplementor structure does not contain any fields.
 149
 150 </para>
 151
 152
 153 <!-- ##### STRUCT AtkPropertyValues ##### -->
 154 <para>
 155 The Atk PropertyValue structure is used when notifying a change in property.
 156 Currently, the only property for which old_value is used is
 157 accessible-state; for instance if there is a focus change the
 158 property change handler will be called for the object which lost the focus
 159 with the old_value containing the AtkState value corresponding to focused
 160 and the property change handler will be called for the object which
 161 received the focus with the new_value containing the AtkState value
 162 corresponding to focused.
 163
 164 </para>
 165
 166 @property_name:
 167 @old_value:
 168 @new_value:
 169
 170 <!-- ##### USER_FUNCTION AtkFunction ##### -->
 171 <para>
 172 An AtkFunction is a function definition used for padding which has been added
 173 to class and interface structures to allow for expansion in the future.
 174
 175 </para>
 176
 177 @data:
 178 @Returns:
 179
 180
 181 <!-- ##### USER_FUNCTION AtkPropertyChangeHandler ##### -->
 182 <para>
 183 An AtkPropertyChangeHandler is a function which is executed when an AtkObject's property changes value. It is specified in a call to
 184 atk_object_connect_property_change_handler().
 185 </para>
 186
 187 @Param1:
 188 @Param2:
 189
 190
 191 <!-- ##### FUNCTION atk_implementor_ref_accessible ##### -->
 192 <para>
 193
 194 </para>
 195
 196 @implementor:
 197 @Returns:
 198
 199
 200 <!-- ##### FUNCTION atk_object_get_name ##### -->
 201 <para>
 202
 203 </para>
 204
 205 @accessible:
 206 @Returns:
 207
 208
 209 <!-- ##### FUNCTION atk_object_get_description ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @accessible:
 215 @Returns:
 216
 217
 218 <!-- ##### FUNCTION atk_object_get_parent ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @accessible:
 224 @Returns:
 225
 226
 227 <!-- ##### FUNCTION atk_object_get_n_accessible_children ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @accessible:
 233 @Returns:
 234
 235
 236 <!-- ##### FUNCTION atk_object_ref_accessible_child ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @accessible:
 242 @i:
 243 @Returns:
 244
 245
 246 <!-- ##### FUNCTION atk_object_ref_relation_set ##### -->
 247 <para>
 248
 249 </para>
 250
 251 @accessible:
 252 @Returns:
 253
 254
 255 <!-- ##### FUNCTION atk_object_get_layer ##### -->
 256 <para>
 257
 258 </para>
 259
 260 @accessible:
 261 @Returns:
 262
 263
 264 <!-- ##### FUNCTION atk_object_get_mdi_zorder ##### -->
 265 <para>
 266
 267 </para>
 268
 269 @accessible:
 270 @Returns:
 271
 272
 273 <!-- ##### FUNCTION atk_object_get_role ##### -->
 274 <para>
 275
 276 </para>
 277
 278 @accessible:
 279 @Returns:
 280
 281
 282 <!-- ##### FUNCTION atk_object_ref_state_set ##### -->
 283 <para>
 284
 285 </para>
 286
 287 @accessible:
 288 @Returns:
 289
 290
 291 <!-- ##### FUNCTION atk_object_get_index_in_parent ##### -->
 292 <para>
 293
 294 </para>
 295
 296 @accessible:
 297 @Returns:
 298
 299
 300 <!-- ##### FUNCTION atk_object_set_name ##### -->
 301 <para>
 302
 303 </para>
 304
 305 @accessible:
 306 @name:
 307
 308
 309 <!-- ##### FUNCTION atk_object_set_description ##### -->
 310 <para>
 311
 312 </para>
 313
 314 @accessible:
 315 @description:
 316
 317
 318 <!-- ##### FUNCTION atk_object_set_parent ##### -->
 319 <para>
 320
 321 </para>
 322
 323 @accessible:
 324 @parent:
 325
 326
 327 <!-- ##### FUNCTION atk_object_set_role ##### -->
 328 <para>
 329
 330 </para>
 331
 332 @accessible:
 333 @role:
 334
 335
 336 <!-- ##### FUNCTION atk_object_connect_property_change_handler ##### -->
 337 <para>
 338
 339 </para>
 340
 341 @accessible:
 342 @handler:
 343 @Returns:
 344
 345
 346 <!-- ##### FUNCTION atk_object_remove_property_change_handler ##### -->
 347 <para>
 348
 349 </para>
 350
 351 @accessible:
 352 @handler_id:
 353
 354
 355 <!-- ##### FUNCTION atk_object_notify_state_change ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @accessible:
 361 @state:
 362 @value:
 363
 364
 365 <!-- ##### FUNCTION atk_object_initialize ##### -->
 366 <para>
 367
 368 </para>
 369
 370 @accessible:
 371 @data:
 372
 373
 374 <!-- ##### FUNCTION atk_object_add_relationship ##### -->
 375 <para>
 376
 377 </para>
 378
 379 @object:
 380 @relationship:
 381 @target:
 382 @Returns:
 383
 384
 385 <!-- ##### FUNCTION atk_object_remove_relationship ##### -->
 386 <para>
 387
 388 </para>
 389
 390 @object:
 391 @relationship:
 392 @target:
 393 @Returns:
 394
 395
 396 <!-- ##### FUNCTION atk_role_get_name ##### -->
 397 <para>
 398
 399 </para>
 400
 401 @role:
 402 @Returns:
 403
 404
 405 <!-- ##### FUNCTION atk_role_get_localized_name ##### -->
 406 <para>
 407
 408 </para>
 409
 410 @role:
 411 @Returns:
 412
 413
 414 <!-- ##### FUNCTION atk_role_for_name ##### -->
 415 <para>
 416
 417 </para>
 418
 419 @name:
 420 @Returns:
 421
 422
 423 <!-- ##### SIGNAL AtkObject::active-descendant-changed ##### -->
 424 <para>
 425 The "active-descendant-changed" signal is emitted by an object which has
 426 the state ATK_STATE_MANAGES_DESCENDANTS when the focus object in the
 427 object changes. For instance, a table will emit the signal when the cell
 428 in the table which has focus changes.
 429 </para>
 430
 431 @atkobject: the object which received the signal.
 432 @arg1: the newly focused object.
 433
 434 <!-- ##### SIGNAL AtkObject::children-changed ##### -->
 435 <para>
 436 The signal "children-changed" is emitted when a child is added or
 437 removed form an object. It supports two details: "add" and "remove"
 438 </para>
 439
 440 @atkobject: the object which received the signal.
 441 @arg1: The index of the added or removed child
 442 @arg2: The child which was added or removed
 443
 444 <!-- ##### SIGNAL AtkObject::focus-event ##### -->
 445 <para>
 446 The signal "focus-event" is emitted when an object gains or loses focus.
 447 </para>
 448
 449 @atkobject: the object which received the signal.
 450 @arg1: A boolean value which indicates whether the object gained or lost focus.
 451
 452 <!-- ##### SIGNAL AtkObject::property-change ##### -->
 453 <para>
 454 The signal "property-change" is emitted when an object's property
 455 value changes. The detail identifies the name of the property whose
 456 value has changed.
 457 </para>
 458
 459 @atkobject: the object which received the signal.
 460 @arg1: The new value of the property which changed.
 461
 462 <!-- ##### SIGNAL AtkObject::state-change ##### -->
 463 <para>
 464 The "state-change" signal is emitted  when an object's state changes.
 465 The detail value identifies the state type which has changed.
 466 </para>
 467
 468 @atkobject: the object which received the signal.
 469 @arg1: The name of the state which has changed
 470 @arg2: A boolean which indicates whether the state has been set or unset.
 471
 472 <!-- ##### SIGNAL AtkObject::visible-data-changed ##### -->
 473 <para>
 474 The "visible-data-changed" signal is emitted when the visual appearance of
 475 the object changed.
 476 </para>
 477
 478 @atkobject: the object which received the signal.
 479
 480 <!-- ##### ARG AtkObject:accessible-component-layer ##### -->
 481 <para>
 482
 483 </para>
 484
 485 <!-- ##### ARG AtkObject:accessible-component-mdi-zorder ##### -->
 486 <para>
 487
 488 </para>
 489
 490 <!-- ##### ARG AtkObject:accessible-description ##### -->
 491 <para>
 492
 493 </para>
 494
 495 <!-- ##### ARG AtkObject:accessible-hypertext-nlinks ##### -->
 496 <para>
 497
 498 </para>
 499
 500 <!-- ##### ARG AtkObject:accessible-name ##### -->
 501 <para>
 502
 503 </para>
 504
 505 <!-- ##### ARG AtkObject:accessible-parent ##### -->
 506 <para>
 507
 508 </para>
 509
 510 <!-- ##### ARG AtkObject:accessible-role ##### -->
 511 <para>
 512
 513 </para>
 514
 515 <!-- ##### ARG AtkObject:accessible-table-caption ##### -->
 516 <para>
 517
 518 </para>
 519
 520 <!-- ##### ARG AtkObject:accessible-table-caption-object ##### -->
 521 <para>
 522
 523 </para>
 524
 525 <!-- ##### ARG AtkObject:accessible-table-column-description ##### -->
 526 <para>
 527
 528 </para>
 529
 530 <!-- ##### ARG AtkObject:accessible-table-column-header ##### -->
 531 <para>
 532
 533 </para>
 534
 535 <!-- ##### ARG AtkObject:accessible-table-row-description ##### -->
 536 <para>
 537
 538 </para>
 539
 540 <!-- ##### ARG AtkObject:accessible-table-row-header ##### -->
 541 <para>
 542
 543 </para>
 544
 545 <!-- ##### ARG AtkObject:accessible-table-summary ##### -->
 546 <para>
 547
 548 </para>
 549
 550 <!-- ##### ARG AtkObject:accessible-value ##### -->
 551 <para>
 552
 553 </para>
 554