atktext.xml

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

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

<refnamediv>
<refname>AtkText</refname>
<refpurpose>The ATK interface implemented by components with text content.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>
                    <link linkend="AtkText-struct">AtkText</link>;
enum                <link linkend="AtkTextBoundary">AtkTextBoundary</link>;
enum                <link linkend="AtkTextClipType">AtkTextClipType</link>;
                    <link linkend="AtkTextRange">AtkTextRange</link>;
                    <link linkend="AtkTextRectangle">AtkTextRectangle</link>;
                    <link linkend="AtkAttribute">AtkAttribute</link>;
typedef             <link linkend="AtkAttributeSet">AtkAttributeSet</link>;
enum                <link linkend="AtkTextAttribute">AtkTextAttribute</link>;
<link linkend="gchar">gchar</link>*              <link linkend="atk-text-get-text">atk_text_get_text</link>                   (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> start_offset,
                                                         <link linkend="gint">gint</link> end_offset);
<link linkend="gunichar">gunichar</link>            <link linkend="atk-text-get-character-at-offset">atk_text_get_character_at_offset</link>    (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> offset);
<link linkend="gchar">gchar</link>*              <link linkend="atk-text-get-text-after-offset">atk_text_get_text_after_offset</link>      (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> offset,
                                                         <link linkend="AtkTextBoundary">AtkTextBoundary</link> boundary_type,
                                                         <link linkend="gint">gint</link> *start_offset,
                                                         <link linkend="gint">gint</link> *end_offset);
<link linkend="gchar">gchar</link>*              <link linkend="atk-text-get-text-at-offset">atk_text_get_text_at_offset</link>         (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> offset,
                                                         <link linkend="AtkTextBoundary">AtkTextBoundary</link> boundary_type,
                                                         <link linkend="gint">gint</link> *start_offset,
                                                         <link linkend="gint">gint</link> *end_offset);
<link linkend="gchar">gchar</link>*              <link linkend="atk-text-get-text-before-offset">atk_text_get_text_before_offset</link>     (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> offset,
                                                         <link linkend="AtkTextBoundary">AtkTextBoundary</link> boundary_type,
                                                         <link linkend="gint">gint</link> *start_offset,
                                                         <link linkend="gint">gint</link> *end_offset);
<link linkend="gint">gint</link>                <link linkend="atk-text-get-caret-offset">atk_text_get_caret_offset</link>           (<link linkend="AtkText">AtkText</link> *text);
<link linkend="void">void</link>                <link linkend="atk-text-get-character-extents">atk_text_get_character_extents</link>      (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> offset,
                                                         <link linkend="gint">gint</link> *x,
                                                         <link linkend="gint">gint</link> *y,
                                                         <link linkend="gint">gint</link> *width,
                                                         <link linkend="gint">gint</link> *height,
                                                         <link linkend="AtkCoordType">AtkCoordType</link> coords);
<link linkend="AtkAttributeSet">AtkAttributeSet</link>*    <link linkend="atk-text-get-run-attributes">atk_text_get_run_attributes</link>         (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> offset,
                                                         <link linkend="gint">gint</link> *start_offset,
                                                         <link linkend="gint">gint</link> *end_offset);
<link linkend="AtkAttributeSet">AtkAttributeSet</link>*    <link linkend="atk-text-get-default-attributes">atk_text_get_default_attributes</link>     (<link linkend="AtkText">AtkText</link> *text);
<link linkend="gint">gint</link>                <link linkend="atk-text-get-character-count">atk_text_get_character_count</link>        (<link linkend="AtkText">AtkText</link> *text);
<link linkend="gint">gint</link>                <link linkend="atk-text-get-offset-at-point">atk_text_get_offset_at_point</link>        (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> x,
                                                         <link linkend="gint">gint</link> y,
                                                         <link linkend="AtkCoordType">AtkCoordType</link> coords);
<link linkend="AtkTextRange">AtkTextRange</link>**      <link linkend="atk-text-get-bounded-ranges">atk_text_get_bounded_ranges</link>         (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="AtkTextRectangle">AtkTextRectangle</link> *rect,
                                                         <link linkend="AtkCoordType">AtkCoordType</link> coord_type,
                                                         <link linkend="AtkTextClipType">AtkTextClipType</link> x_clip_type,
                                                         <link linkend="AtkTextClipType">AtkTextClipType</link> y_clip_type);
