Elementary: Calendar Documentation

SVN revision: 61383

legacy/elementary/doc/examples.dox

@@ -19,6 +19,18 @@
  *
  * @ref general_functions_example_page
  *
+ * @ref calendar_example_01
+ *
+ * @ref calendar_example_02
+ *
+ * @ref calendar_example_03
+ *
+ * @ref calendar_example_04
+ *
+ * @ref calendar_example_05
+ *
+ * @ref calendar_example_06
+ *
  * @ref clock_example
  *
  * @ref flipselector_example
@@ -1097,6 +1109,262 @@
  * @example box_example_02.c
  */
 
+/**
+ * @page calendar_example_01 Calendar - Simple creation.
+ * @dontinclude calendar_example_01.c
+ *
+ * As a first example, let's just display a calendar in our window,
+ * explaining all steps required to do so.
+ *
+ * First you should declare objects we intend to use:
+ * @skipline Evas_Object
+ *
+ * Then a window is created, a title is set and its set to be autodeleted.
+ * More details can be found on windows examples:
+ * @until elm_win_autodel
+ *
+ * Next a simple background is placed on our windows. More details on
+ * @ref bg_01_example_page:
+ * @until evas_object_show(bg)
+ *
+ * Now, the exciting part, let's add the calendar with elm_calendar_add(),
+ * passing our window object as parent.
+ * @until evas_object_show(cal);
+ *
+ * To conclude our example, we should show the window and run elm mainloop:
+ * @until ELM_MAIN
+ *
+ * Our example will look like this:
+ * @image html screenshots/calendar_example_01.png
+ * @image latex screenshots/calendar_example_01.eps
+ *
+ * See the full source code @ref calendar_example_01.c here.
+ * @example calendar_example_01.c
+ */
+
+/**
+ * @page calendar_example_02 Calendar - Layout strings formatting.
+ * @dontinclude calendar_example_02.c
+ *
+ * In this simple example, we'll explain how to format the label displaying
+ * month and year, and also set weekday names.
+ *
+ * To format month and year label, we need to create a callback function
+ * to create a string given the selected time, declared under a
+ * <tt> struct tm </tt>.
+ *
+ * <tt> struct tm </tt>, declared on @c time.h, is a structure composed by
+ * nine integers:
+ * @li tm_sec   seconds [0,59]
+ * @li tm_min   minutes [0,59]
+ * @li tm_hour  hour [0,23]
+ * @li tm_mday  day of month [1,31]
+ * @li tm_mon   month of year [0,11]
+ * @li tm_year  years since 1900
+ * @li tm_wday  day of week [0,6] (Sunday = 0)
+ * @li tm_yday  day of year [0,365]
+ * @li tm_isdst daylight savings flag
+ * @note glib version has 2 additional fields.
+ *
+ * For our function, only stuff that matters are tm_mon and tm_year.
+ * But we don't need to access it directly, since there are nice functions
+ * to format date and time, as @c strftime.
+ * We will get abbreviated month (%b) and year (%y) (check strftime manpage
+ * for more) in our example:
+ * @skipline static char
+ * @until }
+ *
+ * We need to alloc the string to be returned, and calendar widget will
+ * free it when it's not needed, what is done by @c strdup.
+ * So let's register our callback to calendar object:
+ * @skipline elm_calendar_format_function_set
+ *
+ * To set weekday names, we should declare them as an array of strings:
+ * @dontinclude calendar_example_02.c
+ * @skipline weekdays
+ * @until }
+ *
+ * And finally set them to calendar:
+ * skipline weekdays_names_set
+ *
+ * Our example will look like this:
+ * @image html screenshots/calendar_example_02.png
+ * @image latex screenshots/calendar_example_02.eps
+ *
+ * See the full source code @ref calendar_example_02.c here.
+ * @example calendar_example_02.c
+ */
+
+/**
+ * @page calendar_example_03 Calendar - Years restrictions.
+ * @dontinclude calendar_example_03.c
+ *
+ * This example explains how to set max and min year to be displayed
+ * by a calendar object. This means that user won't be able to
+ * see or select a date before and after selected years.
+ * By default, limits are 1902 and maximun value will depends
+ * on platform architecture (year 2037 for 32 bits); You can
+ * read more about time functions on @c ctime manpage.
+ *
+ * Straigh to the point, to set it is enough to call
+ * elm_calendar_min_max_year_set(). First value is minimun year, second
+ * is maximum. If first value is negative, it won't apply limit for min
+ * year, if the second one is negative, won't apply for max year.
+ * Setting both to negative value will clear limits (default state):
+ * @skipline elm_calendar_min_max_year_set
+ *
+ * Our example will look like this:
+ * @image html screenshots/calendar_example_03.png
+ * @image latex screenshots/calendar_example_03.eps
+ *
+ * See the full source code @ref calendar_example_03.c here.
+ * @example calendar_example_03.c
+ */
+
+/**
+ * @page calendar_example_04 Calendar - Days selection.
+ * @dontinclude calendar_example_04.c
+ *
+ * It's possible to disable date selection and to select a date
+ * from your program, and that's what we'll see on this example.
+ *
+ * If isn't required that users could select a day on calendar,
+ * only interacting going through months, disabling days selection
+ * could be a good idea to avoid confusion. For that:
+ * @skipline elm_calendar_day_selection_enabled_set
+ *
+ * Also, regarding days selection, you could be interested to set a
+ * date to be highlighted on calendar from your code, maybe when
+ * a specific event happens, or after calendar creation. Let's select
+ * two days from current day:
+ * @dontinclude calendar_example_04.c
+ * @skipline SECS_DAY
+ * @skipline current_time
+ * @until elm_calendar_selected_time_set
+ *
+ * Our example will look like this:
+ * @image html screenshots/calendar_example_04.png
+ * @image latex screenshots/calendar_example_04.eps
+ *
+ * See the full source code @ref calendar_example_04.c here.
+ * @example calendar_example_04.c
+ */
+
+/**
+ * @page calendar_example_05 Calendar - Signal callback and getters.
+ * @dontinclude calendar_example_05.c
+ *
+ * Most of setters explained on previous examples have associated getters.
+ * That's the subject of this example. We'll add a callback to display
+ * all calendar information every time user interacts with the calendar.
+ *
+ * Let's check our callback function:
+ * @skipline static void
+ * @until double interval;
+ *
+ * To get selected day, we need to call elm_calendar_selected_time_get(),
+ * but to assure nothing wrong happened, we must check for function return.
+ * It'll return @c EINA_FALSE if fail. Otherwise we can use time set to
+ * our structure @p stime.
+ * @skipline elm_calendar_selected_time_get
+ * @until return
+ *
+ * Next we'll get information from calendar and place on declared vars:
+ * @skipline interval
+ * @until elm_calendar_weekdays_names_get
+ *
+ * The only tricky part is that last line gets an array of strings
+ * (char arrays), one for each weekday.
+ *
+ * Then we can simple print that to stdin:
+ * @skipline printf
+ * @until }
+ *
+ * <tt> struct tm </tt> is declared on @c time.h. You can check @c ctime
+ * manpage to read about it.
+ *
+ * To register this callback, that will be called every time user selects
+ * a day or goes to next or previous month, just add a callback for signal
+ * @b changed.
+ * @skipline evas_object_smart_callback_add
+ *
+ * Our example will look like this:
+ * @image html screenshots/calendar_example_05.png
+ * @image latex screenshots/calendar_example_05.eps
+ *
+ * See the full source code @ref calendar_example_05.c here.
+ * @example calendar_example_05.c
+ */
+
+/**
+ * @page calendar_example_06 Calendar - Calendar marks.
+ * @dontinclude calendar_example_06.c
+ *
+ * On this example marks management will be explained. Functions
+ * elm_calendar_mark_add(), elm_calendar_mark_del() and
+ * elm_calendar_marks_clear() will be covered.
+ *
+ * To add a mark, will be required to choose three things:
+ * @li mark style
+ * @li mark date, or start date if it will be repeated
+ * @li mark periodicity
+ *
+ * Style defines the kind of mark will be displayed over marked day,
+ * on caledar. Default theme supports @b holiday and @b checked.
+ * If more is required, is possible to set a new theme to calendar
+ * widget using elm_object_style_set(), and use
+ * the signal that will be used by such marks.
+ *
+ * Date is a <tt> struct tm </tt>, as defined by @c time.h. More can
+ * be read on @c ctime manpage.
+ * If a date relative from current is required, this struct can be set
+ * as:
+ * @skipline current_time
+ * @until localtime_r
+ *
+ * Or if it's an absolute date, you can just declare the struct like:
+ * @dontinclude calendar_example_06.c
+ * @skipline sunday
+ * @until christmas.tm_mon
+ *
+ * Periodicity is how frequently the mark will be displayed over the
+ * calendar.  Can be a unique mark (that don't repeat), or it can repeat
+ * daily, weekly, monthly or annually. It's enumerated by
+ * @c Elm_Calendar_Mark_Repeat.
+ *
+ * So let's add some marks to our calendar. We will add christmas holiday,
+ * set Sundays as holidays, and check current day and day after that.
+ * @dontinclude calendar_example_06.c
+ * @skipline sunday
+ * @until christmas.tm_mon
+ * @skipline current_time
+ * @until ELM_CALENDAR_WEEKLY
+ *
+ * We kept the return of first mark add, because we don't really won't it
+ * to be checked, so let's remove it:
+ * @skipline elm_calendar_mark_del
+ *
+ * After all marks are added and removed, is required to draw them:
+ * @skipline elm_calendar_marks_draw
+ *
+ * Finally, to clear all marks, let's set a callback for our button:
+ * @skipline elm_button_add
+ * @until evas_object_show(bt);
+ *
+ * This callback will receive our calendar object, and should clear it:
+ * @dontinclude calendar_example_06.c
+ * @skipline static
+ * @until }
+ * @note Remember to draw marks after clear the calendar.
+ *
+ * Our example will look like this:
+ * @image html screenshots/calendar_example_06.png
+ * @image latex screenshots/calendar_example_06.eps
+ *
+ * See the full source code @ref calendar_example_06.c here.
+ * @example calendar_example_06.c
+ */
+
 /**
  * @page clock_example Clock widget example
  *

legacy/elementary/src/examples/Makefile.am

@@ -49,6 +49,12 @@ SRCS = \
 	label_example_01.c \
 	theme_example_01.c \
 	theme_example_02.c \
+	calendar_example_01.c \
+	calendar_example_02.c \
+	calendar_example_03.c \
+	calendar_example_04.c \
+	calendar_example_05.c \
+	calendar_example_06.c \
 	clock_example.c \
 	theme_example.edc
 
@@ -91,6 +97,12 @@ pkglib_PROGRAMS += \
 	label_example_01 \
 	theme_example_01 \
 	theme_example_02 \
+	calendar_example_01 \
+	calendar_example_02 \
+	calendar_example_03 \
+	calendar_example_04 \
+	calendar_example_05 \
+	calendar_example_06 \
 	clock_example \
 	flipselector_example \
 	theme_example.edj
@@ -114,6 +126,12 @@ SCREENSHOTS = \
 	hover_example_01:hover_example_01.png:0.0 \
 	label_example_01:label_example_01.png:0.0 \
 	theme_example_01:theme_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 \
+	calendar_example_04:calendar_example_04.png:0.0 \
+	calendar_example_05:calendar_example_05.png:0.0 \
+	calendar_example_06:calendar_example_06.png:0.0 \
 	clock_example:clock_example.png:0.5 \
 	flipselector_example:flipselector_example.png:0.0
 

legacy/elementary/src/examples/calendar_example_01.c

@@ -0,0 +1,43 @@
+/**
+ * Simple Elementary's <b>calendar widget</b> example, illustrating its
+ * creation.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` calendar_example_01.c -o calendar_example_01
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *cal;
+
+   win = elm_win_add(NULL, "calendar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Calendar Creation Example");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   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);
+
+   cal = elm_calendar_add(win);
+   elm_win_resize_object_add(win, cal);
+   evas_object_size_hint_weight_set(cal, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(cal);
+
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/examples/calendar_example_02.c

@@ -0,0 +1,61 @@
+/**
+ * Elementary's <b>calendar widget</b> example, demonstrates how to modify
+ * layout strings, using functions to set weekdays names and to format
+ * month and year label.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` calendar_example_02.c -o calendar_example_02
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+static char *
+_format_month_year(struct tm *stime)
+{
+   char buf[32];
+   /* abbreviates month and year */
+   if (!strftime(buf, sizeof(buf), "%b %y", stime)) return NULL;
+   return strdup(buf);
+}
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *cal;
+   const char *weekdays[] =
+     {
+        "S", "M", "T", "W", "T", "F", "S"
+     };
+
+   win = elm_win_add(NULL, "calendar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Calendar Layout Formatting Example");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   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);
+
+   cal = elm_calendar_add(win);
+   elm_win_resize_object_add(win, cal);
+   evas_object_size_hint_weight_set(cal, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+
+   elm_calendar_format_function_set(cal, _format_month_year);
+   elm_calendar_weekdays_names_set(cal, weekdays);
+
+   evas_object_show(cal);
+
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/examples/calendar_example_03.c

@@ -0,0 +1,45 @@
+/**
+ * Simple Elementary's <b>calendar widget</b> example, illustrating minimum
+ * and maximum years restriction. User will see a calendar of years
+ * 2020, 2021 and 2022.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` calendar_example_03.c -o calendar_example_03
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *cal;
+
+   win = elm_win_add(NULL, "calendar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Calendar Min/Max Year Example");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   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);
+
+   cal = elm_calendar_add(win);
+   elm_win_resize_object_add(win, cal);
+   evas_object_size_hint_weight_set(cal, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   elm_calendar_min_max_year_set(cal, 2020, 2022);
+   evas_object_show(cal);
+
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/examples/calendar_example_04.c

@@ -0,0 +1,64 @@
+/**
+ * Elementary's <b>calendar widget</b> example, regarding date selection.
+ * Shows how to disable day selection by user and how to select a date.
+ * It selects two days from current day.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` calendar_example_04.c -o calendar_example_04
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+#define SECS_DAY 86400
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *bx, *cal, *cal2;
+   struct tm selected_time;
+   time_t current_time;
+
+   win = elm_win_add(NULL, "calendar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Calendar Day Selection Example");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   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);
+
+   bx = elm_box_add(win);
+   elm_win_resize_object_add(win, bx);
+   evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(bx);
+
+   cal = elm_calendar_add(win);
+   evas_object_size_hint_weight_set(cal, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(cal, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_calendar_day_selection_enabled_set(cal, EINA_FALSE);
+   evas_object_show(cal);
+   elm_box_pack_end(bx, cal);
+
+   cal2 = elm_calendar_add(win);
+   evas_object_size_hint_weight_set(cal2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(cal2, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   current_time = time(NULL) + 2 * SECS_DAY;
+   localtime_r(&current_time, &selected_time);
+   elm_calendar_selected_time_set(cal2, &selected_time);
+   evas_object_show(cal2);
+   elm_box_pack_end(bx, cal2);
+
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/examples/calendar_example_05.c

@@ -0,0 +1,71 @@
+/**
+ * Elementary's <b>calendar widget</b> example, illustrating smart callback
+ * registry and getters usage.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` calendar_example_05.c -o calendar_example_05
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+static void
+_print_cal_info_cb(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__)
+{
+   int year_min, year_max;
+   Eina_Bool sel_enabled;
+   const char **wds;
+   struct tm stime;
+   double interval;
+
+   if (!elm_calendar_selected_time_get(obj, &stime))
+     return;
+
+   interval = elm_calendar_interval_get(obj);
+   elm_calendar_min_max_year_get(obj, &year_min, &year_max);
+   sel_enabled = elm_calendar_day_selection_enabled_get(obj);
+   wds = elm_calendar_weekdays_names_get(obj);
+
+   printf("Day: %i, Mon: %i, Year %i, WeekDay: %i<br>\n"
+          "Interval: %0.2f, Year_Min: %i, Year_Max %i, Sel Enabled : %i<br>\n"
+          "Weekdays: %s, %s, %s, %s, %s, %s, %s<br>\n\n",
+          stime.tm_mday, stime.tm_mon, stime.tm_year + 1900, stime.tm_wday,
+          interval, year_min, year_max, sel_enabled,
+          wds[0], wds[1], wds[2], wds[3], wds[4], wds[5], wds[6]);
+}
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *cal;
+
+   win = elm_win_add(NULL, "calendar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Calendar Getters Example");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   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);
+
+   cal = elm_calendar_add(win);
+   elm_win_resize_object_add(win, cal);
+   evas_object_size_hint_weight_set(cal, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   /* Add callback to display calendar information every time user
+    * selects a new date */
+   evas_object_smart_callback_add(cal, "changed", _print_cal_info_cb, NULL);
+   evas_object_show(cal);
+
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/examples/calendar_example_06.c

@@ -0,0 +1,98 @@
+/**
+ * Elementary's <b>calendar widget</b> example to add / del / clear marks.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` calendar_example_06.c -o calendar_example_06
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+#define SECS_DAY 86400
+
+static void
+_btn_clear_cb(void *data, Evas_Object *btn __UNUSED__, void *ev __UNUSED__)
+{
+   Evas_Object *cal = data;
+   elm_calendar_marks_clear(cal);
+   elm_calendar_marks_draw(cal);
+}
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *bt, *bx, *cal;
+   Elm_Calendar_Mark *mark;
+   struct tm selected_time;
+   time_t current_time;
+   struct tm sunday = {0, 0, 12, 7, 0, 0, 0, 0, -1 };
+   /* tm {sec, min, hour, mday, mon, year, wday, yday, isdst } */
+   /* weekdays since Sunday, range 0 to 6 */
+   struct tm christmas;
+   christmas.tm_mday = 25;
+   /* months since Jan, in the range 0 to 11 */
+   christmas.tm_mon = 11;
+
+   win = elm_win_add(NULL, "calendar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Calendar Marks Example");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   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);
+
+   bx = elm_box_add(win);
+   elm_win_resize_object_add(win, bx);
+   evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(bx);
+
+   cal = elm_calendar_add(win);
+   evas_object_size_hint_weight_set(cal, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(cal, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(bx, cal);
+   evas_object_show(cal);
+
+   /* check today - we'll remove it later */
+   current_time = time(NULL);
+   localtime_r(&current_time, &selected_time);
+   mark = elm_calendar_mark_add(cal, "checked", &selected_time,
+                                ELM_CALENDAR_UNIQUE);
+
+   /* check tomorrow */
+   current_time = time(NULL) + 1 * SECS_DAY;
+   localtime_r(&current_time, &selected_time);
+   elm_calendar_mark_add(cal, "checked", &selected_time, ELM_CALENDAR_UNIQUE);
+
+   /* mark christmas as holiday */
+   elm_calendar_mark_add(cal, "holiday", &christmas, ELM_CALENDAR_ANNUALLY);
+
+   /* mark Sundays as holidays */
+   elm_calendar_mark_add(cal, "holiday", &sunday, ELM_CALENDAR_WEEKLY);
+
+   /* ok, let's remove today's check */
+   elm_calendar_mark_del(mark);
+
+   elm_calendar_marks_draw(cal);
+
+   bt = elm_button_add(win);
+   evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_button_label_set(bt, "Clear marks");
+   evas_object_smart_callback_add(bt, "clicked", _btn_clear_cb, cal);
+   elm_box_pack_end(bx, bt);
+   evas_object_show(bt);
+
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

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

@@ -7007,40 +7007,503 @@ extern "C" {
     * @}
     */
 
-   /* calendar */
+   /**
+    * @defgroup Calendar Calendar
+    * @ingroup Elementary
+    *
+    * A calendar is a widget that displays a regular calendar, one
+    * month at a time, to the user, and can allows the user to select a date.
+    *
+    * It has support to adding check marks (holidays and checks are supported
+    * by default theme).
+    *
+    * Weekday names and the function used to format month and year to
+    * be displayed can be set, giving more flexibility to this widget.
+    *
+    * Smart callbacks one can register to:
+    * - "changed" - emitted when the user selects a day or changes the
+    *   displayed month, what actually changes the selected day as well.
+    *
+    * Available styles for it:
+    * - @c "default"
+    *
+    * List of examples:
+    * @li @ref calendar_example_01
+    * @li @ref calendar_example_02
+    * @li @ref calendar_example_03
+    * @li @ref calendar_example_04
+    * @li @ref calendar_example_05
+    * @li @ref calendar_example_06
+    */
+
+   /**
+    * @addtogroup Calendar
+    * @{
+    */
+
+   /**
+    * Event periodicity, used to define if a mark should be repeated
+    * @b beyond event's day. It's set when a mark is added.
+    *
+    * So, for a mark added to 13th May with periodicity set to WEEKLY,
+    * there will be marks every week after this date. Marks will be displayed
+    * at 13th, 20th, 27th, 3rd June ...
+    *
+    * Values don't work as bitmaks, only one can be choosen.
+    *
+    * @see elm_calendar_mark_add()
+    */
    typedef enum
      {
-        ELM_CALENDAR_UNIQUE,
-        ELM_CALENDAR_DAILY,
-        ELM_CALENDAR_WEEKLY,
-        ELM_CALENDAR_MONTHLY,
-        ELM_CALENDAR_ANNUALLY
+        ELM_CALENDAR_UNIQUE, /**< Default value. Marks will be displayed only on event day. */
+        ELM_CALENDAR_DAILY, /**< Marks will be displayed everyday after event day (inclusive). */
+        ELM_CALENDAR_WEEKLY, /**< Marks will be displayed every week after event day (inclusive) - i.e. each seven days. */
+        ELM_CALENDAR_MONTHLY, /**< Marks will be displayed every month day that coincides to event day. E.g.: if an event is set to 30th Jan, no marks will be displayed on Feb, but will be displayed on 30th Mar*/
+        ELM_CALENDAR_ANNUALLY /**< Marks will be displayed every year that coincides to event day (and month). E.g. an event added to 30th Jan 2012 will be repeated on 30th Jan 2013. */
      } Elm_Calendar_Mark_Repeat;
-   typedef struct _Elm_Calendar_Mark Elm_Calendar_Mark;
 
+   typedef struct _Elm_Calendar_Mark Elm_Calendar_Mark; /**< Item handle for a calendar mark. Created with elm_calendar_mark_add() and deleted with elm_calendar_mark_del(). */
+
+   /**
+    * Add a new calendar widget to the given parent Elementary
+    * (container) object.
+    *
+    * @param parent The parent object.
+    * @return a new calendar widget handle or @c NULL, on errors.
+    *
+    * This function inserts a new calendar widget on the canvas.
+    *
+    * @ref calendar_example_01
+    *
+    * @ingroup Calendar
+    */
    EAPI Evas_Object       *elm_calendar_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get weekdays names displayed by the calendar.
+    *
+    * @param obj The calendar object.
+    * @return Array of seven strings to be used as weekday names.
+    *
+    * By default, weekdays abbreviations get from system are displayed:
+    * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
+    * The first string is related to Sunday, the second to Monday...
+    *
+    * @see elm_calendar_weekdays_name_set()
+    *
+    * @ref calendar_example_05
+    *
+    * @ingroup Calendar
+    */
    EAPI const char       **elm_calendar_weekdays_names_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set weekdays names to be displayed by the calendar.
+    *
+    * @param obj The calendar object.
+    * @param weedays Array of seven strings to be used as weekday names.
+    * @warning It must have 7 elements, or it will access invalid memory.
+    * @warning The strings must be NULL terminated ('@\0').
+    *
+    * By default, weekdays abbreviations get from system are displayed:
+    * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
+    *
+    * The first string should be related to Sunday, the second to Monday...
+    *
+    * The usage should be like this:
+    * @code
+    *   const char *weekdays[] =
+    *   {
+    *      "Sunday", "Monday", "Tuesday", "Wednesday",
+    *      "Thursday", "Friday", "Saturday"
+    *   };
+    *   elm_calendar_weekdays_names_set(calendar, weekdays);
+    * @endcode
+    *
+    * @see elm_calendar_weekdays_name_get()
+    *
+    * @ref calendar_example_02
+    *
+    * @ingroup Calendar
+    */
    EAPI void               elm_calendar_weekdays_names_set(Evas_Object *obj, const char *weekdays[]) EINA_ARG_NONNULL(1, 2);
-   EAPI double             elm_calendar_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void               elm_calendar_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1);
-   EAPI void               elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the minimum and maximum values for the year
+    *
+    * @param obj The calendar object
+    * @param min The minimum year, greater than 1901;
+    * @param max The maximum year;
+    *
+    * Maximum must be greater than minimum, except if you don't wan't to set
+    * maximum year.
+    * Default values are 1902 and -1.
+    *
+    * If the maximum year is a negative value, it will be limited depending
+    * on the platform architecture (year 2037 for 32 bits);
+    *
+    * @see elm_calendar_min_max_year_get()
+    *
+    * @ref calendar_example_03
+    *
+    * @ingroup Calendar
+    */
    EAPI void               elm_calendar_min_max_year_set(Evas_Object *obj, int min, int max) EINA_ARG_NONNULL(1);
-   EAPI Eina_Bool          elm_calendar_day_selection_enabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the minimum and maximum values for the year
+    *
+    * @param obj The calendar object.
+    * @param min The minimum year.
+    * @param max The maximum year.
+    *
+    * Default values are 1902 and -1.
+    *
+    * @see elm_calendar_min_max_year_get() for more details.
+    *
+    * @ref calendar_example_05
+    *
+    * @ingroup Calendar
+    */
+   EAPI void               elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max) EINA_ARG_NONNULL(1);
+
+   /**
+    * Enable or disable day selection
+    *
+    * @param obj The calendar object.
+    * @param enabled @c EINA_TRUE to enable selection or @c EINA_FALSE to
+    * disable it.
+    *
+    * Enabled by default. If disabled, the user still can select months,
+    * but not days. Selected days are highlighted on calendar.
+    * It should be used if you won't need such selection for the widget usage.
+    *
+    * When a day is selected, or month is changed, smart callbacks for
+    * signal "changed" will be called.
+    *
+    * @see elm_calendar_day_selection_enable_get()
+    *
+    * @ref calendar_example_04
+    *
+    * @ingroup Calendar
+    */
    EAPI void               elm_calendar_day_selection_enabled_set(Evas_Object *obj, Eina_Bool enabled) EINA_ARG_NONNULL(1);
