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