Release atk 1.32.0

[atk.git] / docs / tmpl / atkobject.sgml

<!-- ##### SECTION Title ##### -->
AtkObject

<!-- ##### SECTION Short_Description ##### -->

The base object class for the Accessibility Toolkit API.

<!-- ##### SECTION Long_Description ##### -->
<para>
This class is the primary class for accessibility support via
the Accessibility ToolKit (ATK).  Objects which are instances
of #AtkObject (or instances of AtkObject-derived types) are
queried for properties which relate basic (and generic) properties of a
UI component such as name and description.  Instances of #AtkObject
may also be queried as to whether they implement other ATK interfaces
(e.g. #AtkAction, #AtkComponent, etc.), as appropriate to the role
which a given UI component plays in a user interface.
</para>
<para>All UI components in an application which provide useful
information or services to the user must provide corresponding
#AtkObject instances on request (in GTK+, for instance, usually
on a call to #gtk_widget_get_accessible ()), either via ATK support
built into the toolkit for the widget class or ancestor class, or in
the case of custom widgets, if the inherited #AtkObject implementation
is insufficient, via instances of a new #AtkObject subclass. 
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
See also: #AtkObjectFactory, #AtkRegistry.
( GTK+ users see also #GtkAccessible).
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### STRUCT AtkObject ##### -->
<para>
The AtkObject structure should not be accessed directly.

</para>


<!-- ##### SIGNAL AtkObject::active-descendant-changed ##### -->
<para>
The "active-descendant-changed" signal is emitted by an object which has
the state ATK_STATE_MANAGES_DESCENDANTS when the focus object in the
object changes. For instance, a table will emit the signal when the cell
in the table which has focus changes.
</para>

@atkobject: the object which received the signal.
@arg1: the newly focused object.

<!-- ##### SIGNAL AtkObject::children-changed ##### -->
<para>
The signal "children-changed" is emitted when a child is added or
removed form an object. It supports two details: "add" and "remove"
</para>

@atkobject: the object which received the signal.
@arg1: The index of the added or removed child
@arg2: A gpointer to the child AtkObject which was added or removed

<!-- ##### SIGNAL AtkObject::focus-event ##### -->
<para>
The signal "focus-event" is emitted when an object gains or loses focus.
</para>

@atkobject: the object which received the signal.
@arg1: A boolean value which indicates whether the object gained or lost focus.

<!-- ##### SIGNAL AtkObject::property-change ##### -->
<para>
The signal "property-change" is emitted when an object's property
value changes. The detail identifies the name of the property whose
value has changed.
</para>

@atkobject: the object which received the signal.
@arg1: The new value of the property which changed.

<!-- ##### SIGNAL AtkObject::state-change ##### -->
<para>
The "state-change" signal is emitted  when an object's state changes.
The detail value identifies the state type which has changed.
</para>

@atkobject: the object which received the signal.
@arg1: The name of the state which has changed
@arg2: A boolean which indicates whether the state has been set or unset.

<!-- ##### SIGNAL AtkObject::visible-data-changed ##### -->
<para>
The "visible-data-changed" signal is emitted when the visual appearance of 
the object changed.
</para>

@atkobject: the object which received the signal.

<!-- ##### ARG AtkObject:accessible-component-layer ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-component-mdi-zorder ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-description ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-hypertext-nlinks ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-name ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-parent ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-role ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-table-caption ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-table-caption-object ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-table-column-description ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-table-column-header ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-table-row-description ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-table-row-header ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-table-summary ##### -->
<para>

</para>

<!-- ##### ARG AtkObject:accessible-value ##### -->
<para>

</para>

<!-- ##### ENUM AtkRole ##### -->
<para>
</para>

@ATK_ROLE_INVALID: 
@ATK_ROLE_ACCEL_LABEL: 
@ATK_ROLE_ALERT: 
@ATK_ROLE_ANIMATION: 
@ATK_ROLE_ARROW: 
@ATK_ROLE_CALENDAR: 
@ATK_ROLE_CANVAS: 
@ATK_ROLE_CHECK_BOX: 
@ATK_ROLE_CHECK_MENU_ITEM: 
@ATK_ROLE_COLOR_CHOOSER: 
@ATK_ROLE_COLUMN_HEADER: 
@ATK_ROLE_COMBO_BOX: 
@ATK_ROLE_DATE_EDITOR: 
@ATK_ROLE_DESKTOP_ICON: 
@ATK_ROLE_DESKTOP_FRAME: 
@ATK_ROLE_DIAL: 
@ATK_ROLE_DIALOG: 
@ATK_ROLE_DIRECTORY_PANE: 
@ATK_ROLE_DRAWING_AREA: 
@ATK_ROLE_FILE_CHOOSER: 
@ATK_ROLE_FILLER: 
@ATK_ROLE_FONT_CHOOSER: 
@ATK_ROLE_FRAME: 
@ATK_ROLE_GLASS_PANE: 
@ATK_ROLE_HTML_CONTAINER: 
@ATK_ROLE_ICON: 
@ATK_ROLE_IMAGE: 
@ATK_ROLE_INTERNAL_FRAME: 
@ATK_ROLE_LABEL: 
@ATK_ROLE_LAYERED_PANE: 
@ATK_ROLE_LIST: 
@ATK_ROLE_LIST_ITEM: 
@ATK_ROLE_MENU: 
@ATK_ROLE_MENU_BAR: 
@ATK_ROLE_MENU_ITEM: 
@ATK_ROLE_OPTION_PANE: 
@ATK_ROLE_PAGE_TAB: 
@ATK_ROLE_PAGE_TAB_LIST: 
@ATK_ROLE_PANEL: 
@ATK_ROLE_PASSWORD_TEXT: 
@ATK_ROLE_POPUP_MENU: 
@ATK_ROLE_PROGRESS_BAR: 
@ATK_ROLE_PUSH_BUTTON: 
@ATK_ROLE_RADIO_BUTTON: 
@ATK_ROLE_RADIO_MENU_ITEM: 
@ATK_ROLE_ROOT_PANE: 
@ATK_ROLE_ROW_HEADER: 
@ATK_ROLE_SCROLL_BAR: 
@ATK_ROLE_SCROLL_PANE: 
@ATK_ROLE_SEPARATOR: 
@ATK_ROLE_SLIDER: 
@ATK_ROLE_SPLIT_PANE: 
@ATK_ROLE_SPIN_BUTTON: 
@ATK_ROLE_STATUSBAR: 
@ATK_ROLE_TABLE: 
@ATK_ROLE_TABLE_CELL: 
@ATK_ROLE_TABLE_COLUMN_HEADER: 
@ATK_ROLE_TABLE_ROW_HEADER: 
@ATK_ROLE_TEAR_OFF_MENU_ITEM: 
@ATK_ROLE_TERMINAL: 
@ATK_ROLE_TEXT: 
@ATK_ROLE_TOGGLE_BUTTON: 
@ATK_ROLE_TOOL_BAR: 
@ATK_ROLE_TOOL_TIP: 
@ATK_ROLE_TREE: 
@ATK_ROLE_TREE_TABLE: 
@ATK_ROLE_UNKNOWN: 
@ATK_ROLE_VIEWPORT: 
@ATK_ROLE_WINDOW: 
@ATK_ROLE_HEADER: 
@ATK_ROLE_FOOTER: 
@ATK_ROLE_PARAGRAPH: 
@ATK_ROLE_RULER: 
@ATK_ROLE_APPLICATION: 
@ATK_ROLE_AUTOCOMPLETE: 
@ATK_ROLE_EDITBAR: 
@ATK_ROLE_EMBEDDED: 
@ATK_ROLE_ENTRY: 
@ATK_ROLE_CHART: 
@ATK_ROLE_CAPTION: 
@ATK_ROLE_DOCUMENT_FRAME: 
@ATK_ROLE_HEADING: 
@ATK_ROLE_PAGE: 
@ATK_ROLE_SECTION: 
@ATK_ROLE_REDUNDANT_OBJECT: 
@ATK_ROLE_FORM: 
@ATK_ROLE_LINK: 
@ATK_ROLE_INPUT_METHOD_WINDOW: 
@ATK_ROLE_LAST_DEFINED: 

<!-- ##### FUNCTION atk_role_register ##### -->
<para>

</para>

@name: 
@Returns: 


<!-- ##### ENUM AtkLayer ##### -->
<para>
</para>

@ATK_LAYER_INVALID: 
@ATK_LAYER_BACKGROUND: 
@ATK_LAYER_CANVAS: 
@ATK_LAYER_WIDGET: 
@ATK_LAYER_MDI: 
@ATK_LAYER_POPUP: 
@ATK_LAYER_OVERLAY: 
@ATK_LAYER_WINDOW: 

<!-- ##### STRUCT AtkImplementor ##### -->
<para>
The AtkImplementor interface is implemented by objects for which AtkObject peers may be obtained via calls to iface->(ref_accessible)(implementor);
</para>


<!-- ##### STRUCT AtkPropertyValues ##### -->
<para>
The Atk PropertyValue structure is used when notifying a change in property.
Currently, the only property for which old_value is used is
accessible-state; for instance if there is a focus change the
property change handler will be called for the object which lost the focus
with the old_value containing the AtkState value corresponding to focused
and the property change handler will be called for the object which
received the focus with the new_value containing the AtkState value
corresponding to focused.

</para>

@property_name: 
@old_value: 
@new_value: 

<!-- ##### USER_FUNCTION AtkFunction ##### -->
<para>
An AtkFunction is a function definition used for padding which has been added 
to class and interface structures to allow for expansion in the future.

</para>

@data: a gpointer to parameter data.
@Returns: Nothing useful, this is only a dummy prototype.


<!-- ##### USER_FUNCTION AtkPropertyChangeHandler ##### -->
<para>
An AtkPropertyChangeHandler is a function which is executed when an AtkObject's property changes value. It is specified in a call to 
atk_object_connect_property_change_handler().
</para>

@Param1:  an #AtkObject
@Param2:  an #AtkPropertyValues


<!-- ##### FUNCTION atk_implementor_ref_accessible ##### -->
<para>

</para>

@implementor: 
@Returns: 


<!-- ##### FUNCTION atk_object_get_name ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_object_get_description ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_object_get_parent ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_object_get_n_accessible_children ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_object_ref_accessible_child ##### -->
<para>

</para>

@accessible: 
@i: 
@Returns: 


<!-- ##### FUNCTION atk_object_ref_relation_set ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_object_get_layer ##### -->
<para>

</para>

@accessible: 
@Returns: 
@Deprecated: Use atk_component_get_layer instead.


<!-- ##### FUNCTION atk_object_get_mdi_zorder ##### -->
<para>

</para>

@accessible: 
@Returns: 
@Deprecated: Use atk_component_get_mdi_zorder instead.


<!-- ##### FUNCTION atk_object_get_role ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_object_ref_state_set ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_object_get_index_in_parent ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_object_set_name ##### -->
<para>

</para>

@accessible: 
@name: 


<!-- ##### FUNCTION atk_object_set_description ##### -->
<para>

</para>

@accessible: 
@description: 


<!-- ##### FUNCTION atk_object_set_parent ##### -->
<para>

</para>

@accessible: 
@parent: 


<!-- ##### FUNCTION atk_object_set_role ##### -->
<para>

</para>

@accessible: 
@role: 


<!-- ##### FUNCTION atk_object_connect_property_change_handler ##### -->
<para>

</para>

@accessible: 
@handler: 
@Returns: 


<!-- ##### FUNCTION atk_object_remove_property_change_handler ##### -->
<para>

</para>

@accessible: 
@handler_id: 


<!-- ##### FUNCTION atk_object_notify_state_change ##### -->
<para>

</para>

@accessible: 
@state: 
@value: 


<!-- ##### FUNCTION atk_object_initialize ##### -->
<para>

</para>

@accessible: 
@data: 


<!-- ##### FUNCTION atk_object_add_relationship ##### -->
<para>

</para>

@object: 
@relationship: 
@target: 
@Returns: 


<!-- ##### FUNCTION atk_object_remove_relationship ##### -->
<para>

</para>

@object: 
@relationship: 
@target: 
@Returns: 


<!-- ##### FUNCTION atk_object_get_attributes ##### -->
<para>

</para>

@accessible: 
@Returns: 


<!-- ##### FUNCTION atk_role_get_name ##### -->
<para>

</para>

@role: 
@Returns: 


<!-- ##### FUNCTION atk_role_get_localized_name ##### -->
<para>

</para>

@role: 
@Returns: 


<!-- ##### FUNCTION atk_role_for_name ##### -->
<para>

</para>

@name: 
@Returns: