combobox: add documentation and example

Summary:
Added Documentation for Combobox Widget
Signed-off-by: divyesh purohit <div.purohit@samsung.com>

Test Plan: execute make doc

Reviewers: shilpasingh, cedric

Subscribers: rajeshps, govi

Differential Revision: https://phab.enlightenment.org/D3539

Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>

8 files changed, 289 insertions, 7 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 953809c74..a4461b7c2 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -26,6 +26,7 @@ WGT_PREVIEW = \
 	clock:preview-00.png:widget_preview_clock:200:100 \
 	colorselector:preview-00.png:widget_preview_colorselector:320:300 \
 	conformant:preview-00.png:widget_preview_conformant:200:400 \
+	combobox:preview-00.png:widget_preview_combobox:300:300 \
 	ctxpopup:preview-00.png:widget_preview_ctxpopup:200:130 \
 	datetime:preview-00.png:widget_preview_datetime1:360:60 \
 	datetime:preview-01.png:widget_preview_datetime2:200:60 \
@@ -101,6 +102,7 @@ WGT_TREE = \
 	colorselector \
 	conformant \
 	container \
+	combobox \
 	ctxpopup \
 	datetime \
 	dayselector \
diff --git a/doc/examples.dox b/doc/examples.dox
index 3d425b1ad..8be745e75 100644
--- a/doc/examples.dox
+++ b/doc/examples.dox
@@ -29,6 +29,8 @@
  *
  * @ref calendar_example_06
  *
+ * @ref combobox_example_01
+ *
  * @ref spinner_example
  *
  * @ref slider_example
@@ -6810,3 +6812,69 @@
  * @example location_example_01.c
  * @example naviframe_example.c
  */
+
+/**
+ * @page tutorial_combobox Combobox example
+ * @dontinclude combobox_example_01.c
+ *
+ * In this example we will create a combobox with 1000 items.
+ *
+ * We will start with the normal creation of window stuff:
+ * @until show(bg)
+ *
+ * Next we will create a box.
+ * @until show(bx)
+ *
+ * And now we create our combobox and set some of it's properties. We set @p win
+ * as its parent, set a text "A Simple List" (which acts as a placeholder).
+ * We pack the combobox in box.
+ * @until show(combobox)
+ *
+ * Next we create a new genlist item class and sets its properties:
+ * item_style as deafult , callback for text_get and set others as NULL.
+ * @until itc->func.del = NULL;
+
+ * Next we will append 1000 items to the combobox, this is similar to appending
+ * items to the genlist
+ * @until ));
+ *
+ * We also set a pair of callbacks to be called whenever any item is selected or
+ * pressed.
+ * when the combobox is activated, dismissed, expanded :
+ * @until _combobox_item_pressed_cb, NULL);
+ *
+ * And then ask that our combobox be shown and run the main loop:
+ * @until ELM_MAIN
+ *
+ * We now have the callback for setting text in the each item of genlist:
+ * @until }
+ *
+ * Next we have the callback which is called when the combobox is clicked:
+ * @until }
+ *
+ * Next we have the callback that is called whenever an item is selected and
+ * text of that item is set on combobox:
+ * @until }
+
+ * Next we have the callback that is called whenever an item is pressed and
+ * text of that item is set on combobox and the hover is closed:
+ * @until }
+ *
+ * Next we have the callback that is called whenever an item is double-clicked
+ * or pressing (enter|return|spacebar) on an item also the text(event_info) of that item is set on
+ * combobox and the hover is closed:
+ * @until }
+
+ * And the callback that is called when the hover,genlist are closed.
+ * @until }
+ *
+ * And finally the callback is called when hover,genlist are shown.
+ * @until }
+ *
+ * Our example will initially look like this:
+ *
+ * @image html screenshots/combobox_example_01.png
+ * @image latex screenshots/combobox_example_01.eps width=\textwidth
+ *
+ * @example combobox_example_01.c
+ */
\ No newline at end of file
diff --git a/doc/index.doxy b/doc/index.doxy
index 8a35ddb84..f20bb0a2c 100644
--- a/doc/index.doxy
+++ b/doc/index.doxy
@@ -77,6 +77,10 @@
  *
  * @image html img/widget/ctxpopup/preview-00.png
  * @image latex img/widget/ctxpopup/preview-00.eps
