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