kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[elementary] Documentation for the index widget. 

SVN revision: 61533
This commit is contained in:
Gustavo Lima Chaves 2011-07-20 16:28:12 +00:00
parent c3cbe7e639
commit c2c47801f7
17 changed files with 41616 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
legacy/elementary/doc/Makefile.am
View File

@ -41,7 +41,8 @@ widget_preview_bubble3 \
widget_preview_fileselector_button1 \
widget_preview_fileselector_button2 \
widget_preview_fileselector_button3 \
widget_preview_colorselector
widget_preview_colorselector \
widget_preview_index
LDADD = $(top_builddir)/src/lib/libelementary.la @ELEMENTARY_EWEATHER_LIBS@ @ELEMENTARY_EDBUS_LIBS@ @ELEMENTARY_EFREET_LIBS@ @ELEMENTARY_LIBS@ @EIO_LIBS@ @my_libs@
@ -59,7 +60,8 @@ WGT_PREVIEW = \
bubble:preview-00.png:widget_preview_bubble1:160:50 \
bubble:preview-01.png:widget_preview_bubble2:160:50 \
bubble:preview-02.png:widget_preview_bubble3:160:50 \
colorselector:preview-00.png:widget_preview_colorselector:160:200
colorselector:preview-00.png:widget_preview_colorselector:160:200 \
index:preview-00.png:widget_preview_index:300:500
widget-preview:
@mkdir -p $(top_builddir)/doc/html/img/widget

169
legacy/elementary/doc/examples.dox
View File

@ -44,6 +44,10 @@
* @ref fileselector_button_example
*
* @ref fileselector_entry_example
*
* @ref index_example_01
*
* @ref index_example_02
*/
/**
@ -2361,6 +2365,159 @@
* @example conformant_example_02.c
*/
/**
* @page index_example_01 Index widget example 1
*
* This code places an Elementary index widget on a window, which also
* has a very long list of arbitrary strings on it. The list is
* sorted alphabetically and the index will be used to index the first
* items of each set of strings beginning with an alphabet letter.
*
* Below the list are some buttons, which are there just to exercise
* some index widget's API.
*
* Here's how we instantiate it:
* @dontinclude index_example_01.c
* @skip elm_list_add
* @until evas_object_show(d.index)
* where we're showing also the list being created. Note that we issue
* elm_win_resize_object_add() on the index, so that it's set to have
* the whole window as its container. Then, we have to populate both
* list and index widgets:
* @dontinclude index_example_01.c
* @skip for (i = 0; i < (sizeof(dict) / sizeof(dict[0])); i++)
* @until }
* @until }
*
* The strings populating the list come from a file
* @dontinclude index_example_01.c
* @skip static const char *dict
* @until }
*
* We use the @c curr char variable to hold the last initial letter
* seen on that ordered list of strings, so that we're able to have an
* index item pointing to each list item starting a new letter
* "section". Note that our index item data pointers will be the list
* item handles. We are also setting a callback function to index
* items deletion events:
* @dontinclude index_example_01.c
* @skip static void
* @until }
*
* There, we show you that the @c event_info pointer will contain the
* item in question's data, i.e., a given list item's pointer. Because
* item data is also returned in the @c data argument on
* @c Evas_Smart_Cb functions, those two pointers must have the same
* values. On this deletion callback, we're deleting the referred list
* item too, just to exemplify that anything could be done there.
*
* Next, we hook to two smart events of the index object:
* @dontinclude index_example_01.c
* @skip smart_callback_add(d.index
* @until _index_selected
* @dontinclude index_example_01.c
* @skip "delay,changed" hook
* @until }
* @until }
*
* Check that, whenever one holds the mouse pressed over a given index
* letter for some time, the list beneath it will roll down to the
* item pointed to by that index item. When one releases the mouse
* button, the second callback takes place. There, we check that the
* reported item data, on @c event_info, is the same reported by
* elm_index_item_selected_get(), which gives the last selection's
* data on the index widget.
*
* The first of the three buttons that follow will call
* elm_index_active_set(), thus showing the index automatically for
* you, if it's not already visible, what is checked with
* elm_index_active_get(). The second button will exercise @b deletion
* of index item objects, by the following code:
* @dontinclude index_example_01.c
* @skip delete an index item
* @until }
*
* It will get the last index item selected's data and find the
* respective #Elm_Index_Item handle with elm_index_item_find(). We
* need the latter to query the indexing letter string from, with
* elm_index_item_letter_get(). Next, comes the delition, itself,
* which will also trigger the @c _index_item_del callback function,
* as said above.
*
* The third button, finally, will exercise elm_index_item_clear(),
* which will delete @b all of the index's items.
*
* This is how the example program's window looks like with the index
* widget hidden:
* @image html screenshots/index_example_00.png
* @image latex screenshots/index_example_00.eps
*
* When it's shown, it's like the following figure:
* @image html screenshots/index_example_01.png
* @image latex screenshots/index_example_01.eps
*
* See the full @ref index_example_01_c "source code" for
* this example.
*
* @example index_example_01.c
*/
/**
* @page index_example_02 Index widget example 2
*
* This code places an Elementary index widget on a window, indexing
* grid items. The items are placed so that their labels @b don't
* follow any order, but the index itself is ordered (through
* elm_index_item_sorted_insert()). This is a complement to to @ref
* index_example_01 "the first example on indexes".
*
* Here's the list of item labels to be used on the grid (in that
* order):
* @dontinclude index_example_02.c
* @skip static const char *items
* @until };
*
* In the interesting part of the code, here, we first instantiate the
* grid (more on grids on their examples) and, after creating our
* index, for each grid item we also create an index one to reference
* it:
* @dontinclude index_example_02.c
* @skip grid = elm_gengrid_add
* @until }
* @until smart_callback_add
*
* The order in which they'll appear in the index, though, is @b
* alphabetical, becase of elm_index_item_sorted_insert() usage
* together with the comparing function, where we take the letters of
* each index item to base our ordering on. The parameters on
* @c _index_cmp have to be declared as void pointers because of the
* @c Eina_Compare_Cb prototype requisition, but in this case we know
* they'll be #Elm_Index_Item's:
* @dontinclude index_example_02.c
* @skip ordering alphabetically
* @until }
*
* The last interesting bit is the callback in the @c "delay,changed"
* smart event, which will bring the given grid item to the grid's
* visible area:
* @dontinclude index_example_02.c
* @skip static void
* @until }
*
* Note how the grid will move kind of randomly while you move your
* mouse pointer held over the index from top to bottom -- that's
* because of the the random order the items have in the grid itself.
*
* This is how the example program's window looks like:
* @image html screenshots/index_example_03.png
* @image latex screenshots/index_example_03.eps
*
* See the full @ref index_example_c "source code" for
* this example.
*
* @example index_example_02.c
*/
/**
* @page bg_example_01_c bg_example_01.c
* @include bg_example_01.c
@ -2438,3 +2595,15 @@
* @include fileselector_entry_example.c
* @example fileselector_entry_example.c
*/
/**
* @page index_example_01_c Index example
* @include index_example_01.c
* @example index_example_01.c
*/
/**
* @page index_example_02_c Index example
* @include index_example_02.c
* @example index_example_02.c
*/

