src/lib/elm_calendar.h

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