src/lib/elm_calendar.h

   1 /**
   2  * @defgroup Calendar Calendar
   3  * @ingroup Elementary
   4  *
   5  * This is a Calendar widget. Calender widget helps applications to flexibly
   6  * display a calender with day of the week, day, year and month. Applications will be
   7  * able to choose a specific date that will be reported in the smart_callbacks for
   8  * the calendar widget. The APIs of calendar widget let the applications perform
   9  * other functions like,
  10  * placing marks on specific dates
  11  * Setting the bounds for the calendar (minimum and maximum years)
  12  * Setting the day names of the week. ( for ex. Thu. or Thursday)
  13  * Setting the year and month format.
  14  *
  15  * Signals that you can add callbacks for are:
  16  * - @c "changed" - emitted when the date in the calendar is changed.
  17  *
  18  * Supported elm_object common APIs.
  19  * @li @ref elm_object_signal_emit
  20  * @li @ref elm_object_signal_callback_add
  21  * @li @ref elm_object_signal_callback_del
  22  *
  23  * Here is some sample code using it:
  24  * @li @ref calendar_example_01
  25  * @li @ref calendar_example_02
  26  * @li @ref calendar_example_03
  27  * @li @ref calendar_example_04
  28  * @li @ref calendar_example_05
  29  * @li @ref calendar_example_06
  30  */
  31
  32 /**
  33  * @addtogroup Calendar
  34  * @{
  35  */
  36
  37 typedef enum
  38 {
  39    ELM_CALENDAR_UNIQUE, /**< Default value. Marks will be displayed only on event day. */
  40    ELM_CALENDAR_DAILY, /**< Marks will be displayed every day after event day (inclusive). */
  41    ELM_CALENDAR_WEEKLY, /**< Marks will be displayed every week after event day (inclusive) - i.e. each seven days. */
  42    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*/
  43    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. */
  44 } _Elm_Calendar_Mark_Repeat_Type;
  45
  46 /**
  47  * @enum _Elm_Calendar_Mark_Repeat_Type
  48  * @typedef Elm_Calendar_Mark_Repeat_Type
  49  *
  50  * Event periodicity, used to define if a mark should be repeated
  51  * @b beyond event's day. It's set when a mark is added.
  52  *
  53  * So, for a mark added to 13th May with periodicity set to WEEKLY,
  54  * there will be marks every week after this date. Marks will be displayed
  55  * at 13th, 20th, 27th, 3rd June ...
  56  *
  57  * Values don't work as bitmask, only one can be chosen.
  58  *
  59  * @see elm_calendar_mark_add()
  60  *
  61  * @ingroup Calendar
  62  */
  63 typedef _Elm_Calendar_Mark_Repeat_Type Elm_Calendar_Mark_Repeat_Type;
  64
  65 typedef enum
  66 {
  67    ELM_DAY_SUNDAY,
  68    ELM_DAY_MONDAY,
  69    ELM_DAY_TUESDAY,
  70    ELM_DAY_WEDNESDAY,
  71    ELM_DAY_THURSDAY,
  72    ELM_DAY_FRIDAY,
  73    ELM_DAY_SATURDAY,
  74    ELM_DAY_LAST
  75 } _Elm_Calendar_Weekday;
  76
  77 /**
  78  * @enum _Elm_Calendar_Weekday
  79  * @typedef Elm_Calendar_Weekday
  80  *
  81  * a weekday
  82  *
  83  * @see elm_calendar_first_day_of_week_set()
  84  *
  85  * @ingroup Calendar
  86  */
  87 typedef _Elm_Calendar_Weekday Elm_Calendar_Weekday;
  88
  89
  90 typedef enum
  91 {
  92    ELM_CALENDAR_SELECT_MODE_DEFAULT = 0, /**< Default value. a day is always selected. */
  93    ELM_CALENDAR_SELECT_MODE_ALWAYS, /**< a day is always selected. */
  94    ELM_CALENDAR_SELECT_MODE_NONE, /**< None of the days can be selected. */
  95    ELM_CALENDAR_SELECT_MODE_ONDEMAND /**< User may have selected a day or not. (not supported yet)*/
  96 } _Elm_Calendar_Select_Mode;
  97
  98 /**
  99  * @enum _Elm_Calendar_Select_Mode
 100  * @typedef Elm_Calendar_Select_Mode
 101  *
 102  * the mode, who determine how user could select a day
 103  *
 104  * @see elm_calendar_select_mode_set()
 105  *
 106  * @ingroup Calendar
 107  */
 108 typedef _Elm_Calendar_Select_Mode Elm_Calendar_Select_Mode;
 109
 110 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(). */
 111
 112 /**
 113  * @typedef Elm_Calendar_Format_Cb
 114  *
 115  * This callback type is used to format the string that will be used
 116  * to display month and year.
 117  *
 118  * @param stime Struct representing time.
 119  * @return String representing time that will be set to calendar's text.
 120  *
 121  * @see elm_calendar_format_function_set()
 122  *
 123  * @ingroup Calendar
 124  */
 125 typedef char * (*Elm_Calendar_Format_Cb)(struct tm *stime);
 126
 127 /**
 128  * Add a new calendar widget to the given parent Elementary
 129  * (container) object.
 130  *
 131  * @param parent The parent object.
 132  * @return a new calendar widget handle or @c NULL, on errors.
 133  *
 134  * This function inserts a new calendar widget on the canvas.
 135  *
 136  * @ref calendar_example_01
 137  *
 138  * @ingroup Calendar
 139  */
 140 EAPI Evas_Object         *elm_calendar_add(Evas_Object *parent);
 141
 142 /**
 143  * Get weekdays names displayed by the calendar.
 144  *
 145  * @param obj The calendar object.
 146  * @return Array of seven strings to be used as weekday names.
 147  *
 148  * By default, weekdays abbreviations get from system are displayed:
 149  * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
 150  * The first string is related to Sunday, the second to Monday...
 151  *
 152  * @see elm_calendar_weekdays_name_set()
 153  *
 154  * @ref calendar_example_05
 155  *
 156  * @ingroup Calendar
 157  */
 158 EAPI const char         **elm_calendar_weekdays_names_get(const Evas_Object *obj);
 159
 160 /**
 161  * Set weekdays names to be displayed by the calendar.
 162  *
 163  * @param obj The calendar object.
 164  * @param weekdays Array of seven strings to be used as weekday names.
 165  * @warning It must have 7 elements, or it will access invalid memory.
 166  * @warning The strings must be NULL terminated ('@\0').
 167  *
 168  * By default, weekdays abbreviations get from system are displayed:
 169  * E.g. for an en_US locale: "Sun, Mon, Tue, Wed, Thu, Fri, Sat"
 170  *
 171  * The first string should be related to Sunday, the second to Monday...
 172  *
 173  * The usage should be like this:
 174  * @code
 175  *   const char *weekdays[] =
 176  *   {
 177  *      "Sunday", "Monday", "Tuesday", "Wednesday",
 178  *      "Thursday", "Friday", "Saturday"
 179  *   };
 180  *   elm_calendar_weekdays_names_set(calendar, weekdays);
 181  * @endcode
 182  *
 183  * @see elm_calendar_weekdays_name_get()
 184  *
 185  * @ref calendar_example_02
 186  *
 187  * @ingroup Calendar
 188  */
 189 EAPI void                 elm_calendar_weekdays_names_set(Evas_Object *obj, const char *weekdays[]);
 190
 191 /**
 192  * Set the minimum and maximum values for the year
 193  *
 194  * @param obj The calendar object
 195  * @param min The minimum year, greater than 1901;
 196  * @param max The maximum year;
 197  *
 198  * Maximum must be greater than minimum, except if you don't want to set
 199  * maximum year.
 200  * Default values are 1902 and -1.
 201  *
 202  * If the maximum year is a negative value, it will be limited depending
 203  * on the platform architecture (year 2037 for 32 bits);
 204  *
 205  * @see elm_calendar_min_max_year_get()
 206  *
 207  * @ref calendar_example_03
 208  *
 209  * @ingroup Calendar
 210  */
 211 EAPI void                 elm_calendar_min_max_year_set(Evas_Object *obj, int min, int max);
 212
 213 /**
 214  * Get the minimum and maximum values for the year
 215  *
 216  * @param obj The calendar object.
 217  * @param min The minimum year.
 218  * @param max The maximum year.
 219  *
 220  * Default values are 1902 and -1.
 221  *
 222  * @see elm_calendar_min_max_year_get() for more details.
 223  *
 224  * @ref calendar_example_05
 225  *
 226  * @ingroup Calendar
 227  */
 228 EAPI void                 elm_calendar_min_max_year_get(const Evas_Object *obj, int *min, int *max);
 229
 230 /**
 231  * Set select day mode to use.
 232  *
 233  * @param obj The calendar object.
 234  * @param select_mdoe The select mode to use.
 235  *
 236  * Set the day selection mode used.
 237  *
 238  * @ingroup Calendar
 239  */
 240 EAPI void                 elm_calendar_select_mode_set(Evas_Object *obj, Elm_Calendar_Select_Mode mode);
 241
 242 /**
 243  * Get the select day mode used.
 244  *
 245  * @param obj The calendar object.
 246  *
 247  * @return the selected mode
 248  *
 249  * Get the day selection mode used.
 250  *
 251  * @see elm_calendar_select_mode_set() for more details
 252  *
 253  * @ingroup Calendar
 254  */
 255 EAPI Elm_Calendar_Select_Mode elm_calendar_select_mode_get(const Evas_Object *obj);
 256
 257 /**
 258  * Set selected date to be highlighted on calendar.
 259  *
 260  * @param obj The calendar object.
 261  * @param selected_time A @b tm struct to represent the selected date.
 262  *
 263  * Set the selected date, changing the displayed month if needed.
 264  * Selected date changes when the user goes to next/previous month or
 265  * select a day pressing over it on calendar.
 266  *
 267  * @see elm_calendar_selected_time_get()
 268  *
 269  * @ref calendar_example_04
 270  *
 271  * @ingroup Calendar
 272  */
 273 EAPI void                 elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time);
 274
 275 /**
 276  * Get selected date.
 277  *
 278  * @param obj The calendar object
 279  * @param selected_time A @b tm struct to point to selected date
 280  * @return EINA_FALSE means an error occurred and returned time shouldn't
 281  * be considered.
 282  *
 283  * Get date selected by the user or set by function
 284  * elm_calendar_selected_time_set().
 285  * Selected date changes when the user goes to next/previous month or
 286  * select a day pressing over it on calendar.
 287  *
 288  * @see elm_calendar_selected_time_get()
 289  *
 290  * @ref calendar_example_05
 291  *
 292  * @ingroup Calendar
 293  */
 294 EAPI Eina_Bool            elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time);
 295
 296 /**
 297  * Set a function to format the string that will be used to display
 298  * month and year;
 299  *
 300  * @param obj The calendar object
 301  * @param format_func Function to set the month-year string given
 302  * the selected date
 303  *
 304  * By default it uses strftime with "%B %Y" format string.
 305  * It should allocate the memory that will be used by the string,
 306  * that will be freed by the widget after usage.
 307  * A pointer to the string and a pointer to the time struct will be provided.
 308  *
 309  * Example:
 310  * @code
 311  * static char *
 312  * _format_month_year(struct tm *selected_time)
 313  * {
 314  *    char buf[32];
 315  *    if (!strftime(buf, sizeof(buf), "%B %Y", selected_time)) return NULL;
 316  *    return strdup(buf);
 317  * }
 318  *
 319  * elm_calendar_format_function_set(calendar, _format_month_year);
 320  * @endcode
 321  *
 322  * @ref calendar_example_02
 323  *
 324  * @ingroup Calendar
 325  */
 326 EAPI void                 elm_calendar_format_function_set(Evas_Object *obj, Elm_Calendar_Format_Cb format_func);
 327
 328 /**
 329  * Add a new mark to the calendar
 330  *
 331  * @param obj The calendar object
 332  * @param mark_type A string used to define the type of mark. It will be
 333  * emitted to the theme, that should display a related modification on these
 334  * days representation.
 335  * @param mark_time A time struct to represent the date of inclusion of the
 336  * mark. For marks that repeats it will just be displayed after the inclusion
 337  * date in the calendar.
 338  * @param repeat Repeat the event following this periodicity. Can be a unique
 339  * mark (that don't repeat), daily, weekly, monthly or annually.
 340  * @return The created mark or @p NULL upon failure.
 341  *
 342  * Add a mark that will be drawn in the calendar respecting the insertion
 343  * time and periodicity. It will emit the type as signal to the widget theme.
 344  * Default theme supports "holiday" and "checked", but it can be extended.
 345  *
 346  * It won't immediately update the calendar, drawing the marks.
 347  * For this, call elm_calendar_marks_draw(). However, when user selects
 348  * next or previous month calendar forces marks drawn.
 349  *
 350  * Marks created with this method can be deleted with
 351  * elm_calendar_mark_del().
 352  *
 353  * Example
 354  * @code
 355  * struct tm selected_time;
 356  * time_t current_time;
 357  *
 358  * current_time = time(NULL) + 5 * 84600;
 359  * localtime_r(&current_time, &selected_time);
 360  * elm_calendar_mark_add(cal, "holiday", selected_time,
 361  *     ELM_CALENDAR_ANNUALLY);
 362  *
 363  * current_time = time(NULL) + 1 * 84600;
 364  * localtime_r(&current_time, &selected_time);
 365  * elm_calendar_mark_add(cal, "checked", selected_time, ELM_CALENDAR_UNIQUE);
 366  *
 367  * elm_calendar_marks_draw(cal);
 368  * @endcode
 369  *
 370  * @see elm_calendar_marks_draw()
 371  * @see elm_calendar_mark_del()
 372  *
 373  * @ref calendar_example_06
 374  *
 375  * @ingroup Calendar
 376  */
 377 EAPI Elm_Calendar_Mark   *elm_calendar_mark_add(Evas_Object *obj, const char *mark_type, struct tm *mark_time, Elm_Calendar_Mark_Repeat_Type repeat);
 378
 379 /**
 380  * Delete mark from the calendar.
 381  *
 382  * @param mark The mark to be deleted.
 383  *
 384  * If deleting all calendar marks is required, elm_calendar_marks_clear()
 385  * should be used instead of getting marks list and deleting each one.
 386  *
 387  * @see elm_calendar_mark_add()
 388  *
 389  * @ref calendar_example_06
 390  *
 391  * @ingroup Calendar
 392  */
 393 EAPI void                 elm_calendar_mark_del(Elm_Calendar_Mark *mark);
 394
 395 /**
 396  * Remove all calendar's marks
 397  *
 398  * @param obj The calendar object.
 399  *
 400  * @see elm_calendar_mark_add()
 401  * @see elm_calendar_mark_del()
 402  *
 403  * @ingroup Calendar
 404  */
 405 EAPI void                 elm_calendar_marks_clear(Evas_Object *obj);
 406
 407 /**
 408  * Get a list of all the calendar marks.
 409  *
 410  * @param obj The calendar object.
 411  * @return An @c Eina_List of calendar marks objects, or @c NULL on failure.
 412  *
 413  * @see elm_calendar_mark_add()
 414  * @see elm_calendar_mark_del()
 415  * @see elm_calendar_marks_clear()
 416  *
 417  * @ingroup Calendar
 418  */
 419 EAPI const Eina_List     *elm_calendar_marks_get(const Evas_Object *obj);
 420
 421 /**
 422  * Draw calendar marks.
 423  *
 424  * @param obj The calendar object.
 425  *
 426  * Should be used after adding, removing or clearing marks.
 427  * It will go through the entire marks list updating the calendar.
 428  * If lots of marks will be added, add all the marks and then call
 429  * this function.
 430  *
 431  * When the month is changed, i.e. user selects next or previous month,
 432  * marks will be drawn.
 433  *
 434  * @see elm_calendar_mark_add()
 435  * @see elm_calendar_mark_del()
 436  * @see elm_calendar_marks_clear()
 437  *
 438  * @ref calendar_example_06
 439  *
 440  * @ingroup Calendar
 441  */
 442 EAPI void                 elm_calendar_marks_draw(Evas_Object *obj);
 443
 444 /**
 445  * Set the interval on time updates for an user mouse button hold
 446  * on calendar widgets' month selection.
 447  *
 448  * @param obj The calendar object
 449  * @param interval The (first) interval value in seconds
 450  *
 451  * This interval value is @b decreased while the user holds the
 452  * mouse pointer either selecting next or previous month.
 453  *
 454  * This helps the user to get to a given month distant from the
 455  * current one easier/faster, as it will start to change quicker and
 456  * quicker on mouse button holds.
 457  *
 458  * The calculation for the next change interval value, starting from
 459  * the one set with this call, is the previous interval divided by
 460  * 1.05, so it decreases a little bit.
 461  *
 462  * The default starting interval value for automatic changes is
 463  * @b 0.85 seconds.
 464  *
 465  * @see elm_calendar_interval_get()
 466  *
 467  * @ingroup Calendar
 468  */
 469 EAPI void                 elm_calendar_interval_set(Evas_Object *obj, double interval);
 470
 471 /**
 472  * Get the interval on time updates for an user mouse button hold
 473  * on calendar widgets' month selection.
 474  *
 475  * @param obj The calendar object
 476  * @return The (first) interval value, in seconds, set on it
 477  *
 478  * @see elm_calendar_interval_set() for more details
 479  *
 480  * @ingroup Calendar
 481  */
 482 EAPI double               elm_calendar_interval_get(const Evas_Object *obj);
 483
 484 /**
 485  * Set the first day of week to use on calendar widgets'.
 486  *
 487  * @param obj The calendar object
 488  * @param day An int which correspond to the first day of the week (Sunday = 0, monday = 1,
 489  * ..., saturday = 6)
 490  *
 491  * @ingroup Calendar
 492  */
 493 EAPI void                 elm_calendar_first_day_of_week_set(Evas_Object *obj, Elm_Calendar_Weekday day);
 494
 495 /**
 496  * Get the first day of week, who are used on calendar widgets'.
 497  *
 498  * @param obj The calendar object
 499  * @return An int which correspond to the first day of the week (Sunday = 0, monday = 1,
 500  * ..., saturday = 6)
 501  *
 502  * @see elm_calendar_first_day_of_week_set() for more details
 503  *
 504  * @ingroup Calendar
 505  */
 506 EAPI Elm_Calendar_Weekday elm_calendar_first_day_of_week_get(const Evas_Object *obj);
 507
 508 /**
 509  * @}
 510  */