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