src/lib/elm_calendar.h

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