Evas textblock: fix legacy header

Fix ABI changes with const qualifiers, as well as some missing docs.

2 files changed, 117 insertions, 19 deletions

diff --git a/src/lib/evas/canvas/evas_object_textblock.c b/src/lib/evas/canvas/evas_object_textblock.c
index cee5a5720c..e897607e41 100644
--- a/src/lib/evas/canvas/evas_object_textblock.c
+++ b/src/lib/evas/canvas/evas_object_textblock.c
@@ -769,7 +769,6 @@ static Eina_Bool _evas_textblock_cursor_format_is_visible_get(const Efl_Text_Cur
 static void _find_layout_item_line_match(Evas_Object *eo_obj, Evas_Object_Textblock_Node_Text *n, size_t pos, Evas_Object_Textblock_Line **lnr, Evas_Object_Textblock_Item **itr);
 static Evas_Object_Textblock_Node_Format *_evas_textblock_cursor_node_format_at_pos_get(const Efl_Text_Cursor_Cursor_Data *cur);
 static int _evas_textblock_cursor_text_prepend(Efl_Text_Cursor_Cursor_Data *cur, const char *_text);
-EAPI int evas_textblock_cursor_compare(const Efl_Text_Cursor_Cursor_Data *cur1, const Efl_Canvas_Text_Cursor *cur2);
 static void _evas_textblock_cursor_copy(Efl_Text_Cursor_Cursor_Data *dst, const Efl_Canvas_Text_Cursor *src);
 
 /** selection iterator */
@@ -8395,10 +8394,10 @@ _evas_textblock_cursor_init(Efl_Text_Cursor_Cursor_Data *cur, const Evas_Object
 }
 
 EAPI Efl_Text_Cursor_Cursor_Data *
-evas_object_textblock_cursor_new(Eo *eo_obj)
+evas_object_textblock_cursor_new(const Evas_Object *eo_obj)
 {
    EINA_SAFETY_ON_NULL_RETURN_VAL(eo_obj, NULL);
-   return efl_text_cursor_new(eo_obj);
+   return efl_text_cursor_new((Eo *) eo_obj);
 }
 
 EAPI void
@@ -15687,7 +15686,7 @@ _efl_canvas_text_efl_text_cursor_cursor_get(Eo *eo_obj EINA_UNUSED, Efl_Canvas_T
 }
 
 EAPI Efl_Text_Cursor_Cursor_Data *
-evas_object_textblock_cursor_get(Eo *eo_obj EINA_UNUSED)
+evas_object_textblock_cursor_get(const Evas_Object *eo_obj EINA_UNUSED)
 {
    return efl_text_cursor_get(eo_obj, EFL_TEXT_CURSOR_GET_MAIN);
 }
diff --git a/src/lib/evas/canvas/evas_textblock_legacy.h b/src/lib/evas/canvas/evas_textblock_legacy.h
index 770b317146..664a2a7a74 100644
--- a/src/lib/evas/canvas/evas_textblock_legacy.h
+++ b/src/lib/evas/canvas/evas_textblock_legacy.h
@@ -842,7 +842,7 @@ EAPI void                                     evas_textblock_cursor_copy(const E
  *  @param obj The textblock to which the new cursor will associate.
  *  @return Returns a new cursor associated with the given textblock object.
  */
-EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(Evas_Object *obj);
+EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(const Evas_Object *obj);
 
 /**
  * @brief Sets the position of the cursor according to the X and Y coordinates.
@@ -855,11 +855,36 @@ EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(Evas_Object *obj);
  */
 EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *obj, Evas_Coord x, Evas_Coord y);
 
-EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *_text);
-
+/**
+ * Free the cursor and unassociate it from the object.
+ * @note do not use it to free unassociated cursors.
+ *
+ * @param cur the cursor to free.
+ * @return Returns no value.
+ */
 EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur);
 
-EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *_text);
+/**
+ * Adds text to the current cursor position and set the cursor to *before*
+ * the start of the text just added.
+ *
+ * @param cur the cursor to where to add text at.
+ * @param text the text to add.
+ * @return Returns the len of the text added.
+ * @see evas_textblock_cursor_text_prepend()
+ */
+EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * Adds text to the current cursor position and set the cursor to *after*
+ * the start of the text just added.
+ *
+ * @param cur the cursor to where to add text at.
+ * @param text the text to add.
+ * @return Returns the len of the text added.
+ * @see evas_textblock_cursor_text_append()
+ */
+EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2);
 
 /**
  * @brief The "replacement character" to use for the given textblock object.
@@ -909,26 +934,100 @@ EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align);
  */
 EAPI double evas_object_textblock_valign_get(const Evas_Object *obj);
 
-EAPI void evas_textblock_cursor_paragraph_first(Efl_Canvas_Text_Cursor *cur);
+/**
+ * Sets the cursor to the start of the first text node.
+ *
+ * @param cur the cursor to update.
+ * @return Returns no value.
+ */
+EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur);
 
-EAPI void evas_textblock_cursor_paragraph_last(Efl_Canvas_Text_Cursor *cur);
+/**
+ * sets the cursor to the end of the last text node.
+ *
+ * @param cur the cursor to set.
+ * @return Returns no value.
+ */
+EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur);
 
-EAPI int evas_textblock_cursor_compare(const Efl_Canvas_Text_Cursor *cur1, const Efl_Canvas_Text_Cursor *cur2);
+/**
+ * Compare two cursors.
+ *
+ * @param cur1 the first cursor.
+ * @param cur2 the second cursor.
+ * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.
+ */
+EAPI int evas_textblock_cursor_compare(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2);
 
-EAPI void evas_textblock_cursor_line_char_first(Efl_Canvas_Text_Cursor *cur);
+/**
+ * @brief Checks if two cursors are equal
+ *
+ * This is faster than @ref evas_textblock_cursor_compare so it should be used
+ * if all we care about is equality.
+ *
+ * @param[in] cur The second cursor.
+ *
+ * @return @c true if equal
+ *
+ * @since 1.18
+ *
+ * @ingroup Efl_Canvas_Text_Cursor
+ */
+EAPI Eina_Bool evas_textblock_cursor_equal(const Efl_Canvas_Text_Cursor *obj, const Efl_Canvas_Text_Cursor *cur);
 
-EAPI void evas_textblock_cursor_line_char_last(Efl_Canvas_Text_Cursor *cur);
+/**
+ * Go to the start of the current line
+ *
+ * @param cur the cursor to update.
+ * @return Returns no value.
+ */
+EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur);
 
-EAPI void evas_textblock_cursor_pos_set(Efl_Canvas_Text_Cursor *cur, int _pos);
+/**
+ * Go to the end of the current line.
+ *
+ * @param cur the cursor to update.
+ * @return Returns no value.
+ */
+EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur);
 
-EAPI void evas_textblock_cursor_paragraph_char_first(Efl_Canvas_Text_Cursor *cur);
+/**
+ * Set the cursor pos.
+ *
+ * @param cur the cursor to be set.
+ * @param pos the pos to set.
+ */
+EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int _pos);
 
-EAPI void evas_textblock_cursor_paragraph_char_last(Efl_Canvas_Text_Cursor *cur);
+/**
+ * Go to the first char in the node the cursor is pointing on.
+ *
+ * @param cur the cursor to update.
+ * @return Returns no value.
+ */
+EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur);
 
-EAPI void evas_textblock_cursor_char_delete(Efl_Canvas_Text_Cursor *cur);
+/**
+ * Go to the last char in a text node.
+ *
+ * @param cur the cursor to update.
+ * @return Returns no value.
+ */
+EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur);
 
-EAPI Efl_Canvas_Text_Cursor *evas_object_textblock_cursor_get(Evas_Object *obj);
-//#include "canvas/efl_canvas_text_cursor.eo.legacy.h"
+/**
+ * Deletes a single character from position pointed by given cursor.
+ *
+ * @param cur the cursor to update.
+ * @return Returns no value.
+ */
+EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur);
+
+/** Get the object's main cursor.
+ *
+ * @ingroup Evas_Textblock
+ */
+EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj);
 #include "canvas/efl_canvas_text.eo.legacy.h"
 /**
  * @}