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