Some more doc fixing in entry, mostly cursor, images showing items and an example.

Example that's not of my liking, stupid entry... I will get you while you sleep and teach you how to edit formatted text!



SVN revision: 61770

legacy/elementary/doc/examples.dox

@@ -3647,6 +3647,154 @@
  *
  * @example gengrid_example.c
  */
+/**
+ * @page entry_example_01 Entry - Example of simple editing
+ *
+ * As a general overview of @ref Entry we are going to write an, albeit simple,
+ * functional editor. Although intended to show how elm_entry works, this
+ * example also makes extensive use of several other widgets. The full code
+ * can be found in @ref entry_example.c "entry_example.c" and in the following
+ * lines we'll go through the parts especific to the @ref Entry widget.
+ *
+ * The program itself is a simple editor, with a file already set to it, that
+ * can be set to autosave or not and allows insertion of emoticons and some
+ * formatted text. As of this writing, the capabilities of format edition in
+ * the entry are very limited, so a lot of manual work is required to change
+ * the current text.
+ *
+ * In any case, the program allows some changes by using the buttons on the
+ * top of the window and returning focus back to the main entry afterwards.
+ *
+ * @image html screenshots/entry_example.png
+ * @image latex screenshots/entry_example.eps width=\textwidth
+ *
+ * We'll begin by showing a few structures used throught the program. First,
+ * the application owns data that holds the main window and the main entry
+ * where the editting happens. Then, an auxiliar structure we'll use later
+ * when inserting icons in our text.
+ * @dontinclude entry_example.c
+ * @skip typedef
+ * @until App_Inwin_Data
+ *
+ * A little convenience function will insert whatever text we need in the
+ * buffer at the current cursor's position and set focus back to this entry.
+ * This is done mostly because clicking on any button will make them steal
+ * focus, which makes writing text more cumbersome.
+ * @skip static void
+ * @until }
+ *
+ * One of the buttons on the top will trigger an @ref Inwin to open and show
+ * us several icons we can insert into the text. We'll jump over most of these
+ * functions, but when all the options are chosen, we insert the special
+ * markup text that will show the chosen icon in place.
+ * @skip edje_file_collection_list_free(emos)
+ * @skip static void
+ * @until evas_object_del
+ * @until }
+ *
+ * As can be seen in that function, the program lets us add icons to our entry
+ * using all the possible configurations for them. That should help to
+ * clarify how the different combinations work out by actually seeing them
+ * in action.
+ *
+ * The same popup window has a page to set the settings of the chosen icon,
+ * that is, the size and how the item will be placed within the line.
+ *
+ * The size is done with two entries, limitted to accept numbers and a fixed
+ * size of characters. Changing the value in this entries will update the icon
+ * size in our struct as seen in the next two callbacks.
+ * @skip static void
+ * @until }
+ * @until }
+ *
+ * The rest of the options are handled with radio buttons, since only one type
+ * of size can be used (@c size, @c absize or @c relsize) and for the vertical
+ * sizing it needs to choose between @c ascent and @c full. Depending on which
+ * is chosen, the @c item tag is formed accordingly as seen before.
+ * @skip static Evas_Object
+ * @until evas_object_show(rvascent)
+ *
+ * The first of our entries is here. There's something worth mentioning about
+ * the way we'll create this one. Normally, any entry regardless of whether is
+ * single line or not, will be set to scrollable, but in this case, since we
+ * are limitting how many characters can fit in them and we know we don't need
+ * scrolling, we are not setting this flag. This makes the entry have virtually
+ * no appearance on screen, other than its text. This is because an entry is
+ * just that, a box that holds text, and in order to have some frame around it
+ * or a background color, another widget needs to provide this. When an entry
+ * is scrollable, the same scroller used internally does this.
+ * We are using @ref Frame "frames" here to provide some decoration around,
+ * then creating our entries, set them to single line, add our two filters and
+ * the callback for when their value change.
+ * @until _height_changed_cb
+ *
+ * This function ends with the button that will finally call the item
+ * into our editting string.
+ * @until }
+ *
+ * Then we get to the format edition. Here we can add the @c bold and
+ * @c emphasis tags to parts of our text. There's a lot of manual work to
+ * know what to do here, since we are not implementing an entire state manager
+ * and the entry itself doesn't, yet, support all the needed capabilities to
+ * make this simpler. We begin by getting the format we are using in our
+ * function from the button pressed.
+ * @skip aid->pager = pager;
+ * @until sizeof(fmt_close)
+ *
+ * Next we need to find out if we need to insert an opening or a closing tag.
+ * For this, we store the current cursor position and create a selection
+ * from this point until the beginning of our text, and then get the selected
+ * text to look for any existing format tags in it. This is currently the only
+ * way in which we can find out what formats is being used in the entry.
+ * @until }
+ * @until }
+ *
+ * Once we know what tag to insert, we need a second check in the case it was
+ * a closing tag. This is because any other closing tag that comes after would
+ * be left dangling alone, so we need to remove it to keep the text consistent.
+ * @until }
+ * @until }
+ * Finally, we clear our fake selections and return the cursor back to the
+ * position it had at first, since there is where we want to insert our format.
+ * @until cursor_pos_set
+ *
+ * And finish by calling our convenience function from before, to insert the
+ * text at the current cursor and give focus back to the entry.
+ * @until }
+ *
+ * A checkbox on the top of our program tells us if the text we are editing
+ * will autosave or not. In it's @c "changed" callback we get the value from
+ * the checkbox and call the elm_entry_autosave_set() function with it. If
+ * autosave is set, we also call elm_entry_file_save(). This is so the internal
+ * timer used to periodically store to disk our changes is started.
+ * @skip static void
+ * @until }
+ *
+ * Two more functions to show some cursor playing. Whenever we double click
+ * anywhere on our entry, we'll find what word is the cursor placed at and
+ * select it. Likewise, for triple clicking, we select the entire line.
+ * @skip static void
+ * @until _edit_tplclick_cb
+ * @until }
+ *
+ * And finally, the main window of the program contains the entry where we
+ * do all the edition and some helping widgets to change format, add icons
+ * or change the autosave flag.
+ * @skip elm_exit
+ * @skip int
+ * @until _image_insert_cb
+ *
+ * And the main entry of the program. Set to scroll, by default we disable
+ * autosave and we'll begin with a file set to it because no file selector
+ * is being used here. The file is loaded with #ELM_TEXT_FORMAT_MARKUP_UTF8
+ * so that any format contained in it is interpreted, otherwise the entry
+ * would load it as just text, escaping any tags found and no format or icons
+ * would be shown. Then we connect to the double and triple click signals
+ * and set focus on the entry so we can start typing right away.
+ * @until ELM_MAIN
+ *
+ * @example entry_example.c
+ */
 
 /**
  * @page genlist_example_01

legacy/elementary/src/examples/Makefile.am

@@ -88,7 +88,8 @@ SRCS = \
 	separator_example_01.c \
 	radio_example_01.c \
 	panel_example_01.c \
-	gengrid_example.c
+	gengrid_example.c \
+	entry_example.c
 
 pkglib_PROGRAMS =
 
@@ -167,7 +168,8 @@ pkglib_PROGRAMS += \
 	gengrid_example \
 	genlist_example_01 \
 	genlist_example_02 \
-	genlist_example_03
+	genlist_example_03 \
+	entry_example
 
 # This variable will hold the list of screenshots that will be made
 # by "make screenshots". Each item in the list is of the form:
@@ -218,7 +220,8 @@ SCREENSHOTS = \
 	radio_example_01:radio_example_01.png:0.0 \
 	toggle_example_01:toggle_example_01.png:0.0 \
 	panel_example_01:panel_example_01.png:0.0 \
-	gengrid_example:gengrid_example.png:0.0
+	gengrid_example:gengrid_example.png:0.0 \
+	entry_example:entry_example.png:0.0
 
 HTML_SS_DIR=$(top_builddir)/doc/html/screenshots
 LATEX_SS_DIR=$(top_builddir)/doc/latex/screenshots

legacy/elementary/src/examples/entry_example.c

@@ -0,0 +1,586 @@
+/*
+ * gcc -o entry_example entry_example.c `pkg-config --cflags --libs elementary`
+ */
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__ __attribute__((unused))
+#endif
+
+typedef struct
+{
+   Evas_Object *win;
+   Evas_Object *edit_buffer;
+} App_Data;
+
+typedef struct
+{
+   Evas_Object *inwin;
+   Evas_Object *pager;
+   Evas_Object *grid;
+   Evas_Object *settings;
+
+   int size;
+   int vsize;
+   int width, height;
+
+   const char *emo;
+
+   App_Data *ad;
+} App_Inwin_Data;
+
+static void
+_edit_buffer_insert(Evas_Object *e, const char *text)
+{
+   elm_entry_entry_insert(e, text);
+   elm_object_focus(e);
+}
+
+static void
+_it_sel_cb(void *data, Evas_Object *obj __UNUSED__, void *event)
+{
+   App_Inwin_Data *aid = data;
+   Elm_Gengrid_Item *it = event;
+
+   aid->emo = elm_gengrid_item_data_get(it);
+
+   elm_pager_content_promote(aid->pager, aid->settings);
+}
+
+static char *
+_emo_label_get(void *data, Evas_Object *obj __UNUSED__, const char *part __UNUSED__)
+{
+   return strdup(data);
+}
+
+static Evas_Object *
+_emo_icon_get(void *data, Evas_Object *obj, const char *part)
+{
+   Evas_Object *o;
+
+   if (strcmp(part, "elm.swallow.icon"))
+     return NULL;
+   o = elm_layout_add(obj);
+   elm_layout_theme_set(o, "entry/emoticon", data, "default");
+   return o;
+}
+
+static void
+_emo_del(void *data, Evas_Object *obj __UNUSED__)
+{
+   free(data);
+}
+
+static Evas_Object *
+_page_grid_add(Evas_Object *parent, App_Inwin_Data *aid)
+{
+   Evas_Object *grid;
+   char *theme, *emo;
+   Eina_List *emos, *it;
+   static Elm_Gengrid_Item_Class it_class = {
+        "default",
+        {
+           _emo_label_get,
+           _emo_icon_get,
+           NULL,
+           _emo_del
+        }
+   };
+
+   theme = elm_theme_list_item_path_get("default", NULL);
+   if (!theme) return NULL;
+   emos = edje_file_collection_list(theme);
+   free(theme);
+   if (!emos) return NULL;
+
+   grid = elm_gengrid_add(parent);
+   elm_gengrid_item_size_set(grid, 64, 80);
+   evas_object_size_hint_weight_set(grid, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(grid, EVAS_HINT_FILL, EVAS_HINT_FILL);
+
+   EINA_LIST_FOREACH(emos, it, emo)
+     {
+        char name[512];
+
+        if (strncmp(emo, "elm/entry/emoticon/", 19))
+          continue;
+        sscanf(emo, "elm/entry/emoticon/%[^/]/default", name);
+        elm_gengrid_item_append(grid, &it_class, strdup(name), _it_sel_cb, aid);
+     }
+   edje_file_collection_list_free(emos);
+
+   return grid;
+}
+
+static void
+_btn_insert_cb(void *data, Evas_Object *obj __UNUSED__, void *event __UNUSED__)
+{
+   App_Inwin_Data *aid = data;
+   const char *size[] = {
+        "size",
+        "absize",
+        "relsize"
+   };
+   const char *vsize[] = {
+        "full",
+        "ascent"
+   };
+   char buf[512];
+
+   snprintf(buf, sizeof(buf), "<item %s=%dx%d vsize=%s href=emoticon/%s>"
+            "</item>", size[aid->size], aid->width, aid->height,
+            vsize[aid->vsize], aid->emo);
+   _edit_buffer_insert(aid->ad->edit_buffer, buf);
+
+   evas_object_del(aid->inwin);
+}
+
+static void
+_width_changed_cb(void *data, Evas_Object *obj, void *event __UNUSED__)
+{
+   App_Inwin_Data *aid = data;
+
+   aid->width = atoi(elm_object_text_get(obj));
+}
+
+static void
+_height_changed_cb(void *data, Evas_Object *obj, void *event __UNUSED__)
+{
+   App_Inwin_Data *aid = data;
+
+   aid->height = atoi(elm_object_text_get(obj));
+}
+
+static Evas_Object *
+_page_settings_add(Evas_Object *parent, App_Inwin_Data *aid)
+{
+   Evas_Object *box, *sizeopts, *box2, *sizebox, *vsizebox,
+               *rsize, *rabsize, *rrelsize, *rvfull, *rvascent,
+               *fwidth, *ewidth, *fheight, *eheight,
+               *binsert;
+   char buf[100];
+   static Elm_Entry_Filter_Accept_Set accept_set = {
+        .accepted = "0123456789",
+        .rejected = NULL
+   };
+   static Elm_Entry_Filter_Limit_Size limit_size = {
+        .max_char_count = 5,
+        .max_byte_count = 0
+   };
+
+   box = elm_box_add(parent);
+   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
+
+   sizeopts = elm_frame_add(parent);
+   elm_object_text_set(sizeopts, "Size");
+   evas_object_size_hint_weight_set(sizeopts, EVAS_HINT_EXPAND, 0.0);
+   evas_object_size_hint_align_set(sizeopts, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box, sizeopts);
+   evas_object_show(sizeopts);
+
+   box2 = elm_box_add(parent);
+   evas_object_size_hint_weight_set(box2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(box2, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_frame_content_set(sizeopts, box2);
+   evas_object_show(box2);
+
+   sizebox = elm_box_add(parent);
+   elm_box_horizontal_set(sizebox, EINA_TRUE);
+   evas_object_size_hint_weight_set(sizebox, EVAS_HINT_EXPAND,
+                                    EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(sizebox, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box2, sizebox);
+   evas_object_show(sizebox);
+
+   rsize = elm_radio_add(parent);
+   elm_object_text_set(rsize, "Scale adjusted (size)");
+   elm_radio_state_value_set(rsize, 0);
+   elm_radio_value_pointer_set(rsize, &aid->size);
+   elm_box_pack_end(sizebox, rsize);
+   evas_object_show(rsize);
+
+   rabsize = elm_radio_add(parent);
+   elm_object_text_set(rabsize, "Absolute size (absize)");
+   elm_radio_state_value_set(rabsize, 1);
+   elm_radio_value_pointer_set(rabsize, &aid->size);
+   elm_radio_group_add(rabsize, rsize);
+   elm_box_pack_end(sizebox, rabsize);
+   evas_object_show(rabsize);
+
+   rrelsize = elm_radio_add(parent);
+   elm_object_text_set(rrelsize, "Relative to line (relsize)");
+   elm_radio_state_value_set(rrelsize, 2);
+   elm_radio_value_pointer_set(rrelsize, &aid->size);
+   elm_radio_group_add(rrelsize, rsize);
+   elm_box_pack_end(sizebox, rrelsize);
+   evas_object_show(rrelsize);
+
+   vsizebox = elm_box_add(parent);
+   elm_box_horizontal_set(vsizebox, EINA_TRUE);
+   evas_object_size_hint_weight_set(vsizebox, EVAS_HINT_EXPAND,
+                                    EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(vsizebox, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box2, vsizebox);
+   evas_object_show(vsizebox);
+
+   rvfull = elm_radio_add(parent);
+   elm_object_text_set(rvfull, "Full height (vsize=full)");
+   elm_radio_state_value_set(rvfull, 0);
+   elm_radio_value_pointer_set(rvfull, &aid->vsize);
+   elm_box_pack_end(vsizebox, rvfull);
+   evas_object_show(rvfull);
+
+   rvascent = elm_radio_add(parent);
+   elm_object_text_set(rvascent, "Ascent only (vsize=ascent)");
+   elm_radio_state_value_set(rvascent, 1);
+   elm_radio_value_pointer_set(rvascent, &aid->vsize);
+   elm_radio_group_add(rvascent, rvfull);
+   elm_box_pack_end(vsizebox, rvascent);
+   evas_object_show(rvascent);
+
+   fwidth = elm_frame_add(parent);
+   elm_object_text_set(fwidth, "Width");
+   evas_object_size_hint_weight_set(fwidth, EVAS_HINT_EXPAND, 0.0);
+   evas_object_size_hint_align_set(fwidth, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box2, fwidth);
+   evas_object_show(fwidth);
+
+   snprintf(buf, sizeof(buf), "%d", aid->width);
+   ewidth = elm_entry_add(parent);
+   elm_entry_single_line_set(ewidth, EINA_TRUE);
+   elm_entry_text_filter_append(ewidth, elm_entry_filter_accept_set,
+                                &accept_set);
+   elm_entry_text_filter_append(ewidth, elm_entry_filter_limit_size,
+                                &limit_size);
+   elm_object_text_set(ewidth, buf);
+   evas_object_size_hint_weight_set(ewidth, EVAS_HINT_EXPAND, 0.0);
+   evas_object_size_hint_align_set(ewidth, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_frame_content_set(fwidth, ewidth);
+   evas_object_show(ewidth);
+
+   evas_object_smart_callback_add(ewidth, "changed", _width_changed_cb, aid);
+
+   fheight = elm_frame_add(parent);
+   elm_object_text_set(fheight, "Height");
+   evas_object_size_hint_weight_set(fheight, EVAS_HINT_EXPAND, 0.0);
+   evas_object_size_hint_align_set(fheight, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box2, fheight);
+   evas_object_show(fheight);
+
+   snprintf(buf, sizeof(buf), "%d", aid->height);
+   eheight = elm_entry_add(parent);
+   elm_entry_single_line_set(eheight, EINA_TRUE);
+   elm_entry_text_filter_append(eheight, elm_entry_filter_accept_set,
+                                &accept_set);
+   elm_entry_text_filter_append(eheight, elm_entry_filter_limit_size,
+                                &limit_size);
+   elm_object_text_set(eheight, buf);
+   evas_object_size_hint_weight_set(eheight, EVAS_HINT_EXPAND, 0.0);
+   evas_object_size_hint_align_set(eheight, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_frame_content_set(fheight, eheight);
+   evas_object_show(eheight);
+
+   evas_object_smart_callback_add(eheight, "changed", _height_changed_cb, aid);
+
+   binsert = elm_button_add(parent);
+   elm_object_text_set(binsert, "Insert");
+   elm_box_pack_end(box, binsert);
+   evas_object_show(binsert);
+
+   evas_object_smart_callback_add(binsert, "clicked", _btn_insert_cb, aid);
+
+   return box;
+}
+
+static void
+_insert_cancel_cb(void *data, Evas_Object *obj __UNUSED__, void *event __UNUSED__)
+{
+   App_Inwin_Data *aid = data;
+
+   evas_object_del(aid->inwin);
+}
+
+static void
+_inwin_del_cb(void *data, Evas *e __UNUSED__, Evas_Object *obj __UNUSED__, void *event __UNUSED__)
+{
+   free(data);
+}
+
+static void
+_image_insert_cb(void *data, Evas_Object *obj __UNUSED__, void *event __UNUSED__)
+{
+   App_Data *ad = data;
+   App_Inwin_Data *aid;
+   Evas_Object *inwin, *box, *box2, *pager, *o;
+
+   aid = calloc(1, sizeof(App_Inwin_Data));
+   if (!aid) return;
+
+   aid->ad = ad;
+   aid->size = 1;
+   aid->vsize = 1;
+   aid->width = 64;
+   aid->height = 64;
+
+   inwin = elm_win_inwin_add(ad->win);
+   evas_object_size_hint_weight_set(inwin, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(inwin, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   evas_object_show(inwin);
+
+   evas_object_event_callback_add(inwin, EVAS_CALLBACK_DEL, _inwin_del_cb,
+                                  aid);
+
+   box = elm_box_add(ad->win);
+   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_win_inwin_content_set(inwin, box);
+   evas_object_show(box);
+
+   pager = elm_pager_add(ad->win);
+   evas_object_size_hint_weight_set(pager, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(pager, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box, pager);
+   evas_object_show(pager);
+
+   o = _page_grid_add(ad->win, aid);
+   elm_pager_content_push(pager, o);
+   aid->grid = o;
+
+   o = _page_settings_add(ad->win, aid);
+   elm_pager_content_push(pager, o);
+   aid->settings = o;
+
+   elm_pager_content_promote(pager, aid->grid);
+
+   box2 = elm_box_add(ad->win);
+   elm_box_horizontal_set(box2, EINA_TRUE);
+   evas_object_size_hint_weight_set(box2, EVAS_HINT_EXPAND, 0.0);
+   evas_object_size_hint_align_set(box2, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box, box2);
+   evas_object_show(box2);
+
+   o = elm_button_add(ad->win);
+   elm_object_text_set(o, "Cancel");
+   evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(o, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box2, o);
+   evas_object_show(o);
+
+   evas_object_smart_callback_add(o, "clicked", _insert_cancel_cb, aid);
+
+   aid->inwin = inwin;
+   aid->pager = pager;
+}
+
+static void
+_format_change_cb(void *data, Evas_Object *obj, void *event __UNUSED__)
+{
+   App_Data *ad = data;
+   char fmt_open[5], fmt_close[6];
+   const char *sel;
+   int cursor;
+   char *s;
+   const char *ptr, *what;
+   Eina_Strbuf *buf = NULL;
+
+   sel = elm_object_text_get(obj);
+   snprintf(fmt_open, sizeof(fmt_open), "<%s>", sel);
+   snprintf(fmt_close, sizeof(fmt_close), "</%s>", sel);
+
+   buf = eina_strbuf_new();
+
+   cursor = elm_entry_cursor_pos_get(ad->edit_buffer);
+   elm_entry_cursor_begin_set(ad->edit_buffer);
+   elm_entry_cursor_selection_begin(ad->edit_buffer);
+   elm_entry_cursor_pos_set(ad->edit_buffer, cursor);
+   elm_entry_cursor_selection_end(ad->edit_buffer);
+   sel = elm_entry_selection_get(ad->edit_buffer);
+   if (!sel || !sel[0])
+     {
+        eina_strbuf_append(buf, fmt_open);
+        goto all_done;
+     }
+   what = fmt_open;
+   ptr = sel;
+   while ((s = strstr(ptr, what)))
+     {
+        ptr = s + strlen(what);
+        if (what == fmt_open) what = fmt_close;
+        else what = fmt_open;
+     }
+   eina_strbuf_append(buf, what);
+   if (what == fmt_close)
+     {
+        elm_entry_cursor_selection_begin(ad->edit_buffer);
+        elm_entry_cursor_end_set(ad->edit_buffer);
+        elm_entry_cursor_selection_end(ad->edit_buffer);
+        sel = elm_entry_selection_get(ad->edit_buffer);
+        if (sel)
+          {
+             Eina_Strbuf *buf2 = eina_strbuf_new();
+             eina_strbuf_append(buf2, sel);
+             eina_strbuf_replace_first(buf2, fmt_close, "");
+             elm_entry_entry_insert(ad->edit_buffer,
+                                    eina_strbuf_string_get(buf2));
+             eina_strbuf_free(buf2);
+          }
+     }
+   elm_entry_select_none(ad->edit_buffer);
+   elm_entry_cursor_pos_set(ad->edit_buffer, cursor);
+
+all_done:
+   _edit_buffer_insert(ad->edit_buffer, eina_strbuf_string_get(buf));
+   eina_strbuf_free(buf);
+}
+
+static void
+_autosave_change_cb(void *data, Evas_Object *obj, void *event __UNUSED__)
+{
+   App_Data *ad = data;
+   Eina_Bool state = elm_check_state_get(obj);
+
+   elm_entry_autosave_set(ad->edit_buffer, state);
+   if (state) elm_entry_file_save(ad->edit_buffer);
+}
+
+static void
+_edit_dblclick_cb(void *data __UNUSED__, Evas_Object *obj, void *event __UNUSED__)
+{
+   int current_cursor;
+
+   current_cursor = elm_entry_cursor_pos_get(obj);
+
+   while (elm_entry_cursor_prev(obj))
+     {
+        const char *content;
+        if (elm_entry_cursor_is_visible_format_get(obj))
+          break;
+        content = elm_entry_cursor_content_get(obj);
+        if (content && (content[0] == ' '))
+          break;
+     }
+
+   if (current_cursor == elm_entry_cursor_pos_get(obj))
+     return;
+
+   elm_entry_cursor_next(obj);
+   elm_entry_cursor_selection_begin(obj);
+   elm_entry_cursor_pos_set(obj, current_cursor);
+   while (elm_entry_cursor_next(obj))
+     {
+        const char *content;
+        if (elm_entry_cursor_is_visible_format_get(obj))
+          break;
+        content = elm_entry_cursor_content_get(obj);
+        if (content && (content[0] == ' '))
+          break;
+     }
+   elm_entry_cursor_selection_end(obj);
+}
+
+static void
+_edit_tplclick_cb(void *data __UNUSED__, Evas_Object *obj, void *event __UNUSED__)
+{
+   elm_entry_cursor_line_begin_set(obj);
+   elm_entry_cursor_selection_begin(obj);
+   elm_entry_cursor_line_end_set(obj);
+   elm_entry_cursor_selection_end(obj);
+}
+
+static void
+_win_del_cb(void *data __UNUSED__, Evas_Object *obj, void *event __UNUSED__)
+{
+   evas_object_del(obj);
+   elm_exit();
+}
+
+int
+elm_main(int argc __UNUSED__, char *argv[] __UNUSED__)
+{
+   Evas_Object *win, *bg, *box, *tb, *en, *o, *icon;
+   App_Data app;
+
+   memset(&app, 0, sizeof(app));
+
+   win = elm_win_add(NULL, "entry-example", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Emacs Lite");
+   evas_object_show(win);
+
+   bg = elm_bg_add(win);
+   evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   elm_win_resize_object_add(win, bg);
+   evas_object_show(bg);
+
+   box = elm_box_add(win);
+   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   elm_win_resize_object_add(win, box);
+   evas_object_show(box);
+
+   tb = elm_box_add(win);
+   elm_box_horizontal_set(tb, EINA_TRUE);
+   evas_object_size_hint_weight_set(tb, EVAS_HINT_EXPAND, 0.0);
+   evas_object_size_hint_weight_set(tb, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box, tb);
+   evas_object_show(tb);
+
+   o = elm_check_add(win);
+   elm_check_state_set(o, EINA_FALSE);
+   elm_object_text_set(o, "Autosave");
+   elm_box_pack_end(tb, o);
+   evas_object_show(o);
+
+   evas_object_smart_callback_add(o, "changed", _autosave_change_cb, &app);
+
+   o = elm_button_add(win);
+   elm_object_text_set(o, "b");
+   elm_box_pack_end(tb, o);
+   evas_object_show(o);
+
+   evas_object_smart_callback_add(o, "clicked", _format_change_cb, &app);
+
+   o = elm_button_add(win);
+   elm_object_text_set(o, "em");
+   elm_box_pack_end(tb, o);
+   evas_object_show(o);
+
+   evas_object_smart_callback_add(o, "clicked", _format_change_cb, &app);
+
+   o = elm_button_add(win);
+   elm_box_pack_end(tb, o);
+   evas_object_show(o);
+
+   icon = elm_layout_add(win);
+   elm_layout_theme_set(icon, "entry", "emoticon/haha", "default");
+   elm_button_icon_set(o, icon);
+
+   evas_object_smart_callback_add(o, "clicked", _image_insert_cb, &app);
+
+   en = elm_entry_add(win);
+   elm_entry_autosave_set(en, EINA_FALSE);
+   elm_entry_file_set(en, "/tmp/da_test.txt", ELM_TEXT_FORMAT_MARKUP_UTF8);
+   evas_object_size_hint_weight_set(en, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(en, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(box, en);
+   evas_object_show(en);
+
+   app.win = win;
+   app.edit_buffer = en;
+
+   evas_object_smart_callback_add(en, "clicked,double", _edit_dblclick_cb,
+                                  NULL);
+   evas_object_smart_callback_add(en, "clicked,triple", _edit_tplclick_cb,
+                                  NULL);
+
+   evas_object_smart_callback_add(win, "delete,request", _win_del_cb, &app);
+
+   elm_object_focus(app.edit_buffer);
+
+   evas_object_resize(win, 300, 780);
+
+   elm_run();
+
+   return 0;
+}
+ELM_MAIN();

legacy/elementary/src/lib/Elementary.h.in

@@ -6918,6 +6918,20 @@ extern "C" {
     * @li full: Items will be placed between the descent and ascent, or the
     * lowest point in the line and its highest.
     *
+    * The next image shows different configurations of items and how they
+    * are the previously mentioned options affect their sizes. In all cases,
+    * the green line indicates the ascent, blue for the baseline and red for
+    * the descent.
+    *
+    * @image html entry_item.png
+    * @image latex entry_item.eps width=\textwidth
+    *
+    * And another one to show how size differs from absize. In the first one,
+    * the scale value is set to 1.0, while the second one is using one of 2.0.
+    *
+    * @image html entry_item_scale.png
+    * @image latex entry_item_scale.eps width=\textwidth
+    *
     * After the size for an item is calculated, the entry will request an
     * object to place in its space. For this, the functions set with
     * elm_entry_item_provider_append() and related functions will be called
@@ -7017,6 +7031,10 @@ extern "C" {
     * parameter for the callback will be an #Elm_Entry_Anchor_Info.
     * @li "preedit,changed": The preedit string has changed.
     *
+    * @section entry-examples
+    *
+    * An overview of the Entry API can be seen in @ref entry_example_01
+    *
     * @{
     */
    /**
@@ -7320,24 +7338,41 @@ extern "C" {
     */
    EAPI void         elm_entry_cursor_selection_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
    /**
-    * TODO: fill this in
+    * Gets whether a format node exists at the current cursor position.
+    *
+    * A format node is anything that defines how the text is rendered. It can
+    * be a visible format node, such as a line break or a paragraph separator,
+    * or an invisible one, such as bold begin or end tag.
+    * This function returns whether any format node exists at the current
+    * cursor position.
     *
     * @param obj The entry object
-    * @return TODO: fill this in
+    * @return EINA_TRUE if the current cursor position contains a format node,
+    * EINA_FALSE otherwise.
+    *
+    * @see elm_entry_cursor_is_visible_format_get()
     */
    EAPI Eina_Bool    elm_entry_cursor_is_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
    /**
-    * This returns whether the cursor is visible.
+    * Gets if the current cursor position holds a visible format node.
     *
     * @param obj The entry object
-    * @return If true, the cursor is visible.
+    * @return EINA_TRUE if the current cursor is a visible format, EINA_FALSE
+    * if it's an invisible one or no format exists.
+    *
+    * @see elm_entry_cursor_is_format_get()
     */
    EAPI Eina_Bool    elm_entry_cursor_is_visible_format_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
    /**
-    * TODO: fill this in
+    * Gets the character pointed by the cursor at its current position.
+    *
+    * This function returns a string with the utf8 character stored at the
+    * current cursor position.
+    * Only the text is returned, any format that may exist will not be part
+    * of the return value.
     *
     * @param obj The entry object
-    * @return TODO: fill this in
+    * @return The text pointed by the cursors.
     */
    EAPI const char  *elm_entry_cursor_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
    /**
@@ -7358,6 +7393,9 @@ extern "C" {
    /**
     * Sets the cursor position in the entry to the given value
     *
+    * The value in @p pos is the index of the character position within the
+    * contents of the string as returned by elm_entry_cursor_pos_get().
+    *
     * @param obj The entry object
     * @param pos The position of the cursor
     */