-   EAPI Eina_Bool          elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time) EINA_ARG_NONNULL(1, 2);
+
+   /**
+    * Get a value whether day selection is enabled or not.
+    *
+    * @see elm_calendar_day_selection_enable_set() for details.
+    *
+    * @param obj The calendar object.
+    * @return EINA_TRUE means day selection is enabled. EINA_FALSE indicates
+    * it's disabled. If @p obj is NULL, EINA_FALSE is returned.
+    *
+    * @ref calendar_example_05
+    *
+    * @ingroup Calendar
+    */
+   EAPI Eina_Bool          elm_calendar_day_selection_enabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+
+   /**
+    * Set selected date to be highlighted on calendar.
+    *
+    * @param obj The calendar object.
+    * @param selected_time A @b tm struct to represent the selected date.
+    *
+    * Set the selected date, changing the displayed month if needed.
+    * Selected date changes when the user goes to next/previous month or
+    * select a day pressing over it on calendar.
+    *
+    * @see elm_calendar_selected_time_get()
+    *
+    * @ref calendar_example_04
+    *
+    * @ingroup Calendar
+    */
    EAPI void               elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get selected date.
+    *
+    * @param obj The calendar object
+    * @param selected_time A @b tm struct to point to selected date
+    * @return EINA_FALSE means an error ocurred and returned time shouldn't
+    * be considered.
+    *
+    * Get date selected by the user or set by function
+    * elm_calendar_selected_time_set().
+    * Selected date changes when the user goes to next/previous month or
+    * select a day pressing over it on calendar.
+    *
+    * @see elm_calendar_selected_time_get()
+    *
+    * @ref calendar_example_05
+    *
+    * @ingroup Calendar
+    */
+   EAPI Eina_Bool          elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time) EINA_ARG_NONNULL(1, 2);
+
+   /**
+    * Set a function to format the string that will be used to display
+    * month and year;
+    *
+    * @param obj The calendar object
+    * @param format_function Function to set the month-year string given
+    * the selected date
+    *
+    * By default it uses strftime with "%B %Y" format string.
+    * It should allocate the memory that will be used by the string,
+    * that will be freed by the widget after usage.
+    * A pointer to the string and a pointer to the time struct will be provided.
+    *
+    * Example:
+    * @code
+    * static char *
+    * _format_month_year(struct tm *selected_time)
+    * {
+    *    char buf[32];
+    *    if (!strftime(buf, sizeof(buf), "%B %Y", selected_time)) return NULL;
+    *    return strdup(buf);
+    * }
+    *
+    * elm_calendar_format_function_set(calendar, _format_month_year);
+    * @endcode
+    *
+    * @ref calendar_example_02
+    *
+    * @ingroup Calendar
+    */
    EAPI void               elm_calendar_format_function_set(Evas_Object *obj, char * (*format_function) (struct tm *stime)) EINA_ARG_NONNULL(1);