<link linkend="void">void</link>                <link linkend="atk-text-get-range-extents">atk_text_get_range_extents</link>          (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> start_offset,
                                                         <link linkend="gint">gint</link> end_offset,
                                                         <link linkend="AtkCoordType">AtkCoordType</link> coord_type,
                                                         <link linkend="AtkTextRectangle">AtkTextRectangle</link> *rect);
<link linkend="void">void</link>                <link linkend="atk-text-free-ranges">atk_text_free_ranges</link>                (<link linkend="AtkTextRange">AtkTextRange</link> **ranges);
<link linkend="gint">gint</link>                <link linkend="atk-text-get-n-selections">atk_text_get_n_selections</link>           (<link linkend="AtkText">AtkText</link> *text);
<link linkend="gchar">gchar</link>*              <link linkend="atk-text-get-selection">atk_text_get_selection</link>              (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> selection_num,
                                                         <link linkend="gint">gint</link> *start_offset,
                                                         <link linkend="gint">gint</link> *end_offset);
<link linkend="gboolean">gboolean</link>            <link linkend="atk-text-add-selection">atk_text_add_selection</link>              (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> start_offset,
                                                         <link linkend="gint">gint</link> end_offset);
<link linkend="gboolean">gboolean</link>            <link linkend="atk-text-remove-selection">atk_text_remove_selection</link>           (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> selection_num);
<link linkend="gboolean">gboolean</link>            <link linkend="atk-text-set-selection">atk_text_set_selection</link>              (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> selection_num,
                                                         <link linkend="gint">gint</link> start_offset,
                                                         <link linkend="gint">gint</link> end_offset);
<link linkend="gboolean">gboolean</link>            <link linkend="atk-text-set-caret-offset">atk_text_set_caret_offset</link>           (<link linkend="AtkText">AtkText</link> *text,
                                                         <link linkend="gint">gint</link> offset);
<link linkend="void">void</link>                <link linkend="atk-attribute-set-free">atk_attribute_set_free</link>              (<link linkend="AtkAttributeSet">AtkAttributeSet</link> *attrib_set);
<link linkend="AtkTextAttribute">AtkTextAttribute</link>    <link linkend="atk-text-attribute-register">atk_text_attribute_register</link>         (const <link linkend="gchar">gchar</link> *name);
const <link linkend="gchar">gchar</link>*        <link linkend="atk-text-attribute-get-name">atk_text_attribute_get_name</link>         (<link linkend="AtkTextAttribute">AtkTextAttribute</link> attr);
<link linkend="AtkTextAttribute">AtkTextAttribute</link>    <link linkend="atk-text-attribute-for-name">atk_text_attribute_for_name</link>         (const <link linkend="gchar">gchar</link> *name);
const <link linkend="gchar">gchar</link>*        <link linkend="atk-text-attribute-get-value">atk_text_attribute_get_value</link>        (<link linkend="AtkTextAttribute">AtkTextAttribute</link> attr,
                                                         <link linkend="gint">gint</link> index_);
</synopsis>
</refsynopsisdiv>

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

</refsect1>




<refsect1 id="AtkText.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
AtkText is implemented by
 <link linkend="AtkNoOpObject">AtkNoOpObject</link>.</para>

</refsect1>


<refsect1 id="AtkText.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<synopsis>
  &quot;<link linkend="AtkText-text-attributes-changed">text-attributes-changed</link>&quot;                        : Run Last
  &quot;<link linkend="AtkText-text-caret-moved">text-caret-moved</link>&quot;                               : Run Last
  &quot;<link linkend="AtkText-text-changed">text-changed</link>&quot;                                   : Run Last / Has Details
  &quot;<link linkend="AtkText-text-selection-changed">text-selection-changed</link>&quot;                         : Run Last
</synopsis>
</refsect1>


<refsect1 id="AtkText.description" role="desc">
<title role="desc.title">Description</title>
<para>
<link linkend="AtkText"><type>AtkText</type></link> should be implemented by <link linkend="AtkObjects"><type>AtkObjects</type></link> on behalf of widgets that
have text content which is either attributed or otherwise non-trivial.
<link linkend="AtkObjects"><type>AtkObjects</type></link> whose text content is simple, unattributed, and very brief
may expose that content via <link linkend="atk-object-get-name"><type>atk_object_get_name</type></link> instead; however if the
text is editable, multi-line, typically longer than three or four words,
attributed, selectable, or if the object already uses the 'name' ATK
property for other information, the <link linkend="AtkText"><type>AtkText</type></link> interface should be used
to expose the text content.  In the case of editable text content,
<link linkend="AtkEditableText"><type>AtkEditableText</type></link> (a subtype of the <link linkend="AtkText"><type>AtkText</type></link> interface) should be
implemented instead.
</para>
<para>
<link linkend="AtkText"><type>AtkText</type></link> provides not only traversal facilities and change notification
for text content, but also caret tracking and glyph bounding box
calculations.  Note that the text strings are exposed as UTF-8, and are
therefore potentially multi-byte, and caret-to-byte offset mapping makes
no assumptions about the character length; also bounding box
glyph-to-offset mapping may be complex for languages which use ligatures.
</para>
</refsect1>