15048
legacy/elementary/doc/img/screenshots/index_example_00.eps Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
legacy/elementary/doc/img/screenshots/index_example_00.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

15048
legacy/elementary/doc/img/screenshots/index_example_01.eps Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
legacy/elementary/doc/img/screenshots/index_example_01.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 68 KiB

7663
legacy/elementary/doc/img/screenshots/index_example_03.eps Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
legacy/elementary/doc/img/screenshots/index_example_03.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

57
legacy/elementary/doc/widget_preview_index.c Normal file
View File

@ -0,0 +1,57 @@
#include "widget_preview_tmpl_head.c"
static const char *dict[] = \
{
"awkward",
"businessman",
"cylinder",
"dying",
"extremophile",
"futhark",
"guttural",
"hypocrites",
"issuing",
"just",
"knows",
"lying",
"mystery",
"nutrients",
"oxymoron",
"putting",
"quizzes",
"running",
"systematically",
"tyranny",
"usually",
"vacuum",
"want",
"xenophobia",
"yacht",
"zebra"
};
Evas_Object *o = elm_list_add(win);
evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_win_resize_object_add(win, o);
evas_object_show(o);
Evas_Object *id = elm_index_add(win);
elm_win_resize_object_add(win, id);
evas_object_size_hint_weight_set(id, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_win_resize_object_add(win, id);
evas_object_show(id);
unsigned int i;
for (i = 0; i < (sizeof(dict) / sizeof(dict[0])); i++)
{
char buf[32];
Elm_List_Item *it;
it = elm_list_item_append(o, dict[i], NULL, NULL, NULL, NULL);
snprintf(buf, sizeof(buf), "%c", dict[i][0]);
elm_index_item_append(id, buf, it);
}
elm_index_active_set(id, EINA_TRUE);
#include "widget_preview_tmpl_foot.c"

12
legacy/elementary/src/examples/Makefile.am
View File

@ -69,6 +69,8 @@ SRCS = \
fileselector_entry_example.c \
diskselector_example_01.c \
diskselector_example_02.c \
index_example_01.c \
index_example_02.c \
theme_example.edc
pkglib_PROGRAMS =
@ -77,7 +79,8 @@ pkglib_PROGRAMS =
$(EDJE_CC) $(EDJE_FLAGS) $< $@
if EFL_INSTALL_EXAMPLES
files_DATA += $(SRCS)
files_DATA += $(SRCS) \
dict.txt
endif
if EFL_BUILD_EXAMPLES
@ -127,7 +130,9 @@ pkglib_PROGRAMS += \
flipselector_example \
fileselector_example \
fileselector_button_example \
fileselector_entry_example
fileselector_entry_example \
index_example_01 \
index_example_02
# This variable will hold the list of screenshots that will be made
# by "make screenshots". Each item in the list is of the form:
@ -161,7 +166,8 @@ SCREENSHOTS = \
diskselector_example_02:diskselector_example_02.png:0.2 \
icon_example_01:icon_example_01.png:0.0 \
flipselector_example:flipselector_example.png:0.0 \
fileselector_example:fileselector_example.png:0.0
fileselector_example:fileselector_example.png:0.0 \
index_example_02:index_example_03.png:0.3
screenshots: all
@mkdir -p $(top_srcdir)/doc/img/screenshots

2
legacy/elementary/src/examples/clock_example.c
View File

@ -24,7 +24,7 @@ _on_done(void *data __UNUSED__,
elm_exit();
}
EAPI int
int
elm_main(int argc __UNUSED__, char **argv __UNUSED__)
{
Evas_Object *win, *bg, *bx, *ck;

2913
legacy/elementary/src/examples/dict.txt Normal file
View File

File diff suppressed because it is too large Load Diff

2
legacy/elementary/src/examples/fileselector_entry_example.c
View File

@ -24,7 +24,7 @@ _on_done(void *data __UNUSED__,
elm_exit();
}
/* hook on the sole smart callback */
/* hook on the file,chosen smart callback */
static void
_file_chosen(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,

213
legacy/elementary/src/examples/index_example_01.c Normal file
View File

@ -0,0 +1,213 @@
/**
* Simple Elementary's <b>index widget</b> example, illustrating its
* usage and API.
*
* See stdout/stderr for output. Compile with:
*
* @verbatim
* gcc -g `pkg-config --cflags --libs elementary` index_example.c -o index_example
* @endverbatim
*/
#include <Elementary.h>
#ifdef HAVE_CONFIG_H
# include "elementary_config.h"
#else
# define __UNUSED__
#endif
struct example_data
{
Evas_Object *list, *index;
};
struct example_data d = {NULL, NULL};
static const char *dict[] = \
{
#include "dict.txt"
};
static void
_index_item_del(void *data,
Evas_Object *obj __UNUSED__,
void *event_info)
{
fprintf(stdout, "Deleting associated list node (%s). Comparing index "
"item data reported via callback with the one returned by "
"index's API on items: %s.\n",
elm_list_item_label_get(data),
data == elm_index_item_data_get(event_info) ? "OK" :
"FAIL, something went wrong");
elm_list_item_del(data);
}
/* delete an index item */
static void
_item_del(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
void *event_info __UNUSED__)
{
Elm_Index_Item *it;
Elm_List_Item *lit = elm_index_item_selected_get(d.index, 0);
it = elm_index_item_find(d.index, lit);
if (!it) return;
fprintf(stdout, "Deleting last selected index item, which had letter"
" %s (pointing to %s)\n", elm_index_item_letter_get(it),
elm_list_item_label_get(lit));
elm_index_item_del(d.index, lit);
}
static void
_item_del_all(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
void *event_info __UNUSED__)
{
elm_index_item_clear(d.index);
}
static void
_active_set(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
void *event_info __UNUSED__)
{
elm_index_active_set(d.index, !elm_index_active_get(d.index));
fprintf(stdout, "Toggling index programmatically.\n");
}
/* "delay,changed" hook */
static void
_index_changed(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
void *event_info)
{
elm_list_item_bring_in(event_info);
}
static void
_index_selected(void *data __UNUSED__,
Evas_Object *obj,
void *event_info)
{
Elm_List_Item *it = event_info;
fprintf(stdout, "New index item selected. Comparing item reported"
" via callback with the selection returned by the API: "
"%s.\n", it == elm_index_item_selected_get(obj, 0) ? "OK" :
"FAIL, something went wrong");
}
static void
_on_done(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
void *event_info __UNUSED__)
{
elm_exit();
}
int
elm_main(int argc __UNUSED__,
char **argv __UNUSED__)
{
Evas_Object *win, *bg, *hbox, *vbox, *bt, *sep;
Elm_List_Item *it;
unsigned int i;
char curr = 0;
win = elm_win_add(NULL, "index", ELM_WIN_BASIC);
elm_win_title_set(win, "Index Example");
evas_object_smart_callback_add(win, "delete,request", _on_done, NULL);
bg = elm_bg_add(win);
elm_win_resize_object_add(win, bg);
evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_show(bg);
vbox = elm_box_add(win);
elm_win_resize_object_add(win, vbox);
evas_object_size_hint_weight_set(vbox, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_show(vbox);
d.list = elm_list_add(win);
evas_object_size_hint_weight_set(d.list, EVAS_HINT_EXPAND,
EVAS_HINT_EXPAND);
evas_object_size_hint_align_set(d.list, EVAS_HINT_FILL, EVAS_HINT_FILL);
evas_object_show(d.list);
elm_box_pack_end(vbox, d.list);
d.index = elm_index_add(win);
elm_win_resize_object_add(win, d.index);
evas_object_size_hint_weight_set(d.index, EVAS_HINT_EXPAND,
EVAS_HINT_EXPAND);
evas_object_size_hint_align_set(d.list, EVAS_HINT_FILL, EVAS_HINT_FILL);
evas_object_show(d.index);
for (i = 0; i < (sizeof(dict) / sizeof(dict[0])); i++)
{
it = elm_list_item_append(d.list, dict[i], NULL, NULL, NULL, NULL);
if (curr != dict[i][0])
{
Elm_Index_Item *index_it;
char buf[32];
curr = dict[i][0];
/* indexing by first letters */
snprintf(buf, sizeof(buf), "%c", curr);
elm_index_item_append(d.index, buf, it);
index_it = elm_index_item_find(d.index, it);
elm_index_item_del_cb_set(index_it, _index_item_del);
}
}
evas_object_smart_callback_add(d.index, "delay,changed", _index_changed,
NULL);
evas_object_smart_callback_add(d.index, "selected", _index_selected, NULL);
/* attribute setting knobs */
sep = elm_separator_add(win);
elm_separator_horizontal_set(sep, EINA_TRUE);
elm_box_pack_end(vbox, sep);
evas_object_show(sep);
hbox = elm_box_add(win);
elm_box_horizontal_set(hbox, EINA_TRUE);
evas_object_size_hint_weight_set(hbox, EVAS_HINT_EXPAND, 0);
evas_object_size_hint_fill_set(hbox, EVAS_HINT_FILL, EVAS_HINT_FILL);
elm_box_pack_end(vbox, hbox);
evas_object_show(hbox);
bt = elm_button_add(win);
elm_object_text_set(bt, "bring in index");
evas_object_smart_callback_add(bt, "clicked", _active_set, NULL);
elm_box_pack_end(hbox, bt);
evas_object_show(bt);
bt = elm_button_add(win);
elm_object_text_set(bt, "delete last selected item");
evas_object_smart_callback_add(bt, "clicked", _item_del, NULL);
elm_box_pack_end(hbox, bt);
evas_object_show(bt);
bt = elm_button_add(win);
elm_object_text_set(bt, "delete all items");
evas_object_smart_callback_add(bt, "clicked", _item_del_all, NULL);
elm_box_pack_end(hbox, bt);
evas_object_show(bt);
evas_object_resize(win, 320, 600);
evas_object_show(win);
elm_run();
return 0;
}
ELM_MAIN()

155
legacy/elementary/src/examples/index_example_02.c Normal file
View File

@ -0,0 +1,155 @@
/**
* Simple Elementary's <b>index widget</b> example, illustrating its
* usage and API -- now with sorted insertions.
*
* See stdout/stderr for output. Compile with:
*
* @verbatim
* gcc -g `pkg-config --cflags --libs elementary` index_example.c -o index_example
* @endverbatim
*/
#include <Elementary.h>
#ifdef HAVE_CONFIG_H
# include "elementary_config.h"
#else
# define __UNUSED__
# define PACKAGE_DATA_DIR "../../data"
#endif
static const char *items[] = \
{
"Judith",
"Paulina",
"Cathy",
"Vendella",
"Naomi",
"Ashley",
"Stacey",
"Gail"
};
static void
_index_changed(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
void *event_info)
{
elm_gengrid_item_bring_in(event_info);
}
static void
_on_done(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
void *event_info __UNUSED__)
{
elm_exit();
}
static char *
_grid_label_get(void *data,
Evas_Object *obj __UNUSED__,
const char *part __UNUSED__)
{
int idx = (int)data;
return strdup(items[idx]);
}
Evas_Object *
_grid_icon_get(void *data __UNUSED__,
Evas_Object *obj,
const char *part)
{
if (!strcmp(part, "elm.swallow.icon"))
{
char buf[PATH_MAX];
snprintf(buf, sizeof(buf), "%s/images/%s", PACKAGE_DATA_DIR,
"sky_01.jpg");
Evas_Object *icon = elm_bg_add(obj);
elm_bg_file_set(icon, buf, NULL);
evas_object_size_hint_aspect_set(icon, EVAS_ASPECT_CONTROL_VERTICAL, 1,
1);
evas_object_show(icon);
return icon;
}
return NULL;
}
/* ordering alphabetically */
static int
_index_icmp(const void *data1,
const void *data2)
{
const char *label1, *label2;
const Elm_Index_Item *it1 = data1;
const Elm_Index_Item *it2 = data2;
label1 = elm_index_item_letter_get(it1);
label2 = elm_index_item_letter_get(it2);
return strcasecmp(label1, label2);
}
int
elm_main(int argc __UNUSED__,
char **argv __UNUSED__)
{
Evas_Object *win, *bg, *grid, *index;
Elm_Gengrid_Item *it;
unsigned int i;
Elm_Gengrid_Item_Class gic;
win = elm_win_add(NULL, "index", ELM_WIN_BASIC);
elm_win_title_set(win, "Index Example");
evas_object_smart_callback_add(win, "delete,request", _on_done, NULL);
bg = elm_bg_add(win);
elm_win_resize_object_add(win, bg);
evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_show(bg);
grid = elm_gengrid_add(win);
elm_gengrid_item_size_set(grid, 150, 150);
gic.item_style = "default";
gic.func.label_get = _grid_label_get;
gic.func.icon_get = _grid_icon_get;
gic.func.state_get = NULL;
gic.func.del = NULL;
evas_object_size_hint_weight_set(grid, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_win_resize_object_add(win, grid);
evas_object_show(grid);
index = elm_index_add(win);
evas_object_size_hint_weight_set(index, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_win_resize_object_add(win, index);
evas_object_show(index);
for (i = 0; i < (sizeof(items) / sizeof(items[0])); i++)
{
char buf[32];
it = elm_gengrid_item_append(grid, &gic, (void *)i, NULL, NULL);
/* indexing by first letters */
snprintf(buf, sizeof(buf), "%c", items[i][0]);
elm_index_item_sorted_insert(index, buf, it, _index_icmp, NULL);
}
evas_object_smart_callback_add(index, "delay,changed", _index_changed, NULL);
evas_object_resize(win, 320, 300);
evas_object_show(win);
elm_index_active_set(index, EINA_TRUE);
elm_run();
return 0;
}
ELM_MAIN()

343
legacy/elementary/src/lib/Elementary.h.in
View File

@ -7637,34 +7637,361 @@ extern "C" {
* vertical (two up/down buttons at the right side and text left aligned)
*/
/* index */
typedef struct _Elm_Index_Item Elm_Index_Item; /**< Item of Elm_Index. Sub-type of Elm_Widget_Item */
/**
* @defgroup Index Index
*
* @image html img/widget/index/preview-00.png
*
* An index widget gives you an index for fast access to whichever
* group of other UI items one might have. It's a list of text
* items (usually letters, for alphabetically ordered access).
*
* Index widgets are by default hidden and just appear when the
* user clicks over it's reserved area in the canvas. In its
* default theme, it's an area one @ref Fingers "finger" wide on
* the right side of the index widget's container.
*
* When items on the index are selected, smart callbacks get
* called, so that its user can make other container objects to
* show a given area or child object depending on the index item
* selected. You'd probably be using an index together with @ref
* List "lists", @ref Genlist "generic lists" or @ref Gengrid
* "general grids".
*
* Smart events one can add callbacks for are:
* - @c "changed" - When the selected index item changes. @c
* event_info is the selected item's data pointer.
* - @c "delay,changed" - When the selected index item changes, but
* after a small idling period. @c event_info is the selected
* item's data pointer.
* - @c "selected" - When the user releases a mouse button and
* selects an item. @c event_info is the selected item's data
* pointer.
* - @c "level,up" - when the user moves a finger from the first
* level to the second level
* - @c "level,down" - when the user moves a finger from the second
* level to the first level
*
* The @c "delay,changed" event is so that it'll wait a small time
* before actually reporting those events and, moreover, just the
* last event happening on those time frames will actually be
* reported.
*
* Here are some examples on its usage:
* @li @ref index_example_01
* @li @ref index_example_02
*/
/**
* @addtogroup Index
* @{
*/
typedef struct _Elm_Index_Item Elm_Index_Item; /**< Opaque handle for items of Elementary index widgets */
/**
* Add a new index widget to the given parent Elementary
* (container) object
*
* @param parent The parent object
* @return a new index widget handle or @c NULL, on errors
*
* This function inserts a new index widget on the canvas.
*
* @ingroup Index
*/
EAPI Evas_Object *elm_index_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
/**
* Set whether a given index widget is or not visible,
* programatically.
*
* @param obj The index object
* @param active @c EINA_TRUE to show it, @c EINA_FALSE to hide it
*
* Not to be confused with visible as in @c evas_object_show() --
* visible with regard to the widget's auto hiding feature.
*
* @see elm_index_active_get()
*
* @ingroup Index
*/
EAPI void elm_index_active_set(Evas_Object *obj, Eina_Bool active) EINA_ARG_NONNULL(1);
/**
* Get whether a given index widget is currently visible or not.
*
* @param obj The index object
* @return @c EINA_TRUE, if it's shown, @c EINA_FALSE otherwise
*
* @see elm_index_active_set() for more details
*
* @ingroup Index
*/
EAPI Eina_Bool elm_index_active_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Set the items level for a given index widget.
*
* @param obj The index object.
* @param level @c 0 or @c 1, the currently implemented levels.
*
* @see elm_index_item_level_get()
*
* @ingroup Index
*/
EAPI void elm_index_item_level_set(Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
/**
* Get the items level set for a given index widget.
*
* @param obj The index object.
* @return @c 0 or @c 1, which are the levels @p obj might be at.
*
* @see elm_index_item_level_set() for more information
*
* @ingroup Index
*/
EAPI int elm_index_item_level_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Returns the last selected item's data, for a given index widget.
*
* @param obj The index object.
* @return The item @b data associated to the last selected item on
* @p obj (or @c NULL, on errors).
*
* @warning The returned value is @b not an #Elm_Index_Item item
* handle, but the data associated to it (see the @c item parameter
* in elm_index_item_append(), as an example).
*
* @ingroup Index
*/
EAPI void *elm_index_item_selected_get(const Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
/**
* Append a new item on a given index widget.
*
* @param obj The index object.
* @param letter Letter under which the item should be indexed
* @param item The item data to set for the index's item
*
* Despite the most common usage of the @p letter argument is for
* single char strings, one could use arbitrary strings as index
* entries.
*
* @c item will be the pointer returned back on @c "changed", @c
* "delay,changed" and @c "selected" smart events.
*
* @ingroup Index
*/
EAPI void elm_index_item_append(Evas_Object *obj, const char *letter, const void *item) EINA_ARG_NONNULL(1);
/**
* Prepend a new item on a given index widget.
*
* @param obj The index object.
* @param letter Letter under which the item should be indexed
* @param item The item data to set for the index's item
*
* Despite the most common usage of the @p letter argument is for
* single char strings, one could use arbitrary strings as index
* entries.
*
* @c item will be the pointer returned back on @c "changed", @c
* "delay,changed" and @c "selected" smart events.
*
* @ingroup Index
*/
EAPI void elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item) EINA_ARG_NONNULL(1);
/**
* Append a new item, on a given index widget, <b>after the item
* having @p relative as data</b>.
*
* @param obj The index object.
* @param letter Letter under which the item should be indexed
* @param item The item data to set for the index's item
* @param relative The item data of the index item to be the
* predecessor of this new one
*
* Despite the most common usage of the @p letter argument is for
* single char strings, one could use arbitrary strings as index
* entries.
*
* @c item will be the pointer returned back on @c "changed", @c
* "delay,changed" and @c "selected" smart events.
*
* @note If @p relative is @c NULL or if it's not found to be data
* set on any previous item on @p obj, this function will behave as
* elm_index_item_append().
*
* @ingroup Index
*/
EAPI void elm_index_item_append_relative(Evas_Object *obj, const char *letter, const void *item, const void *relative) EINA_ARG_NONNULL(1);
/**
* Prepend a new item, on a given index widget, <b>after the item
* having @p relative as data</b>.
*
* @param obj The index object.
* @param letter Letter under which the item should be indexed
* @param item The item data to set for the index's item
* @param relative The item data of the index item to be the
* successor of this new one
*
* Despite the most common usage of the @p letter argument is for
* single char strings, one could use arbitrary strings as index
* entries.
*
* @c item will be the pointer returned back on @c "changed", @c
* "delay,changed" and @c "selected" smart events.
*
* @note If @p relative is @c NULL or if it's not found to be data
* set on any previous item on @p obj, this function will behave as
* elm_index_item_prepend().
*
* @ingroup Index
*/
EAPI void elm_index_item_prepend_relative(Evas_Object *obj, const char *letter, const void *item, const void *relative) EINA_ARG_NONNULL(1);
/**
* Insert a new item into the given index widget, using @p cmp_func
* function to sort items (by item data).
*
* @param obj The index object.
* @param letter Letter under which the item should be indexed
* @param item The item data to set for the index's item
* @param cmp_func The comparing function to be used to sort index
* items <b>by #Elm_Index_Item item handles</b>
* @param cmp_data_func A @b fallback function to be called for the
* sorting of index items <b>by item data</b>). It will be used
* when @p cmp_func returns @c 0 (equality), which means an index
* item with provided item data already exists. To decide which
* data item should be pointed to by the index item in question, @p
* cmp_data_func will be used. If @p cmp_data_func returns a
* non-negative value, the previous index item data will be
* replaced by the given @p item pointer. If the previous data need
* to be freed, it should be done by the @p cmp_data_func function,
* because all references to it will be lost. If this function is
* not provided (@c NULL is given), index items will be @b
* duplicated, if @p cmp_func returns @c 0.
*
* Despite the most common usage of the @p letter argument is for
* single char strings, one could use arbitrary strings as index
* entries.
*
* @c item will be the pointer returned back on @c "changed", @c
* "delay,changed" and @c "selected" smart events.
*
* @ingroup Index
*/
EAPI void elm_index_item_sorted_insert(Evas_Object *obj, const char *letter, const void *item, Eina_Compare_Cb cmp_func, Eina_Compare_Cb cmp_data_func) EINA_ARG_NONNULL(1);
/**
* Remove an item from a given index widget, <b>to be referenced by
* it's data value</b>.
*
* @param obj The index object
* @param item The item's data pointer for the item to be removed
* from @p obj
*
* If a deletion callback is set, via elm_index_item_del_cb_set(),
* that callback function will be called by this one.
*
* @warning The item to be removed from @p obj will be found via
* its item data pointer, and not by an #Elm_Index_Item handle.
*
* @ingroup Index
*/
EAPI void elm_index_item_del(Evas_Object *obj, const void *item) EINA_ARG_NONNULL(1);
/**
* Find a given index widget's item, <b>using item data</b>.
*
* @param obj The index object
* @param item The item data pointed to by the desired index item
* @return The index item handle, if found, or @c NULL otherwise
*
* @ingroup Index
*/
EAPI Elm_Index_Item *elm_index_item_find(Evas_Object *obj, const void *item) EINA_ARG_NONNULL(1);
/**
* Removes @b all items from a given index widget.
*
* @param obj The index object.
*
* If deletion callbacks are set, via elm_index_item_del_cb_set(),
* that callback function will be called for each item in @p obj.
*
* @ingroup Index
*/
EAPI void elm_index_item_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Go to a given items level on a index widget
*
* @param obj The index object
* @param level The index level (one of @c 0 or @c 1)
*
* @ingroup Index
*/
EAPI void elm_index_item_go(Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
/**
* Return the data associated with a given index widget item
*
* @param it The index widget item handle
* @return The data associated with @p it
*
* @see elm_index_item_data_set()
*
* @ingroup Index
*/
EAPI void *elm_index_item_data_get(const Elm_Index_Item *item) EINA_ARG_NONNULL(1);
/**
* Set the data associated with a given index widget item
*
* @param it The index widget item handle
* @param data The new data pointer to set to @p it
*
* This sets new item data on @p it.
*
* @warning The old data pointer won't be touched by this function, so
* the user had better to free that old data himself/herself.
*
* @ingroup Index
*/
EAPI void elm_index_item_data_set(Elm_Index_Item *it, const void *data) EINA_ARG_NONNULL(1);
/**
* Set the function to be called when a given index widget item is freed.
*
* @param it The item to set the callback on
* @param func The function to call on the item's deletion
*
* When called, @p func will have both @c data and @c event_info
* arguments with the @p it item's data value and, naturally, the
* @c obj argument with a handle to the parent index widget.
*
* @ingroup Index
*/
EAPI void elm_index_item_del_cb_set(Elm_Index_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
/**
* Get the letter (string) set on a given index widget item.
*
* @param it The index item handle
* @return The letter string set on @p it
*
* @ingroup Index
*/
EAPI const char *elm_index_item_letter_get(const Elm_Index_Item *item) EINA_ARG_NONNULL(1);
/* smart callbacks called:
* "changed" - when the selected index item changes
* "delay,changed" - when the selected index item changes, but after some small idle period
* "selected" - when the user releases a finger and selects an item
* "level,up" - when the user moves a finger from the first level to the second level
* "level,down" - when the user moves a finger from the second level to the first level
/**
* @}
*/
/* photocam */

186
legacy/elementary/src/lib/elm_index.c
View File

@ -1,23 +1,6 @@
#include <Elementary.h>
#include "elm_priv.h"
/**
* @defgroup Index Index
*
* An index object is a type of list that categorizes items in it
* by letter.
*
* Signals that you can add callbacks for are:
*
* "changed" - when the selected index item changes
* "delay,changed" - when the selected index item changes, but after some small i
* dle period
* "selected" - when the user releases a finger and selects an item
* "level,up" - when the user moves a finger from the first level to the second
* level
* "level,down" - when the user moves a finger from the second level to the first * level
*/
typedef struct _Widget_Data Widget_Data;
struct _Widget_Data
@ -520,14 +503,6 @@ _mouse_move(void *data, Evas *e __UNUSED__, Evas_Object *o __UNUSED__, void *eve
_sel_eval(data, ev->cur.canvas.x, ev->cur.canvas.y);
}
/**
* Add a new index to the parent
*
* @param parent The parent object
* @return The new object or NULL if it cannot be created
*
* @ingroup Index
*/
EAPI Evas_Object *
elm_index_add(Evas_Object *parent)
{
@ -602,14 +577,6 @@ elm_index_add(Evas_Object *parent)
return obj;
}
/**
* Set the active state of the index programatically
*
* @param obj The index object
* @param active The active state
*
* @ingroup Index
*/
EAPI void
elm_index_active_set(Evas_Object *obj, Eina_Bool active)
{
@ -629,14 +596,6 @@ elm_index_active_set(Evas_Object *obj, Eina_Bool active)
edje_object_signal_emit(wd->base, "elm,state,inactive", "elm");
}
/**
* Get the active state of the index programatically
*
* @param obj The index object
* @return The active state
*
* @ingroup Index
*/
EAPI Eina_Bool
elm_index_active_get(const Evas_Object *obj)
{
@ -646,14 +605,6 @@ elm_index_active_get(const Evas_Object *obj)
return wd->active;
}
/**
* Sets the level of the item.
*
* @param obj The index object.
* @param level To be documented.
*
* @ingroup Index
*/
EAPI void
elm_index_item_level_set(Evas_Object *obj, int level)
{
@ -664,13 +615,6 @@ elm_index_item_level_set(Evas_Object *obj, int level)
wd->level = level;
}
/**
* Gets the level of the item.
*
* @param obj The index object
*
* @ingroup Index
*/
EAPI int
elm_index_item_level_get(const Evas_Object *obj)
{
@ -680,14 +624,6 @@ elm_index_item_level_get(const Evas_Object *obj)
return wd->level;
}
/**
* Returns the selected item.
*
* @param obj The index object.
* @param level to be documented.
*
* @ingroup Index
*/
EAPI void *
elm_index_item_selected_get(const Evas_Object *obj, int level)
{
@ -702,15 +638,6 @@ elm_index_item_selected_get(const Evas_Object *obj, int level)
return NULL;
}
/**
* Appends a new item.
*
* @param obj The index object.
* @param letter Letter under which the item should be indexed
* @param item The item to put in the index
*
* @ingroup Index
*/
EAPI void
elm_index_item_append(Evas_Object *obj, const char *letter, const void *item)
{
@ -724,15 +651,6 @@ elm_index_item_append(Evas_Object *obj, const char *letter, const void *item)
_index_box_clear(obj, wd->bx[wd->level], wd->level);
}
/**
* Prepends a new item.
*
* @param obj The index object.
* @param letter Letter under which the item should be indexed
* @param item The item to put in the index
*
* @ingroup Index
*/
EAPI void
elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item)
{
@ -747,16 +665,6 @@ elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item)
_index_box_clear(obj, wd->bx[wd->level], wd->level);
}
/**
* Append an item after @p relative in letter @p letter.
*
* @param obj The index object
* @param letter Letter under which the item should be indexed
* @param item The item to put in the index
* @param relative The item to put @p item after
*
* @ingroup Index
*/
EAPI void
elm_index_item_append_relative(Evas_Object *obj, const char *letter, const void *item, const void *relative)
{
@ -781,16 +689,6 @@ elm_index_item_append_relative(Evas_Object *obj, const char *letter, const void
_index_box_clear(obj, wd->bx[wd->level], wd->level);
}
/**
* Prepend an item before @p relative in letter @p letter.
*
* @param obj The index object
* @param letter Letter under which the item should be indexed
* @param item The item to put in the index
* @param relative The item to put @p item before
*
* @ingroup Index
*/
EAPI void
elm_index_item_prepend_relative(Evas_Object *obj, const char *letter, const void *item, const void *relative)
{
@ -815,24 +713,6 @@ elm_index_item_prepend_relative(Evas_Object *obj, const char *letter, const void
_index_box_clear(obj, wd->bx[wd->level], wd->level);
}
/**
* Insert a new @p item into the sorted index @p obj in @p letter.
*
* @param obj The index object
* @param letter Letter under which the item should be indexed
* @param item The item to put in the index
* @param cmp_func The function called for the sort of index items.
* @param cmp_data_func The function called for the sort of the data. It will
* be used when cmp_func return 0. It means the index item already exists.
* So, to decide which data item should be pointed by the index item, a function
* to compare them is needed. If this function is not provided, index items
* will be duplicated. If cmp_data_func returns a non-negative value, the
* previous index item data will be replaced by the inserted @p item. So
* if the previous data need to be free, it should be done in this function,
* because the reference will be lost.
*
* @ingroup Index
*/
EAPI void
elm_index_item_sorted_insert(Evas_Object *obj, const char *letter, const void *item, Eina_Compare_Cb cmp_func, Eina_Compare_Cb cmp_data_func)
{
@ -874,14 +754,6 @@ elm_index_item_sorted_insert(Evas_Object *obj, const char *letter, const void *i
_index_box_clear(obj, wd->bx[wd->level], wd->level);
}
/**
* Remove an item from the index.
*
* @param obj The index object
* @param item The item to remove from the index
*
* @ingroup Index
*/
EAPI void
elm_index_item_del(Evas_Object *obj, const void *item)
{
@ -895,15 +767,6 @@ elm_index_item_del(Evas_Object *obj, const void *item)
_index_box_clear(obj, wd->bx[wd->level], wd->level);
}
/**
* Find an index item using item data.
*
* @param obj The index object
* @param item The item pointed by index item
* @return The index item pointing to @p item
*
* @ingroup Index
*/
EAPI Elm_Index_Item *
elm_index_item_find(Evas_Object *obj, const void *item)
{
@ -913,13 +776,6 @@ elm_index_item_find(Evas_Object *obj, const void *item)
return _item_find(obj, item);
}
/**
* Clears an index of its items.
*
* @param obj The index object.
*
* @ingroup Index
*/
EAPI void
elm_index_item_clear(Evas_Object *obj)
{
@ -937,14 +793,6 @@ elm_index_item_clear(Evas_Object *obj)
EINA_LIST_FREE(clear, it) _item_free(it);
}
/**
* Go to item at @p level
*
* @param obj The index object
* @param level The index level
*
* @ingroup Index
*/
EAPI void
elm_index_item_go(Evas_Object *obj, int level __UNUSED__)
{
@ -955,14 +803,6 @@ elm_index_item_go(Evas_Object *obj, int level __UNUSED__)
if (wd->level == 1) _index_box_auto_fill(obj, wd->bx[1], 1);
}
/**
* Returns the data associated with the item.
*
* @param it The list item
* @return The data associated with @p it
*
* @ingroup Index
*/
EAPI void *
elm_index_item_data_get(const Elm_Index_Item *it)
{
@ -970,16 +810,6 @@ elm_index_item_data_get(const Elm_Index_Item *it)
return elm_widget_item_data_get(it);
}
/**
* Set the data item from the index item
*
* This set a new data value.
*
* @param it The item
* @param data The new data pointer to set
*
* @ingroup Index
*/
EAPI void
elm_index_item_data_set(Elm_Index_Item *it, const void *data)
{
@ -987,14 +817,6 @@ elm_index_item_data_set(Elm_Index_Item *it, const void *data)
elm_widget_item_data_set(it, data);
}
/**
* Set the function called when a index item is freed.
*
* @param it The item to set the callback on
* @param func The function called
*
* @ingroup Index
*/
EAPI void
elm_index_item_del_cb_set(Elm_Index_Item *it, Evas_Smart_Cb func)
{
@ -1002,14 +824,6 @@ elm_index_item_del_cb_set(Elm_Index_Item *it, Evas_Smart_Cb func)
elm_widget_item_del_cb_set(it, func);
}
/**
* Gets the letter of the item.
*
* @param it The list item
* @return The letter of @p it
*
* @ingroup Index
*/
EAPI const char *
elm_index_item_letter_get(const Elm_Index_Item *it)
{