+
+   /**
+    * Add a new mark to the calendar
+    *
+    * @param obj The calendar object
+    * @param mark_type A string used to define the type of mark. It will be
+    * emitted to the theme, that should display a related modification on these
+    * days representation.
+    * @param mark_time A time struct to represent the date of inclusion of the
+    * mark. For marks that repeats it will just be displayed after the inclusion
+    * date in the calendar.
+    * @param repeat Repeat the event following this periodicity. Can be a unique
+    * mark (that don't repeat), daily, weekly, monthly or annually.
+    * @return The created mark or @NULL upon failure.
+    *
+    * Add a mark that will be drawn in the calendar respecting the insertion
+    * time and periodicity. It will emit the type as signal to the widget theme.
+    * Default theme supports "holiday" and "checked", but it can be extended.
+    *
+    * It won't immediately update the calendar, drawing the marks.
+    * For this, call elm_calendar_marks_draw(). However, when user selects
+    * next or previous month calendar forces marks drawn.
+    *
+    * Marks created with this method can be deleted with
+    * elm_calendar_mark_del().
+    *
+    * Example
+    * @code
+    * struct tm selected_time;
+    * time_t current_time;
+    *
+    * current_time = time(NULL) + 5 * 84600;
+    * localtime_r(&current_time, &selected_time);
+    * elm_calendar_mark_add(cal, "holiday", selected_time,
+    *     ELM_CALENDAR_ANNUALLY);
+    *
+    * current_time = time(NULL) + 1 * 84600;
+    * localtime_r(&current_time, &selected_time);
+    * elm_calendar_mark_add(cal, "checked", selected_time, ELM_CALENDAR_UNIQUE);
+    *
+    * elm_calendar_marks_draw(cal);
+    * @endcode
+    *
+    * @see elm_calendar_marks_draw()
+    * @see elm_calendar_mark_del()
+    *
+    * @ref calendar_example_06
+    *
+    * @ingroup Calendar
+    */
    EAPI Elm_Calendar_Mark *elm_calendar_mark_add(Evas_Object *obj, const char *mark_type, struct tm *mark_time, Elm_Calendar_Mark_Repeat repeat) EINA_ARG_NONNULL(1);