+ * @li @ref Combobox
+ *
+ * @image html img/widget/combobox/preview-00.png
+ * @image latex img/widget/combobox/preview-00.eps
  * @li @ref Datetime
  *
  * @image html img/widget/datetime/preview-00.png
diff --git a/doc/widgets/Makefile.am b/doc/widgets/Makefile.am
index 5cc58f39e..df26c7572 100644
--- a/doc/widgets/Makefile.am
+++ b/doc/widgets/Makefile.am
@@ -37,6 +37,7 @@ widget_preview_check2 \
 widget_preview_check3 \
 widget_preview_clock \
 widget_preview_colorselector \
+widget_preview_combobox \
 widget_preview_conformant \
 widget_preview_ctxpopup \
 widget_preview_datetime1 \
@@ -118,6 +119,7 @@ EXTRA_DIST = \
 	widget_preview_clock.c \
 	widget_preview_colorselector.c \
 	widget_preview_conformant.c \
+	widget_preview_combobox.c \
 	widget_preview_slider.c \
 	widget_preview_panes.c \
 	widget_preview_toolbar.c \
diff --git a/doc/widgets/widget_preview_combobox.c b/doc/widgets/widget_preview_combobox.c
new file mode 100644
index 000000000..2cde37a5d
--- /dev/null
+++ b/doc/widgets/widget_preview_combobox.c
@@ -0,0 +1,48 @@
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define EINA_UNUSED
+#endif
+
+#include <Elementary.h>
+
+static char *
+gl_text_get(void *data, Evas_Object *obj EINA_UNUSED, const char *part EINA_UNUSED)
+{
+   char buf[256];
+   snprintf(buf, sizeof(buf), "Item # %i", (int)(uintptr_t)data);
+   return strdup(buf);
+}
+
+unsigned char _func(void *data);
+
+#include "widget_preview_tmpl_head.c"
+
+Evas_Object *combobox = elm_combobox_add(win);
+evas_object_size_hint_weight_set(combobox, EVAS_HINT_EXPAND, 0);
+evas_object_size_hint_align_set(combobox, EVAS_HINT_FILL, 0);
+elm_object_part_text_set(combobox, "guide", "A long list");
+evas_object_resize(combobox, 300, 28);
+evas_object_show(combobox);
+
+Elm_Genlist_Item_Class *itc;
+itc = elm_genlist_item_class_new();
+itc->item_style = "default";
+itc->func.text_get = gl_text_get;
+itc->func.content_get = NULL;
+itc->func.state_get = NULL;
+itc->func.filter_get = NULL;
+itc->func.del = NULL;
+for (int i = 0; i < 1000; i++)
+   elm_genlist_item_append(combobox, itc, (void *)(uintptr_t)i,
+                           NULL, ELM_GENLIST_ITEM_NONE, NULL,
+                           (void*)(uintptr_t)(i * 10));
+ecore_timer_add(0.05, _func, combobox);
+
+#include "widget_preview_tmpl_foot.c"
+
+unsigned char _func(void *data)
+{
+   elm_combobox_hover_begin(data);
+   return 0;
+}
diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index 112dbeb0e..24f1dd288 100644
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -52,6 +52,7 @@ codegen_example.edc \
 colorselector_example_01.c \
 conformant_example_01.c \
 conformant_example_02.c \
+combobox_example_01.c \
 ctxpopup_example_01.c \
 datetime_example.c \
 dayselector_example.c \
@@ -237,6 +238,7 @@ codegen_example \
 colorselector_example_01 \
 conformant_example_01 \
 conformant_example_02 \
+combobox_example_01 \
 ctxpopup_example_01 \
 datetime_example \
 dayselector_example \
