atkutil.xml

The ATK library provides a set of interfaces for accessibility.By supporting the ATK interfaces, an

<refentry id="AtkUtil">
<refmeta>
<refentrytitle role="top_of_page" id="AtkUtil.top_of_page">AtkUtil</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>ATK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>AtkUtil</refname>
<refpurpose>A set of ATK utility functions for event and toolkit support.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="AtkUtil.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
                    <link linkend="AtkUtil-struct">AtkUtil</link>;
enum                <link linkend="AtkCoordType">AtkCoordType</link>;
<link linkend="guint">guint</link>               <link linkend="atk-add-focus-tracker">atk_add_focus_tracker</link>               (<link linkend="AtkEventListener">AtkEventListener</link> focus_tracker);
<link linkend="void">void</link>                <link linkend="atk-remove-focus-tracker">atk_remove_focus_tracker</link>            (<link linkend="guint">guint</link> tracker_id);
<link linkend="void">void</link>                <link linkend="atk-focus-tracker-init">atk_focus_tracker_init</link>              (<link linkend="AtkEventListenerInit">AtkEventListenerInit</link> init);
<link linkend="void">void</link>                <link linkend="atk-focus-tracker-notify">atk_focus_tracker_notify</link>            (<link linkend="AtkObject">AtkObject</link> *object);
<link linkend="void">void</link>                (<link linkend="AtkEventListener">*AtkEventListener</link>)                 (<link linkend="AtkObject">AtkObject</link> *obj);
<link linkend="void">void</link>                (<link linkend="AtkEventListenerInit">*AtkEventListenerInit</link>)             (void);
<link linkend="guint">guint</link>               <link linkend="atk-add-global-event-listener">atk_add_global_event_listener</link>       (<link linkend="GSignalEmissionHook">GSignalEmissionHook</link> listener,
                                                         const <link linkend="gchar">gchar</link> *event_type);
<link linkend="void">void</link>                <link linkend="atk-remove-global-event-listener">atk_remove_global_event_listener</link>    (<link linkend="guint">guint</link> listener_id);
                    <link linkend="AtkKeyEventStruct">AtkKeyEventStruct</link>;
enum                <link linkend="AtkKeyEventType">AtkKeyEventType</link>;
<link linkend="gint">gint</link>                (<link linkend="AtkKeySnoopFunc">*AtkKeySnoopFunc</link>)                  (<link linkend="AtkKeyEventStruct">AtkKeyEventStruct</link> *event,
                                                         <link linkend="gpointer">gpointer</link> func_data);