+
+   /**
+    * Delete mark from the calendar.
+    *
+    * @param mark The mark to be deleted.
+    *
+    * If deleting all calendar marks is required, elm_calendar_marks_clear()
+    * should be used instead of getting marks list and deleting each one.
+    *
+    * @see elm_calendar_mark_add()
+    *
+    * @ref calendar_example_06
+    *
+    * @ingroup Calendar
+    */
    EAPI void               elm_calendar_mark_del(Elm_Calendar_Mark *mark) EINA_ARG_NONNULL(1);
+
+   /**
+    * Remove all calendar's marks
+    *
+    * @param obj The calendar object.
+    *
+    * @see elm_calendar_mark_add()
+    * @see elm_calendar_mark_del()
+    *
+    * @ingroup Calendar
+    */
    EAPI void               elm_calendar_marks_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+
+   /**
+    * Get a list of all the calendar marks.
+    *
+    * @param obj The calendar object.
+    * @return An @c Eina_List of calendar marks objects, or @c NULL on failure.
+    *
+    * @see elm_calendar_mark_add()
+    * @see elm_calendar_mark_del()
+    * @see elm_calendar_marks_clear()
+    *
+    * @ingroup Calendar
+    */
    EAPI const Eina_List   *elm_calendar_marks_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Draw calendar marks.
