2012-02-27 05:59:49 -08:00
/**
* @ defgroup Calendar Calendar
2012-04-16 18:35:46 -07:00
* @ ingroup Elementary
2012-02-27 05:59:49 -08:00
*
2012-06-05 15:41:21 -07:00
* @ image html calendar_inheritance_tree . png
* @ image latex calendar_inheritance_tree . eps
*
2012-05-03 15:41:58 -07:00
* This is a calendar widget . It helps applications to flexibly
* display a calender with day of the week , date , year and
* month . Applications are able to set specific dates to be reported
* back , when selected , in the smart callbacks of the calendar
* widget . The API of this widget lets the applications perform other
* functions , like :
2012-02-27 05:59:49 -08:00
*
2012-05-03 15:41:58 -07:00
* - placing marks on specific dates
* - setting the bounds for the calendar ( minimum and maximum years )
* - setting the day names of the week ( e . g . " Thu " or " Thursday " )
* - setting the year and month format .
*
* This widget inherits from the @ ref Layout one , so that all the
* functions acting on it also work for calendar objects .
*
* This widget emits the following signals , besides the ones sent from
* @ ref Layout :
2012-02-28 23:54:57 -08:00
* - @ c " changed " - emitted when the date in the calendar is changed .
2012-02-27 05:59:49 -08:00
*
* Supported elm_object common APIs .
2012-04-17 13:33:59 -07:00
* @ li @ ref elm_object_signal_emit
* @ li @ ref elm_object_signal_callback_add
* @ li @ ref elm_object_signal_callback_del
2012-02-27 05:59:49 -08:00
*
2012-03-21 10:57:27 -07:00
* Here is some sample code using it :
* @ li @ ref calendar_example_01
* @ li @ ref calendar_example_02
* @ li @ ref calendar_example_03
* @ li @ ref calendar_example_04
* @ li @ ref calendar_example_05
* @ li @ ref calendar_example_06
2012-02-27 05:59:49 -08:00
*/
2011-12-29 23:20:48 -08:00
/**
* @ addtogroup Calendar
* @ {
*/
2011-12-29 22:49:28 -08:00
2012-02-29 19:38:56 -08:00
typedef enum
{
ELM_CALENDAR_UNIQUE , /**< Default value. Marks will be displayed only on event day. */
2012-03-04 21:31:49 -08:00
ELM_CALENDAR_DAILY , /**< Marks will be displayed every day after event day (inclusive). */
2012-02-29 19:38:56 -08:00
ELM_CALENDAR_WEEKLY , /**< Marks will be displayed every week after event day (inclusive) - i.e. each seven days. */
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*/
2012-06-14 10:10:31 -07:00
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. */
2012-07-09 03:20:21 -07:00
ELM_CALENDAR_LAST_DAY_OF_MONTH /**< Marks will be displayed every last day of month after event day (inclusive). @since 1.7 */
2012-02-29 19:38:56 -08:00
} _Elm_Calendar_Mark_Repeat_Type ;
2011-12-29 23:20:48 -08:00
/**
2012-02-29 19:38:56 -08:00
* @ enum _Elm_Calendar_Mark_Repeat_Type
* @ typedef Elm_Calendar_Mark_Repeat_Type
2011-12-29 23:20:48 -08:00
*
* Event periodicity , used to define if a mark should be repeated
* @ b beyond event ' s day . It ' s set when a mark is added .
*
* So , for a mark added to 13 th May with periodicity set to WEEKLY ,
* there will be marks every week after this date . Marks will be displayed
* at 13 th , 20 th , 27 th , 3 rd June . . .
*
2012-02-14 00:50:26 -08:00
* Values don ' t work as bitmask , only one can be chosen .
2011-12-29 23:20:48 -08:00
*
* @ see elm_calendar_mark_add ( )
*
* @ ingroup Calendar
*/
2012-02-29 19:38:56 -08:00
typedef _Elm_Calendar_Mark_Repeat_Type Elm_Calendar_Mark_Repeat_Type ;
2011-12-29 22:49:28 -08:00
2012-03-29 15:59:11 -07:00
typedef enum
{
ELM_DAY_SUNDAY ,
ELM_DAY_MONDAY ,
ELM_DAY_TUESDAY ,
ELM_DAY_WEDNESDAY ,
ELM_DAY_THURSDAY ,
ELM_DAY_FRIDAY ,
ELM_DAY_SATURDAY ,
ELM_DAY_LAST
} _Elm_Calendar_Weekday ;
/**
* @ enum _Elm_Calendar_Weekday
* @ typedef Elm_Calendar_Weekday
*
* a weekday
*
* @ see elm_calendar_first_day_of_week_set ( )
*
* @ ingroup Calendar
*/
typedef _Elm_Calendar_Weekday Elm_Calendar_Weekday ;
2012-04-19 01:46:22 -07:00
typedef enum
{
2012-04-19 02:03:59 -07:00
ELM_CALENDAR_SELECT_MODE_DEFAULT = 0 , /**< Default value. a day is always selected. */
ELM_CALENDAR_SELECT_MODE_ALWAYS , /**< a day is always selected. */
ELM_CALENDAR_SELECT_MODE_NONE , /**< None of the days can be selected. */
2012-04-24 16:07:36 -07:00
ELM_CALENDAR_SELECT_MODE_ONDEMAND /**< User may have selected a day or not. */
2012-04-19 01:46:22 -07:00
} _Elm_Calendar_Select_Mode ;
/**
* @ enum _Elm_Calendar_Select_Mode
* @ typedef Elm_Calendar_Select_Mode
*
* the mode , who determine how user could select a day
*
* @ see elm_calendar_select_mode_set ( )
*
* @ ingroup Calendar
*/
typedef _Elm_Calendar_Select_Mode Elm_Calendar_Select_Mode ;
2012-09-11 14:33:54 -07:00
typedef enum
{
ELM_CALENDAR_SELECTABLE_NONE = 0 ,
ELM_CALENDAR_SELECTABLE_YEAR = ( 1 < < 0 ) ,
ELM_CALENDAR_SELECTABLE_MONTH = ( 1 < < 1 ) ,
ELM_CALENDAR_SELECTABLE_DAY = ( 1 < < 2 )
} _Elm_Calendar_Selectable ;
/**
* @ enum _Elm_Calendar_Selectable
* @ typedef Elm_Calendar_Selectable
*
* A bitmask used to define which fields of a @ b tm struct will be taken into
* account , when elm_calendar_selected_time_set ( ) is invoked .
*
* @ ingroup Calendar
* @ see elm_calendar_selectable_set ( )
* @ see elm_calendar_selected_time_set ( )
* @ since 1.8
*/
typedef _Elm_Calendar_Selectable Elm_Calendar_Selectable ;
2011-12-29 23:20:48 -08:00
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(). */
2011-12-29 22:49:28 -08:00
2012-03-06 17:02:21 -08:00
/**
* @ typedef Elm_Calendar_Format_Cb
*
* This callback type is used to format the string that will be used
* to display month and year .
*
* @ param stime Struct representing time .
2012-03-07 08:42:34 -08:00
* @ return String representing time that will be set to calendar ' s text .
2012-03-06 17:02:21 -08:00
*
* @ see elm_calendar_format_function_set ( )
2012-04-16 18:35:46 -07:00
*
* @ ingroup Calendar
2012-03-06 17:02:21 -08:00
*/
typedef char * ( * Elm_Calendar_Format_Cb ) ( struct tm * stime ) ;
2011-12-29 23:20:48 -08:00
/**
* Add a new calendar widget to the given parent Elementary
* ( container ) object .
*
* @ param parent The parent object .
* @ return a new calendar widget handle or @ c NULL , on errors .
*
* This function inserts a new calendar widget on the canvas .
*
* @ ref calendar_example_01
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI Evas_Object * elm_calendar_add ( Evas_Object * parent ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Get weekdays names displayed by the calendar .
*
* @ param obj The calendar object .
* @ return Array of seven strings to be used as weekday names .
*
* By default , weekdays abbreviations get from system are displayed :
* E . g . for an en_US locale : " Sun, Mon, Tue, Wed, Thu, Fri, Sat "
* The first string is related to Sunday , the second to Monday . . .
*
* @ see elm_calendar_weekdays_name_set ( )
*
* @ ref calendar_example_05
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI const char * * elm_calendar_weekdays_names_get ( const Evas_Object * obj ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Set weekdays names to be displayed by the calendar .
*
* @ param obj The calendar object .
* @ param weekdays Array of seven strings to be used as weekday names .
* @ warning It must have 7 elements , or it will access invalid memory .
* @ warning The strings must be NULL terminated ( ' @ \ 0 ' ) .
*
* By default , weekdays abbreviations get from system are displayed :
* E . g . for an en_US locale : " Sun, Mon, Tue, Wed, Thu, Fri, Sat "
*
* The first string should be related to Sunday , the second to Monday . . .
*
* The usage should be like this :
* @ code
* const char * weekdays [ ] =
* {
* " Sunday " , " Monday " , " Tuesday " , " Wednesday " ,
* " Thursday " , " Friday " , " Saturday "
* } ;
* elm_calendar_weekdays_names_set ( calendar , weekdays ) ;
* @ endcode
*
* @ see elm_calendar_weekdays_name_get ( )
*
* @ ref calendar_example_02
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI void elm_calendar_weekdays_names_set ( Evas_Object * obj , const char * weekdays [ ] ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Set the minimum and maximum values for the year
*
* @ param obj The calendar object
* @ param min The minimum year , greater than 1901 ;
* @ param max The maximum year ;
*
2012-02-14 00:50:26 -08:00
* Maximum must be greater than minimum , except if you don ' t want to set
2011-12-29 23:20:48 -08:00
* maximum year .
* Default values are 1902 and - 1.
*
* If the maximum year is a negative value , it will be limited depending
* on the platform architecture ( year 2037 for 32 bits ) ;
*
* @ see elm_calendar_min_max_year_get ( )
*
* @ ref calendar_example_03
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI void elm_calendar_min_max_year_set ( Evas_Object * obj , int min , int max ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Get the minimum and maximum values for the year
*
* @ param obj The calendar object .
* @ param min The minimum year .
* @ param max The maximum year .
*
* Default values are 1902 and - 1.
*
* @ see elm_calendar_min_max_year_get ( ) for more details .
*
* @ ref calendar_example_05
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI void elm_calendar_min_max_year_get ( const Evas_Object * obj , int * min , int * max ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
2012-04-19 01:46:22 -07:00
* Set select day mode to use .
2011-12-29 23:20:48 -08:00
*
* @ param obj The calendar object .
2012-04-27 05:55:25 -07:00
* @ param mode The select mode to use .
2011-12-29 23:20:48 -08:00
*
2012-04-19 01:46:22 -07:00
* Set the day selection mode used .
2011-12-29 23:20:48 -08:00
*
* @ ingroup Calendar
*/
2012-04-19 01:46:22 -07:00
EAPI void elm_calendar_select_mode_set ( Evas_Object * obj , Elm_Calendar_Select_Mode mode ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
2012-04-19 01:46:22 -07:00
* Get the select day mode used .
2011-12-29 23:20:48 -08:00
*
* @ param obj The calendar object .
2012-02-28 23:54:57 -08:00
*
2012-04-19 01:46:22 -07:00
* @ return the selected mode
2011-12-29 23:20:48 -08:00
*
2012-04-19 01:46:22 -07:00
* Get the day selection mode used .
*
* @ see elm_calendar_select_mode_set ( ) for more details
2011-12-29 23:20:48 -08:00
*
* @ ingroup Calendar
*/
2012-04-19 01:46:22 -07:00
EAPI Elm_Calendar_Select_Mode elm_calendar_select_mode_get ( const Evas_Object * obj ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Set selected date to be highlighted on calendar .
*
* @ param obj The calendar object .
* @ param selected_time A @ b tm struct to represent the selected date .
*
* Set the selected date , changing the displayed month if needed .
* Selected date changes when the user goes to next / previous month or
* select a day pressing over it on calendar .
*
* @ see elm_calendar_selected_time_get ( )
*
* @ ref calendar_example_04
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI void elm_calendar_selected_time_set ( Evas_Object * obj , struct tm * selected_time ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Get selected date .
*
* @ param obj The calendar object
* @ param selected_time A @ b tm struct to point to selected date
2012-02-14 00:50:26 -08:00
* @ return EINA_FALSE means an error occurred and returned time shouldn ' t
2011-12-29 23:20:48 -08:00
* be considered .
*
* Get date selected by the user or set by function
* elm_calendar_selected_time_set ( ) .
* Selected date changes when the user goes to next / previous month or
* select a day pressing over it on calendar .
*
* @ see elm_calendar_selected_time_get ( )
*
* @ ref calendar_example_05
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI Eina_Bool elm_calendar_selected_time_get ( const Evas_Object * obj , struct tm * selected_time ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Set a function to format the string that will be used to display
* month and year ;
*
* @ param obj The calendar object
2012-03-14 18:20:58 -07:00
* @ param format_func Function to set the month - year string given
2011-12-29 23:20:48 -08:00
* the selected date
*
* By default it uses strftime with " %B %Y " format string .
* It should allocate the memory that will be used by the string ,
* that will be freed by the widget after usage .
* A pointer to the string and a pointer to the time struct will be provided .
*
* Example :
* @ code
* static char *
* _format_month_year ( struct tm * selected_time )
* {
* char buf [ 32 ] ;
* if ( ! strftime ( buf , sizeof ( buf ) , " %B %Y " , selected_time ) ) return NULL ;
* return strdup ( buf ) ;
* }
*
* elm_calendar_format_function_set ( calendar , _format_month_year ) ;
* @ endcode
*
* @ ref calendar_example_02
*
* @ ingroup Calendar
*/
2012-03-06 17:02:21 -08:00
EAPI void elm_calendar_format_function_set ( Evas_Object * obj , Elm_Calendar_Format_Cb format_func ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Add a new mark to the calendar
*
* @ param obj The calendar object
* @ param mark_type A string used to define the type of mark . It will be
* emitted to the theme , that should display a related modification on these
* days representation .
* @ param mark_time A time struct to represent the date of inclusion of the
* mark . For marks that repeats it will just be displayed after the inclusion
* date in the calendar .
* @ param repeat Repeat the event following this periodicity . Can be a unique
* mark ( that don ' t repeat ) , daily , weekly , monthly or annually .
* @ return The created mark or @ p NULL upon failure .
*
* Add a mark that will be drawn in the calendar respecting the insertion
* time and periodicity . It will emit the type as signal to the widget theme .
* Default theme supports " holiday " and " checked " , but it can be extended .
*
* It won ' t immediately update the calendar , drawing the marks .
* For this , call elm_calendar_marks_draw ( ) . However , when user selects
* next or previous month calendar forces marks drawn .
*
* Marks created with this method can be deleted with
* elm_calendar_mark_del ( ) .
*
* Example
* @ code
* struct tm selected_time ;
* time_t current_time ;
*
* current_time = time ( NULL ) + 5 * 84600 ;
* localtime_r ( & current_time , & selected_time ) ;
* elm_calendar_mark_add ( cal , " holiday " , selected_time ,
* ELM_CALENDAR_ANNUALLY ) ;
*
* current_time = time ( NULL ) + 1 * 84600 ;
* localtime_r ( & current_time , & selected_time ) ;
* elm_calendar_mark_add ( cal , " checked " , selected_time , ELM_CALENDAR_UNIQUE ) ;
*
* elm_calendar_marks_draw ( cal ) ;
* @ endcode
*
* @ see elm_calendar_marks_draw ( )
* @ see elm_calendar_mark_del ( )
*
* @ ref calendar_example_06
*
* @ ingroup Calendar
*/
2012-02-29 19:38:56 -08:00
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 ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Delete mark from the calendar .
*
* @ param mark The mark to be deleted .
*
* If deleting all calendar marks is required , elm_calendar_marks_clear ( )
* should be used instead of getting marks list and deleting each one .
*
* @ see elm_calendar_mark_add ( )
*
* @ ref calendar_example_06
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI void elm_calendar_mark_del ( Elm_Calendar_Mark * mark ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Remove all calendar ' s marks
*
* @ param obj The calendar object .
*
* @ see elm_calendar_mark_add ( )
* @ see elm_calendar_mark_del ( )
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI void elm_calendar_marks_clear ( Evas_Object * obj ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Get a list of all the calendar marks .
*
* @ param obj The calendar object .
* @ return An @ c Eina_List of calendar marks objects , or @ c NULL on failure .
*
* @ see elm_calendar_mark_add ( )
* @ see elm_calendar_mark_del ( )
* @ see elm_calendar_marks_clear ( )
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI const Eina_List * elm_calendar_marks_get ( const Evas_Object * obj ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Draw calendar marks .
*
* @ param obj The calendar object .
*
* Should be used after adding , removing or clearing marks .
* It will go through the entire marks list updating the calendar .
* If lots of marks will be added , add all the marks and then call
* this function .
*
* When the month is changed , i . e . user selects next or previous month ,
2012-02-14 00:50:26 -08:00
* marks will be drawn .
2011-12-29 23:20:48 -08:00
*
* @ see elm_calendar_mark_add ( )
* @ see elm_calendar_mark_del ( )
* @ see elm_calendar_marks_clear ( )
*
* @ ref calendar_example_06
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI void elm_calendar_marks_draw ( Evas_Object * obj ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Set the interval on time updates for an user mouse button hold
* on calendar widgets ' month selection .
*
* @ param obj The calendar object
* @ param interval The ( first ) interval value in seconds
*
* This interval value is @ b decreased while the user holds the
* mouse pointer either selecting next or previous month .
*
* This helps the user to get to a given month distant from the
* current one easier / faster , as it will start to change quicker and
* quicker on mouse button holds .
*
* The calculation for the next change interval value , starting from
* the one set with this call , is the previous interval divided by
* 1.05 , so it decreases a little bit .
*
* The default starting interval value for automatic changes is
* @ b 0.85 seconds .
*
* @ see elm_calendar_interval_get ( )
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI void elm_calendar_interval_set ( Evas_Object * obj , double interval ) ;
2011-12-29 22:49:28 -08:00
2011-12-29 23:20:48 -08:00
/**
* Get the interval on time updates for an user mouse button hold
* on calendar widgets ' month selection .
*
* @ param obj The calendar object
* @ return The ( first ) interval value , in seconds , set on it
*
* @ see elm_calendar_interval_set ( ) for more details
*
* @ ingroup Calendar
*/
2011-12-30 01:48:46 -08:00
EAPI double elm_calendar_interval_get ( const Evas_Object * obj ) ;
2011-12-29 22:49:28 -08:00
2012-03-29 15:14:30 -07:00
/**
* Set the first day of week to use on calendar widgets ' .
*
* @ param obj The calendar object
* @ param day An int which correspond to the first day of the week ( Sunday = 0 , monday = 1 ,
* . . . , saturday = 6 )
*
* @ ingroup Calendar
*/
2012-03-29 15:59:11 -07:00
EAPI void elm_calendar_first_day_of_week_set ( Evas_Object * obj , Elm_Calendar_Weekday day ) ;
2012-03-29 15:14:30 -07:00
/**
* Get the first day of week , who are used on calendar widgets ' .
*
* @ param obj The calendar object
* @ return An int which correspond to the first day of the week ( Sunday = 0 , monday = 1 ,
* . . . , saturday = 6 )
*
* @ see elm_calendar_first_day_of_week_set ( ) for more details
*
* @ ingroup Calendar
*/
2012-03-29 15:59:11 -07:00
EAPI Elm_Calendar_Weekday elm_calendar_first_day_of_week_get ( const Evas_Object * obj ) ;
2012-03-29 15:14:30 -07:00
2012-09-11 14:33:54 -07:00
/**
* Define which fields of a @ b tm struct will be taken into account , when
* elm_calendar_selected_time_set ( ) is invoked .
*
* @ param obj The calendar object
* @ param selectable A bitmask of Elm_Calendar_Selectable
*
* By Default the bitmask is set to use all fields of a @ b tm struct ( year ,
* month and day of the month ) .
*
* @ ingroup Calendar
* @ see elm_calendar_selected_time_set
* @ since 1.8
*/
EAPI void elm_calendar_selectable_set ( Evas_Object * obj , Elm_Calendar_Selectable selectable ) ;
/**
* Get how elm_calendar_selected_time_set manage a date
*
* @ param obj The calendar object
* @ return The flag used to manage a date with a elm_calendar_selected_time_set
*
* @ ingroup Calendar
* @ see elm_calendar_selectable_set
* @ see elm_calendar_selected_time_set
* @ since 1.8
*/
EAPI Elm_Calendar_Selectable elm_calendar_selectable_get ( const Evas_Object * obj ) ;
2011-12-29 23:20:48 -08:00
/**
* @ }
*/