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
  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  * Set selected date to be highlighted on calendar.
 176  *
 177  * @param obj The calendar object.
 178  * @param selected_time A @b tm struct to represent the selected date.
 179  *
 180  * Set the selected date, changing the displayed month if needed.
 181  * Selected date changes when the user goes to next/previous month or
 182  * select a day pressing over it on calendar.
 183  *
 184  * @see elm_calendar_selected_time_get()
 185  *
 186  * @ref calendar_example_04
 187  *
 188  * @ingroup Calendar
 189  */
 190 EAPI void                 elm_calendar_selected_time_set(Evas_Object *obj, struct tm *selected_time) EINA_ARG_NONNULL(1);
 191
 192 /**
 193  * Get selected date.
 194  *
 195  * @param obj The calendar object
 196  * @param selected_time A @b tm struct to point to selected date
 197  * @return EINA_FALSE means an error ocurred and returned time shouldn't
 198  * be considered.
 199  *
 200  * Get date selected by the user or set by function
 201  * elm_calendar_selected_time_set().
 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_05
 208  *
 209  * @ingroup Calendar
 210  */
 211 EAPI Eina_Bool            elm_calendar_selected_time_get(const Evas_Object *obj, struct tm *selected_time) EINA_ARG_NONNULL(1, 2);
 212
 213 /**
 214  * Set a function to format the string that will be used to display
 215  * month and year;
 216  *
 217  * @param obj The calendar object
 218  * @param format_function Function to set the month-year string given
 219  * the selected date
 220  *
 221  * By default it uses strftime with "%B %Y" format string.
 222  * It should allocate the memory that will be used by the string,
 223  * that will be freed by the widget after usage.
 224  * A pointer to the string and a pointer to the time struct will be provided.
 225  *
 226  * Example:
 227  * @code
 228  * static char *
 229  * _format_month_year(struct tm *selected_time)
 230  * {
 231  *    char buf[32];
 232  *    if (!strftime(buf, sizeof(buf), "%B %Y", selected_time)) return NULL;
 233  *    return strdup(buf);
 234  * }
 235  *
 236  * elm_calendar_format_function_set(calendar, _format_month_year);
 237  * @endcode
 238  *
 239  * @ref calendar_example_02
 240  *
 241  * @ingroup Calendar
 242  */
 243 EAPI void                 elm_calendar_format_function_set(Evas_Object *obj, char *(*format_function)(struct tm *stime)) EINA_ARG_NONNULL(1);
 244
 245 /**
 246  * Add a new mark to the calendar
 247  *
 248  * @param obj The calendar object
 249  * @param mark_type A string used to define the type of mark. It will be
 250  * emitted to the theme, that should display a related modification on these
 251  * days representation.
 252  * @param mark_time A time struct to represent the date of inclusion of the
 253  * mark. For marks that repeats it will just be displayed after the inclusion
 254  * date in the calendar.
 255  * @param repeat Repeat the event following this periodicity. Can be a unique
 256  * mark (that don't repeat), daily, weekly, monthly or annually.
 257  * @return The created mark or @p NULL upon failure.
 258  *
 259  * Add a mark that will be drawn in the calendar respecting the insertion
 260  * time and periodicity. It will emit the type as signal to the widget theme.
 261  * Default theme supports "holiday" and "checked", but it can be extended.
 262  *
 263  * It won't immediately update the calendar, drawing the marks.
 264  * For this, call elm_calendar_marks_draw(). However, when user selects
 265  * next or previous month calendar forces marks drawn.
 266  *
 267  * Marks created with this method can be deleted with
 268  * elm_calendar_mark_del().
 269  *
 270  * Example
 271  * @code
 272  * struct tm selected_time;
 273  * time_t current_time;
 274  *
 275  * current_time = time(NULL) + 5 * 84600;
 276  * localtime_r(&current_time, &selected_time);
 277  * elm_calendar_mark_add(cal, "holiday", selected_time,
 278  *     ELM_CALENDAR_ANNUALLY);
 279  *
 280  * current_time = time(NULL) + 1 * 84600;
 281  * localtime_r(&current_time, &selected_time);
 282  * elm_calendar_mark_add(cal, "checked", selected_time, ELM_CALENDAR_UNIQUE);
 283  *
 284  * elm_calendar_marks_draw(cal);
 285  * @endcode
 286  *
 287  * @see elm_calendar_marks_draw()
 288  * @see elm_calendar_mark_del()
 289  *
 290  * @ref calendar_example_06
 291  *
 292  * @ingroup Calendar
 293  */
 294 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);
 295
 296 /**
 297  * Delete mark from the calendar.
 298  *
 299  * @param mark The mark to be deleted.
 300  *
 301  * If deleting all calendar marks is required, elm_calendar_marks_clear()
 302  * should be used instead of getting marks list and deleting each one.
 303  *
 304  * @see elm_calendar_mark_add()
 305  *
 306  * @ref calendar_example_06
 307  *
 308  * @ingroup Calendar
 309  */
 310 EAPI void                 elm_calendar_mark_del(Elm_Calendar_Mark *mark) EINA_ARG_NONNULL(1);
 311
 312 /**
 313  * Remove all calendar's marks
 314  *
 315  * @param obj The calendar object.
 316  *
 317  * @see elm_calendar_mark_add()
 318  * @see elm_calendar_mark_del()
 319  *
 320  * @ingroup Calendar
 321  */
 322 EAPI void                 elm_calendar_marks_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
 323
 324 /**
 325  * Get a list of all the calendar marks.
 326  *
 327  * @param obj The calendar object.
 328  * @return An @c Eina_List of calendar marks objects, or @c NULL on failure.
 329  *
 330  * @see elm_calendar_mark_add()
 331  * @see elm_calendar_mark_del()
 332  * @see elm_calendar_marks_clear()
 333  *
 334  * @ingroup Calendar
 335  */
 336 EAPI const Eina_List     *elm_calendar_marks_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 337
 338 /**
 339  * Draw calendar marks.
 340  *
 341  * @param obj The calendar object.
 342  *
 343  * Should be used after adding, removing or clearing marks.
 344  * It will go through the entire marks list updating the calendar.
 345  * If lots of marks will be added, add all the marks and then call
 346  * this function.
 347  *
 348  * When the month is changed, i.e. user selects next or previous month,
 349  * marks will be drawed.
 350  *
 351  * @see elm_calendar_mark_add()
 352  * @see elm_calendar_mark_del()
 353  * @see elm_calendar_marks_clear()
 354  *
 355  * @ref calendar_example_06
 356  *
 357  * @ingroup Calendar
 358  */
 359 EAPI void                 elm_calendar_marks_draw(Evas_Object *obj) EINA_ARG_NONNULL(1);
 360
 361 /**
 362  * Set the interval on time updates for an user mouse button hold
 363  * on calendar widgets' month selection.
 364  *
 365  * @param obj The calendar object
 366  * @param interval The (first) interval value in seconds
 367  *
 368  * This interval value is @b decreased while the user holds the
 369  * mouse pointer either selecting next or previous month.
 370  *
 371  * This helps the user to get to a given month distant from the
 372  * current one easier/faster, as it will start to change quicker and
 373  * quicker on mouse button holds.
 374  *
 375  * The calculation for the next change interval value, starting from
 376  * the one set with this call, is the previous interval divided by
 377  * 1.05, so it decreases a little bit.
 378  *
 379  * The default starting interval value for automatic changes is
 380  * @b 0.85 seconds.
 381  *
 382  * @see elm_calendar_interval_get()
 383  *
 384  * @ingroup Calendar
 385  */
 386 EAPI void                 elm_calendar_interval_set(Evas_Object *obj, double interval) EINA_ARG_NONNULL(1);
 387
 388 /**
 389  * Get the interval on time updates for an user mouse button hold
 390  * on calendar widgets' month selection.
 391  *
 392  * @param obj The calendar object
 393  * @return The (first) interval value, in seconds, set on it
 394  *
 395  * @see elm_calendar_interval_set() for more details
 396  *
 397  * @ingroup Calendar
 398  */
 399 EAPI double               elm_calendar_interval_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 400
 401 /**
 402  * @}
 403  */