src/lib/elm_calendar.h

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