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