EFL migration revision 67547
[framework/uifw/elementary.git] / 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  */