+    *
+    * @param obj The calendar object.
+    *
+    * Should be used after adding, removing or clearing marks.
+    * It will go through the entire marks list updating the calendar.
+    * If lots of marks will be added, add all the marks and then call
+    * this function.
+    *
+    * When the month is changed, i.e. user selects next or previous month,
+    * marks will be drawed.
+    *
+    * @see elm_calendar_mark_add()
+    * @see elm_calendar_mark_del()
+    * @see elm_calendar_marks_clear()
+    *
+    * @ref calendar_example_06
+    *
+    * @ingroup Calendar
+    */
    EAPI void               elm_calendar_marks_draw(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set a day text color to the same that represents Saturdays.
+    *
+    * @param obj The calendar object.
+    * @param pos The text position. Position is the cell counter, from left
+    * to right, up to down. It starts on 0 and ends on 41.
+    *
+    * @deprecated use elm_calendar_mark_add() instead like:
+    *
+    * @code
+    * struct tm t = { 0, 0, 12, 6, 0, 0, 6, 6, -1 };
+    * elm_calendar_mark_add(obj, "sat", &t, ELM_CALENDAR_WEEKLY);
+    * @endcode
+    *
+    * @see elm_calendar_mark_add()
+    *
+    * @ingroup Calendar
+    */
    EINA_DEPRECATED EAPI void               elm_calendar_text_saturday_color_set(Evas_Object *obj, int pos) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set a day text color to the same that represents Sundays.
+    *
+    * @param obj The calendar object.
+    * @param pos The text position. Position is the cell counter, from left
+    * to right, up to down. It starts on 0 and ends on 41.
+
+    * @deprecated use elm_calendar_mark_add() instead like:
+    *
+    * @code
+    * struct tm t = { 0, 0, 12, 7, 0, 0, 0, 0, -1 };
+    * elm_calendar_mark_add(obj, "sat", &t, ELM_CALENDAR_WEEKLY);
+    * @endcode
+    *
+    * @see elm_calendar_mark_add()
+    *
+    * @ingroup Calendar
+    */
    EINA_DEPRECATED EAPI void               elm_calendar_text_sunday_color_set(Evas_Object *obj, int pos) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set a day text color to the same that represents Weekdays.
+    *
+    * @param obj The calendar object
+    * @param pos The text position. Position is the cell counter, from left
+    * to right, up to down. It starts on 0 and ends on 41.
+    *
+    * @deprecated use elm_calendar_mark_add() instead like:
+    *
+    * @code
+    * struct tm t = { 0, 0, 12, 1, 0, 0, 0, 0, -1 };
+    *
+    * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // monday
+    * t.tm_tm_mday++; t.tm_wday++; t.tm_yday++;
+    * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // tuesday
+    * t.tm_tm_mday++; t.tm_wday++; t.tm_yday++;
+    * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // wednesday
+    * t.tm_tm_mday++; t.tm_wday++; t.tm_yday++;
+    * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // thursday
+    * t.tm_tm_mday++; t.tm_wday++; t.tm_yday++;
+    * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // friday
+    * @endcode
+    *
+    * @see elm_calendar_mark_add()
+    *
+    * @ingroup Calendar
+    */
    EINA_DEPRECATED EAPI void               elm_calendar_text_weekday_color_set(Evas_Object *obj, int pos) EINA_ARG_NONNULL(1);
-   /* smart callbacks called:
-    * changed - emitted when the user select a day or change the displayed
-    * month.
+
+   /**
+    * Set the interval on time updates for an user mouse button hold
+    * on calendar widgets' month selection.
+    *
+    * @param obj The calendar object
+    * @param interval The (first) interval value in seconds
+    *
+    * This interval value is @b decreased while the user holds the
+    * mouse pointer either selecting next or previous month.
+    *
+    * This helps the user to get to a given month distant from the
+    * current one easier/faster, as it will start to change quicker and
+    * quicker on mouse button holds.
+    *
+    * The calculation for the next change interval value, starting from
+    * the one set with this call, is the previous interval divided by
+    * 1.05, so it decreases a little bit.
+    *
+    * The default starting interval value for automatic changes is
+    * @b 0.85 seconds.
+    *
+    * @see elm_calendar_interval_get()
+    *
+    * @ingroup Calendar
+    */
+   EAPI void               elm_calendar_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the interval on time updates for an user mouse button hold
+    * on calendar widgets' month selection.
+    *
+    * @param obj The calendar object
+    * @return The (first) interval value, in seconds, set on it
+    *
+    * @see elm_calendar_interval_set() for more details
+    *
+    * @ingroup Calendar
+    */
+   EAPI double             elm_calendar_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * @}
     */
 
    /* diskselector */

