/**
* atk_text_get_text:
* @text: an #AtkText
- * @start_offset: start position
- * @end_offset: end position, or -1 for the end of the string.
+ * @start_offset: a starting character offset within @text
+ * @end_offset: an ending character offset within @text, or -1 for the end of the string.
*
* Gets the specified text.
*
* Returns: a newly allocated string containing the text from @start_offset up
- * to, but not including @end_offset. Use g_free() to free the returned string.
+ * to, but not including @end_offset. Use g_free() to free the returned
+ * string.
**/
gchar*
atk_text_get_text (AtkText *text,
/**
* atk_text_get_character_at_offset:
* @text: an #AtkText
- * @offset: position
+ * @offset: a character offset within @text
*
* Gets the specified text.
*
- * Returns: the character at @offset.
+ * Returns: the character at @offset or 0 in the case of failure.
**/
gunichar
atk_text_get_character_at_offset (AtkText *text,
* @text: an #AtkText
* @offset: position
* @boundary_type: An #AtkTextBoundary
- * @start_offset: (out): the start offset of the returned string
+ * @start_offset: (out): the starting character offset of the returned string
* @end_offset: (out): the offset of the first character after the
* returned substring
*
* Deprecated: 2.9.3: Please use atk_text_get_string_at_offset() instead.
*
* Returns: a newly allocated string containing the text after @offset bounded
- * by the specified @boundary_type. Use g_free() to free the returned string.
+ * by the specified @boundary_type. Use g_free() to free the returned
+ * string.
**/
gchar*
atk_text_get_text_after_offset (AtkText *text,
* @text: an #AtkText
* @offset: position
* @boundary_type: An #AtkTextBoundary
- * @start_offset: (out): the start offset of the returned string
+ * @start_offset: (out): the starting character offset of the returned string
* @end_offset: (out): the offset of the first character after the
* returned substring
*
* Deprecated: This method is deprecated since ATK version
* 2.9.4. Please use atk_text_get_string_at_offset() instead.
*
- * Returns: a newly allocated string containing the text at @offset bounded by
- * the specified @boundary_type. Use g_free() to free the returned string.
+ * Returns: a newly allocated string containing the text at @offset bounded
+ * by the specified @boundary_type. Use g_free() to free the returned
+ * string.
**/
gchar*
atk_text_get_text_at_offset (AtkText *text,
* @text: an #AtkText
* @offset: position
* @boundary_type: An #AtkTextBoundary
- * @start_offset: (out): the start offset of the returned string
+ * @start_offset: (out): the starting character offset of the returned string
* @end_offset: (out): the offset of the first character after the
* returned substring
*
* Deprecated: 2.9.3: Please use atk_text_get_string_at_offset() instead.
*
* Returns: a newly allocated string containing the text before @offset bounded
- * by the specified @boundary_type. Use g_free() to free the returned string.
+ * by the specified @boundary_type. Use g_free() to free the returned
+ * string.
**/
gchar*
atk_text_get_text_before_offset (AtkText *text,
* @text: an #AtkText
* @offset: position
* @granularity: An #AtkTextGranularity
- * @start_offset: (out): the start offset of the returned string, or -1
- * if an error has occurred (e.g. invalid offset, not implemented)
+ * @start_offset: (out): the starting character offset of the returned string, or -1
+ * in the case of error (e.g. invalid offset, not implemented)
* @end_offset: (out): the offset of the first character after the returned string,
- * or -1 if an error has occurred (e.g. invalid offset, not implemented)
+ * or -1 in the case of error (e.g. invalid offset, not implemented)
*
* Gets a portion of the text exposed through an #AtkText according to a given @offset
* and a specific @granularity, along with the start and end offsets defining the
*
* Since: 2.10
*
- * Returns: (nullable): a newly allocated string containing the text
- * at the @offset bounded by the specified @granularity. Use
- * g_free() to free the returned string. Returns %NULL if the
- * offset is invalid or no implementation is available.
+ * Returns: (nullable): a newly allocated string containing the text at
+ * the @offset bounded by the specified @granularity. Use g_free()
+ * to free the returned string. Returns %NULL if the offset is invalid
+ * or no implementation is available.
**/
gchar* atk_text_get_string_at_offset (AtkText *text,
gint offset,
* atk_text_get_caret_offset:
* @text: an #AtkText
*
- * Gets the offset position of the caret (cursor).
+ * Gets the offset of the position of the caret (cursor).
*
- * Returns: the offset position of the caret (cursor).
+ * Returns: the character offset of the position of the caret or 0 if
+ * the caret is not located inside the element or in the case of
+ * any other failure.
**/
gint
atk_text_get_caret_offset (AtkText *text)
* atk_text_get_character_extents:
* @text: an #AtkText
* @offset: The offset of the text character for which bounding information is required.
- * @x: (out) (optional): Pointer for the x cordinate of the bounding box
- * @y: (out) (optional): Pointer for the y cordinate of the bounding box
+ * @x: (out) (optional): Pointer for the x coordinate of the bounding box
+ * @y: (out) (optional): Pointer for the y coordinate of the bounding box
* @width: (out) (optional): Pointer for the width of the bounding box
* @height: (out) (optional): Pointer for the height of the bounding box
* @coords: specify whether coordinates are relative to the screen or widget window
gint *y,
gint *width,
gint *height,
- AtkCoordType coords)
+ AtkCoordType coords)
{
AtkTextIface *iface;
gint local_x, local_y, local_width, local_height;
/**
* atk_text_get_run_attributes:
*@text: an #AtkText
- *@offset: the offset at which to get the attributes, -1 means the offset of
+ *@offset: the character offset at which to get the attributes, -1 means the offset of
*the character to be inserted at the caret location.
*@start_offset: (out): the address to put the start offset of the range
*@end_offset: (out): the address to put the end offset of the range
*returned.
*
*Returns: (transfer full): an #AtkAttributeSet which contains the attributes
- * explicitly set at @offset. This #AtkAttributeSet should be freed by a call
- * to atk_attribute_set_free().
+ * explicitly set at @offset. This #AtkAttributeSet should be freed by
+ * a call to atk_attribute_set_free().
**/
AtkAttributeSet*
atk_text_get_run_attributes (AtkText *text,
*attributes that can be returned. Note that other attributes may also be
*returned.
*
- *Returns: (transfer full): an #AtkAttributeSet which contains the default
- * values of attributes. at @offset. this #atkattributeset should be freed by
- * a call to atk_attribute_set_free().
+ *Returns: (transfer full): an #AtkAttributeSet which contains the default values
+ * of attributes. at @offset. this #atkattributeset should be freed by
+ * a call to atk_attribute_set_free().
*/
AtkAttributeSet*
atk_text_get_default_attributes (AtkText *text)
*
* Gets the character count.
*
- * Returns: the number of characters.
+ * Returns: the number of characters or -1 in case of failure.
**/
gint
atk_text_get_character_count (AtkText *text)
* are interpreted as being relative to the screen or this widget's window
* depending on @coords.
*
- * Returns: the offset to the character which is located at
- * the specified @x and @y coordinates.
+ * Returns: the offset to the character which is located at the specified
+ * @x and @y coordinates of -1 in case of failure.
**/
gint
atk_text_get_offset_at_point (AtkText *text,
*
* Gets the number of selected regions.
*
- * Returns: The number of selected regions, or -1 if a failure
- * occurred.
+ * Returns: The number of selected regions, or -1 in the case of failure.
**/
gint
atk_text_get_n_selections (AtkText *text)
* start of the text. The selected region closest to the beginning
* of the text region is assigned the number 0, etc. Note that adding,
* moving or deleting a selected region can change the numbering.
- * @start_offset: (out): passes back the start position of the selected region
- * @end_offset: (out): passes back the end position of (e.g. offset immediately past)
- * the selected region
+ * @start_offset: (out): passes back the starting character offset of the selected region
+ * @end_offset: (out): passes back the ending character offset (offset immediately past)
+ * of the selected region
*
* Gets the text from the specified selection.
*
* Returns: a newly allocated string containing the selected text. Use g_free()
- * to free the returned string.
+ * to free the returned string.
**/
gchar*
atk_text_get_selection (AtkText *text,
/**
* atk_text_add_selection:
* @text: an #AtkText
- * @start_offset: the start position of the selected region
+ * @start_offset: the starting character offset of the selected region
* @end_offset: the offset of the first character after the selected region.
*
* Adds a selection bounded by the specified offsets.
*
- * Returns: %TRUE if success, %FALSE otherwise
+ * Returns: %TRUE if successful, %FALSE otherwise
**/
gboolean
atk_text_add_selection (AtkText *text,
*
* Removes the specified selection.
*
- * Returns: %TRUE if success, %FALSE otherwise
+ * Returns: %TRUE if successful, %FALSE otherwise
**/
gboolean
atk_text_remove_selection (AtkText *text,
* start of the text. The selected region closest to the beginning
* of the text region is assigned the number 0, etc. Note that adding,
* moving or deleting a selected region can change the numbering.
- * @start_offset: the new start position of the selection
+ * @start_offset: the new starting character offset of the selection
* @end_offset: the new end position of (e.g. offset immediately past)
* the selection
*
* Changes the start and end offset of the specified selection.
*
- * Returns: %TRUE if success, %FALSE otherwise
+ * Returns: %TRUE if successful, %FALSE otherwise
**/
gboolean
atk_text_set_selection (AtkText *text,
/**
* atk_text_set_caret_offset:
* @text: an #AtkText
- * @offset: position
+ * @offset: the character offset of the new caret position
*
* Sets the caret (cursor) position to the specified @offset.
*
- * Returns: %TRUE if success, %FALSE otherwise.
+ * Returns: %TRUE if successful, %FALSE otherwise.
**/
gboolean
atk_text_set_caret_offset (AtkText *text,
}
/**
- * atk_text_get_bounded_ranges:
+ * atk_text_get_bounded_ranges: (virtual get_bounded_ranges)
* @text: an #AtkText
* @rect: An AtkTextRectangle giving the dimensions of the bounding box.
* @coord_type: Specify whether coordinates are relative to the screen or widget window.
* Get the #AtkTextAttribute type corresponding to a text attribute name.
*
* Returns: the #AtkTextAttribute enumerated type corresponding to the specified
-name,
- * or #ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute is found.
+ * name, or #ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute
+ * is found.
**/
AtkTextAttribute
atk_text_attribute_for_name (const gchar *name)
projects / platform / upstream / atk.git / blobdiff