src/lib/elm_calendar.h

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