legacy/elementary/src/lib/elm_calendar.c

@@ -9,22 +9,6 @@
 #include <Elementary.h>
 #include "elm_priv.h"
 
-/**
- * @defgroup Calendar
- *
- * A calendar is a widget that allows the user to select a date. It has
- * support to adding check marks (holidays and checks by default). The calendar
- * is displayed one month at a time.
- *
- * Weekday names and the function used to format month and year to
- * be displayed can be set, giving more flexibility to this widget.
- *
- * Signals that you can add callbacks for are:
- *
- * "changed" - emitted when the user selects a day or changes the displayed
- *             month, what actually changes the selected day as well.
- */
-
 typedef enum _Day_Color // EINA_DEPRECATED
 {
    DAY_WEEKDAY = 0,
@@ -718,14 +702,6 @@ _event_hook(Evas_Object *obj, Evas_Object *src __UNUSED__, Evas_Callback_Type ty
    return EINA_TRUE;
 }
 
-/**
- * Add a new calendar to the parent
- *
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- *
- * @ingroup Calendar
- */
 EAPI Evas_Object *
 elm_calendar_add(Evas_Object *parent)
 {
@@ -809,30 +785,6 @@ elm_calendar_add(Evas_Object *parent)
    return obj;
 }
 
-/**
- * Set weekdays names to display in the calendar.
- *
- * By default, the following abbreviations are displayed:
- * "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
- * The first string should be related to Sunday, the second to Monday...
- *
- * The usage should be like this:
- * @code
- *   const char *weekdays[] =
- *   {
- *      "Sunday", "Monday", "Tuesday", "Wednesday",
- *      "Thursday", "Friday", "Saturday"
- *   };
- *   elm_calendar_weekdays_names_set(calendar, weekdays);
- * @endcode
- *
- * @param obj The calendar object
- * @param weedays Array of seven strings to be used as weekday names.
- * Warning: it must have 7 elements, or it will access invalid memory.
- * The strings must be NULL terminated ('@\0').
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_weekdays_names_set(Evas_Object *obj, const char *weekdays[])
 {
@@ -850,18 +802,6 @@ elm_calendar_weekdays_names_set(Evas_Object *obj, const char *weekdays[])
    _set_headers(obj);
 }
 
-/**
- * Get weekdays names displayed in the calendar.
- *
- * By default, the following abbreviations are displayed:
- * "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
- * The first string is related to Sunday, the second to Monday...
- *
- * @param obj The calendar object
- * @return Array of seven strings to used as weekday names.
- *
- * @ingroup Calendar
- */
 EAPI const char **
 elm_calendar_weekdays_names_get(const Evas_Object *obj)
 {
@@ -871,18 +811,6 @@ elm_calendar_weekdays_names_get(const Evas_Object *obj)
    return wd->weekdays;
 }
 
-/**
- * Set the interval for the calendar
- *
- * The interval value is decreased while the user increments or decrements
- * the calendar value. The next interval value is the previous interval / 1.05,
- * so it speed up a bit. Default value is 0.85 seconds.
- *
- * @param obj The calendar object
- * @param interval The interval value in seconds
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_interval_set(Evas_Object *obj, double interval)
 {
@@ -892,18 +820,6 @@ elm_calendar_interval_set(Evas_Object *obj, double interval)
    wd->first_interval = interval;
 }
 
-/**
- * Get the interval of the calendar
- *
- * The interval value is decreased while the user increments or decrements
- * the calendar value. The next interval value is the previous interval / 1.05,
- * so it speed up a bit. Default value is 0.85 seconds.
- *
- * @param obj The calendar object
- * @return The value of the first interval in seconds
- *
- * @ingroup Calendar
- */
 EAPI double
 elm_calendar_interval_get(const Evas_Object *obj)
 {
@@ -913,22 +829,6 @@ elm_calendar_interval_get(const Evas_Object *obj)
    return wd->first_interval;
 }
 
-/**
- * Set the minimum and maximum values for the year
- *
- * Maximum must be greater than minimum, except if you don't wan't to set
- * maximum year.
- * Default values are 1902 and -1.
- *
- * If the maximum year is a negative value, it will be limited depending of the
- * platform architecture (2037 for 32 bits);
- *
- * @param obj The calendar object
- * @param min The minimum year, greater than 1901;
- * @param max The maximum year;
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_min_max_year_set(Evas_Object *obj, int min, int max)
 {
@@ -948,20 +848,6 @@ elm_calendar_min_max_year_set(Evas_Object *obj, int min, int max)
    _populate(obj);
 }
 
-/**
- * Get the minimum and maximum values for the year
- *
- * Default values are 1902 and -1.
- *
- * If the maximum year is a negative value, it will be limited depending of the
- * platform architecture (2037 for 32 bits);
- *
- * @param obj The calendar object
- * @param min The minimum year
- * @param max The maximum year
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max)
 {
@@ -972,17 +858,6 @@ elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max)
    if (max) *max = wd->year_max + 1900;
 }
 
-/**
- * Enable or disable day selection
- *
- * Enabled by default. If disabled, the user can select months, but not days.
- * It should be used if you won't need such selection for the widget usage.
- *
- * @param obj The calendar object
- * @param enabled Boolean to enable (true) or disable (false) day selection
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_day_selection_enabled_set(Evas_Object *obj, Eina_Bool enabled)
 {
@@ -996,18 +871,6 @@ elm_calendar_day_selection_enabled_set(Evas_Object *obj, Eina_Bool enabled)
      _unselect(wd, wd->selected_it);
 }
 
-/**
- * Get day selection state
- *
- * Enabled by default. If disabled, the user can select months, but not days.
- * It should be used if you won't need such selection for the widget usage.
- *
- * @param obj The calendar object
- * @return True if day selection is enabled, or false otherwise. It will
- * return false if it can't get widget data.
- *
- * @ingroup Calendar
- */
 EAPI Eina_Bool
 elm_calendar_day_selection_enabled_get(const Evas_Object *obj)
 {
@@ -1017,17 +880,6 @@ elm_calendar_day_selection_enabled_get(const Evas_Object *obj)
    return wd->selection_enabled;
 }
 
-/**
- * Set selected time
- *
- * Set the time selected, changing the displayed month if needed.
- * Selected time changes when the user changes the month or select a day.
- *
- * @param obj The calendar object
- * @param selected_time A tm struct to represent the selected date
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time)
 {
@@ -1041,18 +893,6 @@ elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time)
    return;
 }
 
-/**
- * Get selected time
- *
- * Get the time selected by the user.
- * Selected time changes when the user changes the month or select a day.
- *
- * @param obj The calendar object
- * @param selected_time A tm struct to represent the selected date
- * @return It will return false if it can't get widget data, or true otherwise
- *
- * @ingroup Calendar
- */
 EAPI Eina_Bool
 elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time)
 {
@@ -1064,33 +904,6 @@ elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time)
    return EINA_TRUE;
 }
 