@@ -419,6 +421,7 @@ label_example_01:label_example_01.png:0.0 \
 theme_example_01:theme_example_01.png:0.0 \
 conformant_example_01:conformant_example_01.png:0.0 \
 conformant_example_02:conformant_example_02.png:0.0 \
+combobox_example_01:combobox_example_01.png:0.0 \
 calendar_example_01:calendar_example_01.png:0.0 \
 calendar_example_02:calendar_example_02.png:0.0 \
 calendar_example_03:calendar_example_03.png:0.0 \
diff --git a/src/examples/combobox_example_01.c b/src/examples/combobox_example_01.c
new file mode 100644
index 000000000..30121ba16
--- /dev/null
+++ b/src/examples/combobox_example_01.c
@@ -0,0 +1,155 @@
+//Compile with:
+//gcc -o combobox_example_01 combobox_example_01.c -g `pkg-config --cflags --libs elementary`
+
+#include <Elementary.h>
+
+static void
+_combobox_clicked_cb(void *data EINA_UNUSED, Evas_Object *obj EINA_UNUSED,
+                     void *event_info EINA_UNUSED)
+{
+   printf("Hover button is clicked and 'clicked' callback is called.\n");
+}
+
+static void
+_combobox_selected_cb(void *data EINA_UNUSED, Evas_Object *obj EINA_UNUSED,
+                      void *event_info)
+{
+   const char *txt = elm_object_item_text_get(event_info);
+   printf("'selected' callback is called. (selected item : %s)\n", txt);
+}
+
+static void
+_combobox_dismissed_cb(void *data EINA_UNUSED, Evas_Object *obj EINA_UNUSED,
+                       void *event_info EINA_UNUSED)
+{
+   printf("'dismissed' callback is called.\n");
+}
+
+static void
+_combobox_expanded_cb(void *data EINA_UNUSED, Evas_Object *obj EINA_UNUSED,
+                       void *event_info EINA_UNUSED)
+{
+   printf("'expanded' callback is called.\n");
+}
+
+static void
+_combobox_item_pressed_cb(void *data EINA_UNUSED, Evas_Object *obj,
+                      void *event_info)
+{
+   const char *txt = elm_object_item_text_get(event_info);
+   printf("'item,pressed' callback is called. (selected item : %s)\n", txt);
+   elm_object_text_set(obj, txt);
+   elm_combobox_hover_end(obj);
+}
+
+static char *
+gl_text_get(void *data, Evas_Object *obj EINA_UNUSED, const char *part EINA_UNUSED)
+{
+   char buf[256];
+   snprintf(buf, sizeof(buf), "Item # %i", (int)(uintptr_t)data);
+   return strdup(buf);
+}
+
+static Evas_Object *gl_content_get(void *data EINA_UNUSED, Evas_Object *obj,
+                                    const char *part)
+{
+   char buf[PATH_MAX];
+   Evas_Object *ic = elm_icon_add(obj);
+   if (!strcmp(part, "elm.swallow.end"))
+     snprintf(buf, sizeof(buf), "%s/images/bubble.png", elm_app_data_dir_get());
+   else
+     snprintf(buf, sizeof(buf), "%s/images/logo_small.png", elm_app_data_dir_get());
+   elm_image_file_set(ic, buf, NULL);
+   evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
+   return ic;
+}
+
+static Eina_Bool gl_state_get(void *data EINA_UNUSED,
+                               Evas_Object *obj EINA_UNUSED,
+                               const char *part EINA_UNUSED)
+{
+   return EINA_FALSE;
+}
+
+static Eina_Bool
+gl_filter_get(void *data, Evas_Object *obj EINA_UNUSED, void *key)
+{
+   // if the key is empty/NULL, return true for item
+   if (!strlen((char *)key)) return EINA_TRUE;
+   char buf[256];
+   snprintf(buf, sizeof(buf), "Item # %i", (int)(uintptr_t)data);
+   if (strcasestr(buf, (char *)key))
+     return EINA_TRUE;
+   // Default case should return false (item fails filter hence will be hidden)
+   return EINA_FALSE;
+}
+
+static void
+_gl_filter_finished_cb(void *data EINA_UNUSED,
+                       Evas_Object *obj EINA_UNUSED,
+                       void *event_info EINA_UNUSED)
+{
+   printf("Filter finished\n");
+}
+
+
+EAPI_MAIN int
+elm_main(int argc EINA_UNUSED, char **argv)
+{
+   Evas_Object *win, *bg;
+
+   elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
+
+   win = elm_win_util_standard_add("combobox", "Combobox");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   bg = elm_bg_add(win);
+   evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(bg, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_win_resize_object_add(win, bg);
+   evas_object_show(bg);
+
+   Evas_Object *bx = elm_box_add(win);
+   evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   elm_win_resize_object_add(win, bx);
+   evas_object_show(bx);
+
+   Evas_Object *combobox = elm_combobox_add(win);
+   evas_object_size_hint_weight_set(combobox, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(combobox, EVAS_HINT_FILL, 0);
+   elm_object_part_text_set(combobox, "guide", "A Simple list");
+   elm_box_pack_end(bx, combobox);
+   evas_object_show(combobox);
+
+   Elm_Genlist_Item_Class *itc;
+   itc = elm_genlist_item_class_new();
+   itc->item_style = "default";
+   itc->func.text_get = gl_text_get;
+   itc->func.content_get = NULL;
+   itc->func.state_get = gl_state_get;
+   itc->func.filter_get = gl_filter_get;
+   itc->func.del = NULL;
+
+   for (int i = 0; i < 1000; i++)
+     elm_genlist_item_append(combobox, itc, (void *)(uintptr_t)i,
+                             NULL, ELM_GENLIST_ITEM_NONE, NULL,
+                             (void*)(uintptr_t)(i * 10));
+   evas_object_smart_callback_add(combobox, "clicked",
+                                  _combobox_clicked_cb, NULL);
+   evas_object_smart_callback_add(combobox, "selected",
+                                  _combobox_selected_cb, NULL);
+   evas_object_smart_callback_add(combobox, "dismissed",
+                                  _combobox_dismissed_cb, NULL);
+   evas_object_smart_callback_add(combobox, "expanded",
+                                  _combobox_expanded_cb, NULL);
+   evas_object_smart_callback_add(combobox, "item,pressed",
+                                  _combobox_item_pressed_cb, NULL);
+
+   evas_object_resize(win, 300, 500);
+   evas_object_show(win);
+
+   elm_run();
+
+   return 0;
+}
+ELM_MAIN()
\ No newline at end of file
diff --git a/src/lib/elc_combobox.h b/src/lib/elc_combobox.h
index 80e1ae42f..8237b87ef 100644
--- a/src/lib/elc_combobox.h
+++ b/src/lib/elc_combobox.h
@@ -24,15 +24,15 @@
  *   is the selected item
  * - @c "dismissed" - the hover is dismissed
  * - @c "expanded" - This is called on clicking combobox and elm_combobox_hover_begin().
- * - @c "language,changed" - the program's language changed (since 1.9)
- * - @c "item,focused" - When the combobox item has received focus. (since 1.10)
- * - @c "item,unfocused" - When the combobox item has lost focus. (since 1.10)
+ * - @c "language,changed" - the program's language changed.
+ * - @c "item,pressed" - When the combobox item is pressed.
+ * - @c "filter,done" - When the combobox completes the filter process.
  *
- * Default content parts of the combobox widget that you can use for are:
- * @li "icon" - An icon of the combobox
+ * Default content parts of the combobox widget that you can use are the
+ * the same that you use with the @ref Button
  *
- * Default text parts of the combobox widget that you can use for are:
- * @li "default" - A label of the combobox
+ * Default text parts of the combobox widget that you can use are the
+ * the same that you use with the @ref Entry
  *
  * Supported elm_object common APIs.
  * @li @ref elm_object_disabled_set