src/lib/elm_calendar.h

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