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