atktext.xml

linux下图形库开发包atk-1.4.0.tar.gz

<refentry id="AtkText">
<refmeta>
<refentrytitle>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>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



struct      <link linkend="AtkText-struct">AtkText</link>;
enum        <link linkend="AtkTextBoundary">AtkTextBoundary</link>;
enum        <link linkend="AtkTextClipType">AtkTextClipType</link>;
struct      <link linkend="AtkTextRange">AtkTextRange</link>;
struct      <link linkend="AtkTextRectangle">AtkTextRectangle</link>;
struct      <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);
G_CONST_RETURN <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);
G_CONST_RETURN <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>
<title>Object Hierarchy</title>
<synopsis>

  <link linkend="GInterface">GInterface</link>
   +----AtkText
</synopsis>

</refsect1>




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

</refsect1>


<refsect1>
<title>Signal Prototypes</title>
<synopsis>

&quot;<link linkend="AtkText-text-attributes-changed">text-attributes-changed</link>&quot;
            <link linkend="void">void</link>        user_function      (<link linkend="AtkText">AtkText</link> *atktext,
                                            <link linkend="gpointer">gpointer</link> user_data);
&quot;<link linkend="AtkText-text-caret-moved">text-caret-moved</link>&quot;
            <link linkend="void">void</link>        user_function      (<link linkend="AtkText">AtkText</link> *atktext,
                                            <link linkend="gint">gint</link> arg1,
                                            <link linkend="gpointer">gpointer</link> user_data);
&quot;<link linkend="AtkText-text-changed">text-changed</link>&quot;
            <link linkend="void">void</link>        user_function      (<link linkend="AtkText">AtkText</link> *atktext,
                                            <link linkend="gint">gint</link> arg1,
                                            <link linkend="gint">gint</link> arg2,
                                            <link linkend="gpointer">gpointer</link> user_data);
&quot;<link linkend="AtkText-text-selection-changed">text-selection-changed</link>&quot;
            <link linkend="void">void</link>        user_function      (<link linkend="AtkText">AtkText</link> *atktext,
                                            <link linkend="gpointer">gpointer</link> user_data);
</synopsis>
</refsect1>


<refsect1>
<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>
<title>Details</title>
<refsect2>
<title><anchor id="AtkText-struct"/>struct AtkText</title>
<indexterm><primary>AtkText</primary></indexterm><programlisting>struct AtkText;</programlisting>
<para>
The AtkText structure does not contain any fields.

</para></refsect2>
<refsect2>
<title><anchor id="AtkTextBoundary"/>enum AtkTextBoundary</title>
<indexterm><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></refsect2>
<refsect2>
<title><anchor id="AtkTextClipType"/>enum AtkTextClipType</title>
<indexterm><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>
Describes the type of clipping required.</para>
<para>

</para><variablelist role="enum">
<varlistentry>
<term><literal>ATK_TEXT_CLIP_NONE</literal></term>
<listitem><simpara> No clipping to be done
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>ATK_TEXT_CLIP_MIN</literal></term>
<listitem><simpara> Text clipped by min coordinate is omitted
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>ATK_TEXT_CLIP_MAX</literal></term>
<listitem><simpara> Text clipped by max coordinate is omitted
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>ATK_TEXT_CLIP_BOTH</literal></term>
<listitem><simpara> Only text fully within mix/max bound is retained
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="AtkTextRange"/>struct AtkTextRange</title>
<indexterm><primary>AtkTextRange</primary></indexterm><programlisting>struct AtkTextRange {

  AtkTextRectangle bounds;
  gint start_offset;
  gint end_offset;
  gchar* content;
};