<refsect1 id="AtkText.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="AtkText-struct" role="struct">
<title>AtkText</title>
<indexterm zone="AtkText-struct"><primary>AtkText</primary></indexterm><programlisting>typedef struct _AtkText AtkText;</programlisting>
<para>
The AtkText structure does not contain any fields.

</para></refsect2>
<refsect2 id="AtkTextBoundary" role="enum">
<title>enum AtkTextBoundary</title>
<indexterm zone="AtkTextBoundary"><primary>AtkTextBoundary</primary></indexterm><programlisting>typedef enum {
  ATK_TEXT_BOUNDARY_CHAR,
  ATK_TEXT_BOUNDARY_WORD_START,
  ATK_TEXT_BOUNDARY_WORD_END,
  ATK_TEXT_BOUNDARY_SENTENCE_START,
  ATK_TEXT_BOUNDARY_SENTENCE_END,
  ATK_TEXT_BOUNDARY_LINE_START,
  ATK_TEXT_BOUNDARY_LINE_END
} AtkTextBoundary;
</programlisting>
<para>
Text boundary types used for specifying boundaries for regions of text</para>
<para>

</para><variablelist role="enum">
<varlistentry id="ATK-TEXT-BOUNDARY-CHAR:CAPS" role="constant">
<term><literal>ATK_TEXT_BOUNDARY_CHAR</literal></term>
<listitem><simpara> Boundary is the boundary between characters 
(including non-printing characters)
</simpara></listitem>
</varlistentry>
<varlistentry id="ATK-TEXT-BOUNDARY-WORD-START:CAPS" role="constant">
<term><literal>ATK_TEXT_BOUNDARY_WORD_START</literal></term>
<listitem><simpara> Boundary is the start (i.e. first character) of a word. 
</simpara></listitem>
</varlistentry>
<varlistentry id="ATK-TEXT-BOUNDARY-WORD-END:CAPS" role="constant">
<term><literal>ATK_TEXT_BOUNDARY_WORD_END</literal></term>
<listitem><simpara> Boundary is the end (i.e. last character) of a word.
</simpara></listitem>
</varlistentry>
<varlistentry id="ATK-TEXT-BOUNDARY-SENTENCE-START:CAPS" role="constant">
<term><literal>ATK_TEXT_BOUNDARY_SENTENCE_START</literal></term>
<listitem><simpara> Boundary is the first character in a sentence.
</simpara></listitem>
</varlistentry>
<varlistentry id="ATK-TEXT-BOUNDARY-SENTENCE-END:CAPS" role="constant">
<term><literal>ATK_TEXT_BOUNDARY_SENTENCE_END</literal></term>
<listitem><simpara> Boundary is the last (terminal) character in a sentence; 
in languages which use "sentence stop" punctuation such as English, the boundary is thus the
'.', '?', or similar terminal punctuation character.
</simpara></listitem>
</varlistentry>
<varlistentry id="ATK-TEXT-BOUNDARY-LINE-START:CAPS" role="constant">
<term><literal>ATK_TEXT_BOUNDARY_LINE_START</literal></term>
<listitem><simpara> Boundary is the initial character of the content or a 
character immediately following a newline, linefeed, or return character.
</simpara></listitem>
</varlistentry>
<varlistentry id="ATK-TEXT-BOUNDARY-LINE-END:CAPS" role="constant">
<term><literal>ATK_TEXT_BOUNDARY_LINE_END</literal></term>
<listitem><simpara> Boundary is the linefeed, or return character.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="AtkTextClipType" role="enum">
<title>enum AtkTextClipType</title>
<indexterm zone="AtkTextClipType"><primary>AtkTextClipType</primary></indexterm><programlisting>typedef enum {
    ATK_TEXT_CLIP_NONE,
    ATK_TEXT_CLIP_MIN,
    ATK_TEXT_CLIP_MAX,
    ATK_TEXT_CLIP_BOTH
} AtkTextClipType;
</programlisting>
<para>