-/**
- * Set a function to format the string that will be used to display
- * month - year
- *
- * By default it uses strftime with "%B %Y" format string.
- * It should allocate the memory that will be used by the string,
- * that will be freed by the widget after usage.
- * A pointer to the string and a pointer to the time struct will be provided.
- *
- * Example:
- * @code
- * static char *
- * _format_month_year(struct tm *selected_time)
- * {
- *    char buf[32];
- *    if (!strftime(buf, sizeof(buf), "%B %Y", selected_time)) return NULL;
- *    return strdup(buf);
- * }
- * elm_calendar_format_function_set(calendar, _format_month_year);
- * @endcode
- *
- * @param obj The calendar object
- * @param format_function Function to set the month-year string given
- * the selected date
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_format_function_set(Evas_Object *obj, char * (*format_function) (struct tm *selected_time))
 {
@@ -1100,46 +913,6 @@ elm_calendar_format_function_set(Evas_Object *obj, char * (*format_function) (st
    wd->format_func = format_function;
 }
 
-/**
- * Add a new mark to the calendar
- *
- * Add a mark that will be drawn in the calendar respecting the insertion time
- * and periodicity. It will emit the type as signal to the widget theme.
- * By default, it supports "holiday" and "checked", but it can be extended.
- *
- * It won't immediately update the calendar, drawing the marks. For this, call
- * elm_calendar_marks_draw().
- *
- * Example
- * @code
- * struct tm selected_time;
- * time_t current_time;
- *
- * current_time = time(NULL) + 5 * 84600;
- * localtime_r(&current_time, &selected_time);
- * elm_calendar_mark_add(cal, "holiday", selected_time, ELM_CALENDAR_ANNUALLY);
- *
- * current_time = time(NULL) + 1 * 84600;
- * localtime_r(&current_time, &selected_time);
- * elm_calendar_mark_add(cal, "checked", selected_time, ELM_CALENDAR_UNIQUE);
- *
- * elm_calendar_marks_draw(cal);
- * @endcode
- *
- * @param obj The calendar object
- * @param mark_type A string used to define the type of mark. It will be
- * emitted to the theme, that should display a related modification on these
- * days representation.
- * @param mark_time A time struct to represent the date of inclusion of the
- * mark. For marks that repeats it will just be displayed after the inclusion
- * date in the calendar.
- * @param repeat Repeat the event following this periodicity. Can be a unique
- * mark (that don't repeat), daily, weekly, monthly or annually.
- *
- * @return The created mark or NULL upon failure
- *
- * @ingroup Calendar
- */
 EAPI Elm_Calendar_Mark *
 elm_calendar_mark_add(Evas_Object *obj, const char *mark_type, struct tm *mark_time, Elm_Calendar_Mark_Repeat repeat)
 {
@@ -1154,13 +927,6 @@ elm_calendar_mark_add(Evas_Object *obj, const char *mark_type, struct tm *mark_t
    return mark;
 }
 
-/**
- * Delete mark from the calendar.
- *
- * @param mark The mark to delete
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_mark_del(Elm_Calendar_Mark *mark)
 {
@@ -1177,13 +943,6 @@ elm_calendar_mark_del(Elm_Calendar_Mark *mark)
    _mark_free(mark);
 }
 
-/**
- * Remove all the marks from the calendar
- *
- * @param obj The calendar object
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_marks_clear(Evas_Object *obj)
 {
@@ -1196,14 +955,6 @@ elm_calendar_marks_clear(Evas_Object *obj)
       _mark_free(mark);
 }
 
-/**
- * Returns a list of all the calendar marks.
- *
- * @param obj The calendar object
- * @return An Eina_List* of the calendar marks, or NULL on failure
- *
- * @ingroup Calendar
- */
 EAPI const Eina_List *
 elm_calendar_marks_get(const Evas_Object *obj)
 {
@@ -1213,20 +964,6 @@ elm_calendar_marks_get(const Evas_Object *obj)
    return wd->marks;
 }
 
-/**
- * Draw calendar marks.
- *
- * Should be used after adding, removing or clearing marks.
- * It will go through the entire marks list updating the calendar
- * (not a cheap function). So if lots of marks will be added,
- * add all the marks and then call this function.
- *
- * When the month is changed marks will be drawed.
- *
- * @param obj The calendar object
- *
- * @ingroup Calendar
- */
 EAPI void
 elm_calendar_marks_draw(Evas_Object *obj)
 {
@@ -1236,21 +973,6 @@ elm_calendar_marks_draw(Evas_Object *obj)
    _populate(obj);
 }
 
-/**
- * Set a text color to the saturday color.
- *
- * Deprecated. use elm_calendar_mark_add() instead like:
- *
- * @code
- * struct tm t = { 0, 0, 12, 6, 0, 0, 5, 5, -1 };
- * elm_calendar_mark_add(obj, "sat", &t, ELM_CALENDAR_WEEKLY);
- * @endcode
- *
- * @param obj The calendar object
- * @param pos The text position
- *
- * @ingroup Calendar
- */
 EINA_DEPRECATED EAPI void
 elm_calendar_text_saturday_color_set(Evas_Object *obj, int pos)
 {
@@ -1260,21 +982,6 @@ elm_calendar_text_saturday_color_set(Evas_Object *obj, int pos)
    _text_day_color_set(wd, DAY_SATURDAY, pos);
 }
 
-/**
- * Set a text color to the sunday color.
- *
- * Deprecated. use elm_calendar_mark_add() instead like:
- *
- * @code
- * struct tm t = { 0, 0, 12, 7, 0, 0, 6, 6, -1 };
- * elm_calendar_mark_add(obj, "sun", &t, ELM_CALENDAR_WEEKLY);
- * @endcode
- *
- * @param obj The calendar object
- * @param pos The text position
- *
- * @ingroup Calendar
- */
 EINA_DEPRECATED EAPI void
 elm_calendar_text_sunday_color_set(Evas_Object *obj, int pos)
 {
@@ -1284,30 +991,6 @@ elm_calendar_text_sunday_color_set(Evas_Object *obj, int pos)
    _text_day_color_set(wd, DAY_SUNDAY, pos);
 }
 
-/**
- * Set a text color to the weekday color.
- *
- * Deprecated. use elm_calendar_mark_add() instead like:
- *
- * @code
- * struct tm t = { 0, 0, 12, 1, 0, 0, 0, 0, -1 };
- *
- * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // monday
- * t.tm_tm_mday++; t.tm_wday++; t.tm_yday++;
- * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // tuesday
- * t.tm_tm_mday++; t.tm_wday++; t.tm_yday++;
- * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // wednesday
- * t.tm_tm_mday++; t.tm_wday++; t.tm_yday++;
- * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // thursday
- * t.tm_tm_mday++; t.tm_wday++; t.tm_yday++;
- * elm_calendar_mark_add(obj, "week", &t, ELM_CALENDAR_WEEKLY); // friday
- * @endcode
- *
- * @param obj The calendar object
- * @param pos The text position
- *
- * @ingroup Calendar
- */
 EINA_DEPRECATED EAPI void
 elm_calendar_text_weekday_color_set(Evas_Object *obj, int pos)
 {