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