<link linkend="guint">guint</link>               <link linkend="atk-add-key-event-listener">atk_add_key_event_listener</link>          (<link linkend="AtkKeySnoopFunc">AtkKeySnoopFunc</link> listener,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link>                <link linkend="atk-remove-key-event-listener">atk_remove_key_event_listener</link>       (<link linkend="guint">guint</link> listener_id);
<link linkend="AtkObject">AtkObject</link>*          <link linkend="atk-get-root">atk_get_root</link>                        (void);
<link linkend="AtkObject">AtkObject</link>*          <link linkend="atk-get-focus-object">atk_get_focus_object</link>                (void);
const <link linkend="gchar">gchar</link>*        <link linkend="atk-get-toolkit-name">atk_get_toolkit_name</link>                (void);
const <link linkend="gchar">gchar</link>*        <link linkend="atk-get-toolkit-version">atk_get_toolkit_version</link>             (void);
</synopsis>
</refsynopsisdiv>

<refsect1 id="AtkUtil.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----AtkUtil
</synopsis>

</refsect1>








<refsect1 id="AtkUtil.description" role="desc">
<title role="desc.title">Description</title>
<para>
A set of ATK utility functions which are used to support event registration of
various types, and obtaining the 'root' accessible of a process and
information about the current ATK implementation and toolkit version.
</para>
</refsect1>

<refsect1 id="AtkUtil.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="AtkUtil-struct" role="struct">
<title>AtkUtil</title>
<indexterm zone="AtkUtil-struct"><primary>AtkUtil</primary></indexterm><programlisting>typedef struct _AtkUtil AtkUtil;</programlisting>
<para>
The AtkUtil struct does not contain any fields.
</para></refsect2>
<refsect2 id="AtkCoordType" role="enum">
<title>enum AtkCoordType</title>
<indexterm zone="AtkCoordType"><primary>AtkCoordType</primary></indexterm><programlisting>typedef enum {
  ATK_XY_SCREEN,
  ATK_XY_WINDOW
}AtkCoordType;
</programlisting>
<para>
Specifies how xy coordinates are to be interpreted. Used by functions such
as <link linkend="atk-component-get-position"><function>atk_component_get_position()</function></link> and <link linkend="atk-text-get-character-extents"><function>atk_text_get_character_extents()</function></link></para>
<para>

</para><variablelist role="enum">
<varlistentry id="ATK-XY-SCREEN:CAPS" role="constant">
<term><literal>ATK_XY_SCREEN</literal></term>
<listitem><simpara> specifies xy coordinates relative to the screen
</simpara></listitem>
</varlistentry>
<varlistentry id="ATK-XY-WINDOW:CAPS" role="constant">
<term><literal>ATK_XY_WINDOW</literal></term>
<listitem><simpara> specifies xy coordinates relative to the widget's 
top-level window
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="atk-add-focus-tracker" role="function">
<title>atk_add_focus_tracker ()</title>
<indexterm zone="atk-add-focus-tracker"><primary>atk_add_focus_tracker</primary></indexterm><programlisting><link linkend="guint">guint</link>               atk_add_focus_tracker               (<link linkend="AtkEventListener">AtkEventListener</link> focus_tracker);</programlisting>
<para>
Adds the specified function to the list of functions to be called
when an object receives focus.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>focus_tracker</parameter>&nbsp;:</term>
<listitem><simpara> Function to be added to the list of functions to be called
when an object receives focus.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> added focus tracker id, or 0 on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="atk-remove-focus-tracker" role="function">
<title>atk_remove_focus_tracker ()</title>
<indexterm zone="atk-remove-focus-tracker"><primary>atk_remove_focus_tracker</primary></indexterm><programlisting><link linkend="void">void</link>                atk_remove_focus_tracker            (<link linkend="guint">guint</link> tracker_id);</programlisting>
<para>
Removes the specified focus tracker from the list of functions
to be called when any object receives focus.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>tracker_id</parameter>&nbsp;:</term>
<listitem><simpara> the id of the focus tracker to remove
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="atk-focus-tracker-init" role="function">
<title>atk_focus_tracker_init ()</title>
<indexterm zone="atk-focus-tracker-init"><primary>atk_focus_tracker_init</primary></indexterm><programlisting><link linkend="void">void</link>                atk_focus_tracker_init              (<link linkend="AtkEventListenerInit">AtkEventListenerInit</link> init);</programlisting>
<para>
Specifies the function to be called for focus tracker initialization.
This function should be called by an implementation of the
ATK interface if any specific work needs to be done to enable
focus tracking.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>init</parameter>&nbsp;:</term>
<listitem><simpara> Function to be called for focus tracker initialization
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="atk-focus-tracker-notify" role="function">
<title>atk_focus_tracker_notify ()</title>
<indexterm zone="atk-focus-tracker-notify"><primary>atk_focus_tracker_notify</primary></indexterm><programlisting><link linkend="void">void</link>                atk_focus_tracker_notify            (<link linkend="AtkObject">AtkObject</link> *object);</programlisting>
<para>
Cause the focus tracker functions which have been specified to be
executed for the object.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="AtkObject"><type>AtkObject</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="AtkEventListener" role="function">
<title>AtkEventListener ()</title>
<indexterm zone="AtkEventListener"><primary>AtkEventListener</primary></indexterm><programlisting><link linkend="void">void</link>                (*AtkEventListener)                 (<link linkend="AtkObject">AtkObject</link> *obj);</programlisting>
<para>
A function which is called when an object emits a matching event,
as used in <link linkend="atk-add-focus-tracker"><type>atk_add_focus_tracker</type></link>.
Currently the only events for which object-specific handlers are
supported are events of type "focus:".  Most clients of ATK will prefer to 
attach signal handlers for the various ATK signals instead.
</para>
<para>
<parameter>see</parameter>: atk_add_focus_tracker.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>obj</parameter>&nbsp;:</term>
<listitem><simpara> An <link linkend="AtkObject"><type>AtkObject</type></link> instance for whom the callback will be called when
the specified event (e.g. 'focus:') takes place.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="AtkEventListenerInit" role="function">
<title>AtkEventListenerInit ()</title>
<indexterm zone="AtkEventListenerInit"><primary>AtkEventListenerInit</primary></indexterm><programlisting><link linkend="void">void</link>                (*AtkEventListenerInit)             (void);</programlisting>
<para>
An <link linkend="AtkEventListenerInit"><type>AtkEventListenerInit</type></link> function is a special function that is
called in order to initialize the per-object event registration system
used by <link linkend="AtkEventListener"><type>AtkEventListener</type></link>, if any preparation is required.  
</para>
<para>
<parameter>see</parameter>: atk_focus_tracker_init.</para>
<para>

</para></refsect2>
<refsect2 id="atk-add-global-event-listener" role="function">
<title>atk_add_global_event_listener ()</title>
<indexterm zone="atk-add-global-event-listener"><primary>atk_add_global_event_listener</primary></indexterm><programlisting><link linkend="guint">guint</link>               atk_add_global_event_listener       (<link linkend="GSignalEmissionHook">GSignalEmissionHook</link> listener,
                                                         const <link linkend="gchar">gchar</link> *event_type);</programlisting>
<para>
Adds the specified function to the list of functions to be called
when an event of type event_type occurs.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>listener</parameter>&nbsp;:</term>
<listitem><simpara> the listener to notify
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event_type</parameter>&nbsp;:</term>
<listitem><simpara> the type of event for which notification is requested
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> added event listener id, or 0 on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="atk-remove-global-event-listener" role="function">
<title>atk_remove_global_event_listener ()</title>
<indexterm zone="atk-remove-global-event-listener"><primary>atk_remove_global_event_listener</primary></indexterm><programlisting><link linkend="void">void</link>                atk_remove_global_event_listener    (<link linkend="guint">guint</link> listener_id);</programlisting>
<para>