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