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