diff options
| author | Georges Basile Stavracas Neto <georges.stavracas@gmail.com> | 2017-03-20 17:55:09 -0300 |
|---|---|---|
| committer | Georges Basile Stavracas Neto <georges.stavracas@gmail.com> | 2017-04-08 21:45:06 -0300 |
| commit | 0a34dc8ef2ed4a46421dba1ab7246d3cc9ed5376 (patch) | |
| tree | 0c136e480b11bd253d312757296db65a44338930 | |
| parent | 8ad65d311b1b71974fce7a5508c6963ff461c584 (diff) | |
| download | gnome-calendar-wip/gbsneto/docs.tar.gz | |
wip: document classeswip/gbsneto/docs
24 files changed, 1050 insertions, 486 deletions
@@ -96,4 +96,4 @@ gtk-doc.make doc/reference/xml doc/reference/html doc/reference/*.stamp -doc/reference/*.xml +doc/reference/version.xml diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am index a1e6351a..74373178 100644 --- a/doc/reference/Makefile.am +++ b/doc/reference/Makefile.am @@ -34,6 +34,7 @@ if ENABLE_DOC_CROSS_REFERENCES # Extra options to supply to gtkdoc-fixref. Not normally needed. # e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html FIXXREF_OPTIONS = \ + --extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/evolution-data-server \ --extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib \ --extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gobject \ --extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gio \ @@ -55,7 +56,13 @@ CFILE_GLOB = \ IGNORE_HFILES = $(NULL) # Images to copy into HTML directory. -HTML_IMAGES = $(NULL) +HTML_IMAGES = \ + images/gcal-edit-dialog.png \ + images/gcal-event-widget.png \ + images/gcal-source-dialog.png \ + images/gcal-window.png \ + images/gcal-window_agendas.png \ + $(NULL) # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). # e.g. content_files=running.sgml building.sgml changes-2.0.sgml diff --git a/doc/reference/gnome-calendar-decl-list.txt b/doc/reference/gnome-calendar-decl-list.txt index d9c201e3..bdf45148 100644 --- a/doc/reference/gnome-calendar-decl-list.txt +++ b/doc/reference/gnome-calendar-decl-list.txt @@ -152,9 +152,7 @@ GcalEditDialog <SECTION> <FILE>gcal-enum-types</FILE> <SUBSECTION Standard> -GCAL_EDITABLE_PROPERTY GCAL_WINDOW_VIEW_TYPE -event_editable_property_get_type gcal_window_view_type_get_type </SECTION> @@ -448,8 +446,6 @@ MINUTES_PER_DAY MAX_MINUTES gcal_clear_datetime GcalWindowViewType -EventEditableProperty -GcalTranslateFunc icaltime_get_type datetime_compare_date datetime_to_icaltime @@ -488,8 +484,6 @@ GCAL_TYPE_VIEW GcalViewInterface gcal_view_set_date gcal_view_get_date -gcal_view_get_initial_date -gcal_view_get_final_date gcal_view_clear_marks gcal_view_get_children_by_uuid GcalView diff --git a/doc/reference/gnome-calendar-decl.txt b/doc/reference/gnome-calendar-decl.txt index 1f795415..17db1202 100644 --- a/doc/reference/gnome-calendar-decl.txt +++ b/doc/reference/gnome-calendar-decl.txt @@ -764,10 +764,6 @@ struct _GcalViewInterface icaltimetype *start_span, icaltimetype *end_span); - /* Time handling related API */ - icaltimetype* (*get_initial_date) (GcalView *view); - icaltimetype* (*get_final_date) (GcalView *view); - /* Marks related API */ void (*clear_marks) (GcalView *view); @@ -786,16 +782,6 @@ GcalView *view, icaltimetype *date GcalView *view </FUNCTION> <FUNCTION> -<NAME>gcal_view_get_initial_date</NAME> -<RETURNS>icaltimetype * </RETURNS> -GcalView *view -</FUNCTION> -<FUNCTION> -<NAME>gcal_view_get_final_date</NAME> -<RETURNS>icaltimetype * </RETURNS> -GcalView *view -</FUNCTION> -<FUNCTION> <NAME>gcal_view_clear_marks</NAME> <RETURNS>void </RETURNS> GcalView *view @@ -1023,15 +1009,6 @@ ECalDataModel *data_model <RETURNS>GType </RETURNS> void </FUNCTION> -<MACRO> -<NAME>GCAL_EDITABLE_PROPERTY</NAME> -#define GCAL_EDITABLE_PROPERTY (event_editable_property_get_type()) -</MACRO> -<FUNCTION> -<NAME>event_editable_property_get_type</NAME> -<RETURNS>GType </RETURNS> -void -</FUNCTION> <FUNCTION> <NAME>gcal_log_init</NAME> <RETURNS>void </RETURNS> @@ -1069,23 +1046,6 @@ typedef enum GCAL_WINDOW_VIEW_SEARCH, } GcalWindowViewType; </ENUM> -<ENUM> -<NAME>EventEditableProperty</NAME> -typedef enum -{ - EVENT_SUMMARY = 0, - EVENT_START_DATE, - EVENT_END_DATE, - EVENT_LOCATION, - EVENT_DESCRIPTION, - EVENT_SOURCE, -} EventEditableProperty; -</ENUM> -<USER_FUNCTION> -<NAME>GcalTranslateFunc</NAME> -<RETURNS>const gchar *</RETURNS> -GtkWidget *source_widget -</USER_FUNCTION> <FUNCTION> <NAME>icaltime_get_type</NAME> <RETURNS>GType </RETURNS> diff --git a/doc/reference/gnome-calendar-undeclared.txt b/doc/reference/gnome-calendar-undeclared.txt index e69de29b..2b4034e9 100644 --- a/doc/reference/gnome-calendar-undeclared.txt +++ b/doc/reference/gnome-calendar-undeclared.txt @@ -0,0 +1,4 @@ +EventEditableProperty +GcalTranslateFunc +gcal_view_get_final_date +gcal_view_get_initial_date diff --git a/doc/reference/gnome-calendar-undocumented.txt b/doc/reference/gnome-calendar-undocumented.txt index a222a9da..e6ad0f52 100644 --- a/doc/reference/gnome-calendar-undocumented.txt +++ b/doc/reference/gnome-calendar-undocumented.txt @@ -1,7 +1,7 @@ -47% symbol docs coverage. -264 symbols documented. -182 symbols incomplete. -296 not documented. +60% symbol docs coverage. +324 symbols documented. +108 symbols incomplete. +216 not documented. ALIGNED (<parameters>) @@ -12,22 +12,14 @@ ECalDataModel:timezone ECalDataModelForeachFunc (<parameters>) ECalDataModelViewState (<items>) EThreadJobFunc (<parameters>) -EventEditableProperty (<items>) -GCAL_BUG (<parameters>) +EventEditableProperty GCAL_ENABLE_TRACE -GCAL_ENTRY GCAL_EVENT_ERROR -GCAL_EXIT -GCAL_GOTO (<parameters>) GCAL_LOG_LEVEL_TRACE -GCAL_PROBE GCAL_RESPONSE_CREATE_EVENT GCAL_RESPONSE_DELETE_EVENT GCAL_RESPONSE_REMOVE_SOURCE GCAL_RESPONSE_SAVE_EVENT -GCAL_RETURN (<parameters>) -GCAL_TODO (<parameters>) -GCAL_TRACE_MSG (<parameters>) GCAL_TYPE_APPLICATION GCAL_TYPE_DATE_CHOOSER GCAL_TYPE_DATE_CHOOSER_DAY @@ -60,7 +52,6 @@ GcalDateChooserDayOptionsCallback (<parameters>) GcalDateSelector GcalEditDialog GcalEvent -GcalEventError (<items>) GcalEventWidget GcalEventWidget::activate GcalManager @@ -74,16 +65,14 @@ GcalMultiChoice GcalMultiChoice::wrapped GcalMultiChoiceFormatCallback (<parameters>) GcalQuickAddPopover -GcalRangeTraverseFunc (<parameters>) GcalSearchView GcalShellSearchProvider GcalShellSearchProviderClass (<items>) GcalSourceDialog -GcalSourceDialogMode (<items>) GcalSubscriberView::event-activated GcalSubscriberViewPrivate (<items>) GcalTimeSelector -GcalTranslateFunc (<parameters>) +GcalTranslateFunc GcalView GcalViewInterface (<items>) GcalWeekGrid @@ -93,29 +82,19 @@ GcalWeekHeader::event-activated GcalWeekView GcalWeekView::event-activated GcalWindow -GcalWindowViewType (<items>) GcalYearView GcalYearView::event-activated ICAL_TIME_TYPE MAX_MINUTES MINUTES_PER_DAY -action_widget_activated (Returns) -back_button_clicked (Returns) +_GCAL_BUG build_component_from_details (summary, initial_date, final_date) -calendar_file_selected (Returns) calendar_get_resource -calendar_listbox_row_activated (Returns) -clear_pages (Returns) -datetime_compare_date (<parameters>) -datetime_is_date (<parameters>) -datetime_to_icaltime (<parameters>) -description_label_link_activated (Returns) e_cal_data_model_remove_client (data_model) e_cal_data_model_subscriber_component_added (comp) -e_strftime_fix_am_pm (<parameters>) -e_utf8_strftime_fix_am_pm (<parameters>) +e_strftime_fix_am_pm (str, tm, fmt, max) +e_utf8_strftime_fix_am_pm (fmt, max, str, tm) fix_popover_menu_icons (popover) -format_utc_offset (<parameters>) free_row_data (Returns) gcal_application_get_manager (<parameters>) gcal_application_get_settings (<parameters>) @@ -143,15 +122,6 @@ gcal_date_chooser_set_show_day_names (<parameters>) gcal_date_chooser_set_show_heading (<parameters>) gcal_date_chooser_set_show_week_numbers (<parameters>) gcal_date_selector_new -gcal_dup_icaltime (<parameters>) -gcal_edit_dialog_get_date_end (<parameters>) -gcal_edit_dialog_get_date_start (<parameters>) -gcal_edit_dialog_get_event (<parameters>) -gcal_edit_dialog_new -gcal_edit_dialog_set_event (<parameters>) -gcal_edit_dialog_set_event_is_new (<parameters>) -gcal_edit_dialog_set_manager (<parameters>) -gcal_edit_dialog_set_time_format (<parameters>) gcal_event_get_description (self) gcal_event_set_summary (self) gcal_event_widget_clone (<parameters>) @@ -163,37 +133,18 @@ gcal_event_widget_new (<parameters>) gcal_event_widget_set_date_start (date_start) gcal_event_widget_set_has_reminders (<parameters>) gcal_event_widget_set_read_only (<parameters>) -gcal_get_month_name (<parameters>) -gcal_get_pixbuf_from_color (color, size) -gcal_get_surface_from_color (<parameters>) -gcal_get_weekday (<parameters>) gcal_log_init -gcal_manager_add_source (name, backend) -gcal_manager_create_event (<parameters>) +gcal_manager_add_source (backend, name) gcal_manager_get_default_source -gcal_manager_get_event_from_shell_search (<parameters>) -gcal_manager_get_events (manager, range_end, range_start) -gcal_manager_get_goa_client (<parameters>) -gcal_manager_get_loading (<parameters>) -gcal_manager_get_shell_search_events (<parameters>) -gcal_manager_get_source (manager) -gcal_manager_get_sources (manager) -gcal_manager_get_sources_connected (manager) -gcal_manager_get_system_timezone (<parameters>) -gcal_manager_is_client_writable (<parameters>) -gcal_manager_move_event_to_source (<parameters>) -gcal_manager_new_with_settings -gcal_manager_query_client_data (source, manager, field) -gcal_manager_refresh (<parameters>) -gcal_manager_remove_event (<parameters>) -gcal_manager_set_default_source -gcal_manager_set_search_subscriber (<parameters>) -gcal_manager_set_shell_search_subscriber (<parameters>) -gcal_manager_set_subscriber (<parameters>) -gcal_manager_setup_shell_search (<parameters>) -gcal_manager_shell_search_done (<parameters>) -gcal_manager_update_event (<parameters>) -gcal_month_view_get_final_date +gcal_manager_get_events (range_end, range_start) +gcal_manager_get_goa_client (manager) +gcal_manager_get_shell_search_events (manager) +gcal_manager_query_client_data (field, source, manager) +gcal_manager_set_search_subscriber (manager) +gcal_manager_set_shell_search_subscriber (manager) +gcal_manager_set_subscriber (manager) +gcal_manager_setup_shell_search (self) +gcal_manager_shell_search_done (manager) gcal_month_view_motion_notify_event (widget, event, Returns) gcal_month_view_set_first_weekday (self) gcal_month_view_set_manager (<parameters>) @@ -204,7 +155,6 @@ gcal_multi_choice_set_choices (<parameters>) gcal_multi_choice_set_format_callback (<parameters>) gcal_multi_choice_set_value (<parameters>) gcal_quick_add_popover_new -gcal_range_tree_count_entries_at_range (<parameters>) gcal_search_view_new gcal_search_view_search (<parameters>) gcal_search_view_set_search @@ -213,15 +163,14 @@ gcal_shell_search_provider_dbus_export (<parameters>) gcal_shell_search_provider_dbus_unexport (<parameters>) gcal_shell_search_provider_new gcal_source_dialog_new -gcal_source_dialog_set_manager (Returns) -gcal_source_dialog_set_mode (Returns) -gcal_source_dialog_set_source (Returns) gcal_subscriber_view_get_child_by_uuid (<parameters>) gcal_time_selector_get_time (<parameters>) gcal_time_selector_new gcal_time_selector_set_time (<parameters>) gcal_time_selector_set_time_format (<parameters>) gcal_view_get_date (<parameters>) +gcal_view_get_final_date +gcal_view_get_initial_date gcal_view_set_date (<parameters>) gcal_week_grid_add_event (<parameters>) gcal_week_grid_clear_marks (<parameters>) @@ -238,49 +187,21 @@ gcal_week_header_remove_event (<parameters>) gcal_week_header_set_first_weekday (<parameters>) gcal_week_header_set_manager (<parameters>) gcal_week_header_set_use_24h_format (<parameters>) -gcal_week_view_get_final_date -gcal_week_view_get_initial_date gcal_week_view_set_first_weekday (view, day_nr) gcal_week_view_set_manager (<parameters>) gcal_week_view_set_use_24h_format (view, use_24h) -gcal_window_new_event (<parameters>) -gcal_window_new_with_view_and_date (<parameters>) -gcal_window_open_event_by_uuid (<parameters>) -gcal_window_set_search_mode (<parameters>) -gcal_window_set_search_query (<parameters>) gcal_year_view_set_current_date (<parameters>) gcal_year_view_set_first_weekday (<parameters>) gcal_year_view_set_manager (<parameters>) gcal_year_view_set_use_24h_format (<parameters>) -get_alarm_trigger_minutes (<parameters>) -get_circle_surface_from_color (<parameters>) -get_color_name_from_source (<parameters>) -get_desc_from_component (component) -get_end_of_week (<parameters>) -get_source_parent_name_color (<parameters>) -get_start_of_week (<parameters>) hide_notification (Returns) -icaltime_compare_date (date1, date2) -icaltime_compare_with_current (<parameters>) icaltime_get_type -icaltime_to_datetime (<parameters>) -is_clock_format_24h -is_source_enabled (<parameters>) -name_entry_text_changed (Returns) notification_child_revealed_changed (Returns) -on_local_activated (Returns) -on_web_activated (Returns) -online_accounts_listbox_row_activated (Returns) -online_accounts_settings_button_clicked (Returns) open_event (Returns) remove_button_clicked (Returns) remove_source (Returns) -response_signal (Returns) -should_change_date_for_scroll (<parameters>) undo_remove_action (Returns) update_view (Returns) -uri_get_fields (uri, schema, host, path) -url_entry_text_changed (Returns) view_changed (object, pspec, user_data) css-code:Long_Description @@ -297,28 +218,18 @@ gcal-date-chooser:Long_Description gcal-date-chooser:Short_Description gcal-date-selector:Long_Description gcal-date-selector:Short_Description -gcal-debug:Long_Description -gcal-debug:Short_Description -gcal-edit-dialog:Long_Description -gcal-edit-dialog:Short_Description gcal-enum-types:Long_Description gcal-enum-types:Short_Description gcal-event-widget:Long_Description gcal-event-widget:Short_Description -gcal-event:Long_Description -gcal-event:Short_Description gcal-log:Long_Description gcal-log:Short_Description -gcal-manager:Long_Description -gcal-manager:Short_Description gcal-month-view:Long_Description gcal-month-view:Short_Description gcal-multi-choice:Long_Description gcal-multi-choice:Short_Description gcal-quick-add-popover:Long_Description gcal-quick-add-popover:Short_Description -gcal-range-tree:Long_Description -gcal-range-tree:Short_Description gcal-resources:Long_Description gcal-resources:Short_Description gcal-search-view:Long_Description @@ -327,8 +238,6 @@ gcal-shell-search-provider-generated:Long_Description gcal-shell-search-provider-generated:Short_Description gcal-shell-search-provider:Long_Description gcal-shell-search-provider:Short_Description -gcal-source-dialog:Long_Description -gcal-source-dialog:Short_Description gcal-subscriber-view-private:Long_Description gcal-subscriber-view-private:Short_Description gcal-subscriber-view:Long_Description @@ -336,7 +245,6 @@ gcal-subscriber-view:Short_Description gcal-time-selector:Long_Description gcal-time-selector:Short_Description gcal-utils:Long_Description -gcal-utils:Short_Description gcal-view:Long_Description gcal-view:Short_Description gcal-week-grid:Long_Description @@ -345,7 +253,5 @@ gcal-week-header:Long_Description gcal-week-header:Short_Description gcal-week-view:Long_Description gcal-week-view:Short_Description -gcal-window:Long_Description -gcal-window:Short_Description gcal-year-view:Long_Description gcal-year-view:Short_Description diff --git a/doc/reference/gnome-calendar-unused.txt b/doc/reference/gnome-calendar-unused.txt index 8b2221ea..b3ac4899 100644 --- a/doc/reference/gnome-calendar-unused.txt +++ b/doc/reference/gnome-calendar-unused.txt @@ -4,6 +4,14 @@ fix_popover_menu_icons(window) gcal_event_set_summary(event) gcal_event_widget_set_date_start(date_end) gcal_manager_add_source(base_uri, relative_uri) +gcal_manager_get_events(start_date, end_date) +gcal_manager_get_goa_client(self) +gcal_manager_get_shell_search_events(self) +gcal_manager_set_search_subscriber(self) +gcal_manager_set_shell_search_subscriber(self) +gcal_manager_set_subscriber(self) +gcal_manager_setup_shell_search(manager) +gcal_manager_shell_search_done(self) gcal_month_view_set_first_weekday(view) gcal_month_view_set_use_24h_format(view) gcal_week_view_set_first_weekday(view) diff --git a/doc/reference/gnome-calendar.hierarchy b/doc/reference/gnome-calendar.hierarchy index 7e24ac9d..bc548aba 100644 --- a/doc/reference/gnome-calendar.hierarchy +++ b/doc/reference/gnome-calendar.hierarchy @@ -104,8 +104,28 @@ GInterface GConverter GProxyResolver AtkImage +GBoxed + GValueArray + GcalRangeTree + icaltimetype + GError + GVariantDict + GdkRectangle + CairoRectangleInt + CairoContext + GdkEvent + GtkSelectionData + GtkRequisition + GtkBorder + GdkColor + GDateTime + PangoAttrList + PangoTabArray + GdkRGBA + GTimeZone + GStrv + GDBusInterfaceInfo GEnum - EventEditableProperty GcalWindowViewType GtkAlign GtkStateType @@ -133,24 +153,3 @@ GEnum GBusType GtkReliefStyle GtkArrowType -GBoxed - GValueArray - GcalRangeTree - icaltimetype - GError - GVariantDict - GdkRectangle - CairoRectangleInt - CairoContext - GdkEvent - GtkSelectionData - GtkRequisition - GtkBorder - GdkColor - GDateTime - PangoAttrList - PangoTabArray - GdkRGBA - GTimeZone - GStrv - GDBusInterfaceInfo diff --git a/doc/reference/gnome-calendar.types b/doc/reference/gnome-calendar.types index 833da847..954780f2 100644 --- a/doc/reference/gnome-calendar.types +++ b/doc/reference/gnome-calendar.types @@ -1,6 +1,5 @@ e_cal_data_model_get_type e_cal_data_model_subscriber_get_type -event_editable_property_get_type gcal_application_get_type gcal_date_chooser_day_get_type gcal_date_chooser_get_type diff --git a/doc/reference/images/gcal-event-widget.png b/doc/reference/images/gcal-event-widget.png Binary files differnew file mode 100644 index 00000000..431ed87a --- /dev/null +++ b/doc/reference/images/gcal-event-widget.png diff --git a/doc/reference/images/gcal-window.png b/doc/reference/images/gcal-window.png Binary files differnew file mode 100644 index 00000000..d7d2c535 --- /dev/null +++ b/doc/reference/images/gcal-window.png diff --git a/doc/reference/images/gcal-window_agendas.png b/doc/reference/images/gcal-window_agendas.png Binary files differnew file mode 100644 index 00000000..b7a3bb0e --- /dev/null +++ b/doc/reference/images/gcal-window_agendas.png diff --git a/src/gcal-debug.h.in b/src/gcal-debug.h.in index bc2d1eb8..199624cc 100644 --- a/src/gcal-debug.h.in +++ b/src/gcal-debug.h.in @@ -21,6 +21,18 @@ #include <glib.h> +/** + * SECTION:gcal-debug + * @short_description: Debugging macros + * @title:Debugging + * @stability:stable + * + * Macros used for tracing and debugging code. These + * are only valid when Calendar is compiled with tracing + * suppoer (pass `--enable-tracing` to the configure + * script to do that). + */ + G_BEGIN_DECLS #ifndef GCAL_ENABLE_TRACE @@ -38,46 +50,158 @@ G_BEGIN_DECLS #endif #ifdef GCAL_ENABLE_TRACE + +/** + * GCAL_TRACE_MSG: + * @fmt: printf-like format of the message + * @...: arguments for @fmt + * + * Prints a trace message. + */ # define GCAL_TRACE_MSG(fmt, ...) \ g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " MSG: %s():%d: " fmt, \ G_STRFUNC, __LINE__, ##__VA_ARGS__) + +/** + * GCAL_PROBE: + * + * Prints a probing message. Put this macro in the code when + * you want to check the program reaches a certain section + * of code. + */ # define GCAL_PROBE \ g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, "PROBE: %s():%d", \ G_STRFUNC, __LINE__) + +/** + * GCAL_TODO: + * @_msg: the message to print + * + * Prints a TODO message. + */ # define GCAL_TODO(_msg) \ g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " TODO: %s():%d: %s", \ G_STRFUNC, __LINE__, _msg) + +/** + * GCAL_ENTRY: + * + * Prints an entry message. This shouldn't be used in + * critical functions. Place this at the beggining of + * the function, before any assertion. + */ # define GCAL_ENTRY \ g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, "ENTRY: %s():%d", \ G_STRFUNC, __LINE__) + +/** + * GCAL_EXIT: + * + * Prints an exit message. This shouldn't be used in + * critical functions. Place this at the end of + * the function, after any relevant code. If the + * function returns something, use GCAL_RETURN() + * instead. + */ # define GCAL_EXIT \ G_STMT_START { \ g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " EXIT: %s():%d", \ G_STRFUNC, __LINE__); \ return; \ } G_STMT_END + +/** + * GCAL_GOTO: + * @_l: goto tag + * + * Logs a goto jump. + */ # define GCAL_GOTO(_l) \ G_STMT_START { \ g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " GOTO: %s():%d ("#_l")",\ G_STRFUNC, __LINE__); \ goto _l; \ } G_STMT_END + +/** + * GCAL_RETURN: + * @_r: the return value. + * + * Prints an exit message, and returns @_r. See #GCAL_EXIT. + */ # define GCAL_RETURN(_r) \ G_STMT_START { \ g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " EXIT: %s():%d ", \ G_STRFUNC, __LINE__); \ return _r; \ } G_STMT_END + #else + +/** + * GCAL_TODO: + * @_msg: the message to print + * + * Prints a TODO message. + */ # define GCAL_TODO(_msg) + +/** + * GCAL_PROBE: + * + * Prints a probing message. + */ # define GCAL_PROBE + +/** + * GCAL_TRACE_MSG: + * @fmt: printf-like format of the message + * @...: arguments for @fmt + * + * Prints a trace message. + */ # define GCAL_TRACE_MSG(fmt, ...) + +/** + * GCAL_ENTRY: + * + * Prints a probing message. This shouldn't be used in + * critical functions. Place this at the beggining of + * the function, before any assertion. + */ # define GCAL_ENTRY + +/** + * GCAL_GOTO: + * @_l: goto tag + * + * Logs a goto jump. + */ # define GCAL_GOTO(_l) goto _l + +/** + * GCAL_EXIT: + * + * Prints an exit message. This shouldn't be used in + * critical functions. Place this at the end of + * the function, after any relevant code. If the + * function returns somethin, use GCAL_RETURN() + * instead. + */ # define GCAL_EXIT return + +/** + * GCAL_RETURN: + * @_r: the return value. + * + * Prints an exit message, and returns @_r. See #GCAL_EXIT. + */ # define GCAL_RETURN(_r) return _r #endif +/** + * _GCAL_BUG: (skip) + */ #define _GCAL_BUG(Component, Description, File, Line, Func, ...) \ G_STMT_START { \ g_printerr ("-----------------------------------------------------------------\n"); \ @@ -91,6 +215,15 @@ G_BEGIN_DECLS g_printerr (Description"\n", ##__VA_ARGS__); \ g_printerr ("-----------------------------------------------------------------\n"); \ } G_STMT_END + +/** + * GCAL_BUG: + * @Component: the component + * @Description: the description + * @...: extra arguments + * + * Logs a bug-friendly message. + */ #define GCAL_BUG(Component, Description, ...) \ _GCAL_BUG(Component, Description, __FILE__, __LINE__, G_STRFUNC, ##__VA_ARGS__) diff --git a/src/gcal-edit-dialog.c b/src/gcal-edit-dialog.c index 59fc74a4..f54ebf1a 100644 --- a/src/gcal-edit-dialog.c +++ b/src/gcal-edit-dialog.c @@ -29,6 +29,17 @@ #include <libecal/libecal.h> #include <glib/gi18n.h> +/** + * SECTION:gcal-edit-dialog + * @short_description: Event editor dialog + * @title:GcalEditDialog + * @image:gcal-edit-dialog.png + * + * #GcalEditDialog is the event editor dialog of GNOME Calendar. It + * allows the user to change the various aspects of the events, as + * well as managing alarms. + */ + struct _GcalEditDialog { GtkDialog parent; @@ -766,6 +777,7 @@ get_row_for_alarm_trigger_minutes (GcalEditDialog *self, return NULL; } + static void remove_button_clicked (GtkButton *button, GtkWidget *row) @@ -1019,12 +1031,27 @@ add_alarm_button_clicked (GtkWidget *button, } /* Public API */ + +/** + * gcal_edit_dialog_new: + * + * Creates a new #GcalEditDialog + * + * Returns: (transfer full): a #GcalEditDialog + */ GtkWidget* gcal_edit_dialog_new (void) { return g_object_new (GCAL_TYPE_EDIT_DIALOG, NULL); } +/** + * gcal_edit_dialog_set_time_format: + * @dialog: a #GcalDialog + * @use_24h_format: %TRUE to use 24h format, %FALSE otherwise + * + * Sets the time format to be used by @dialog. + */ void gcal_edit_dialog_set_time_format (GcalEditDialog *dialog, gboolean use_24h_format) @@ -1037,6 +1064,14 @@ gcal_edit_dialog_set_time_format (GcalEditDialog *dialog, gcal_time_selector_set_time_format (GCAL_TIME_SELECTOR (dialog->end_time_selector), dialog->format_24h); } +/** + * gcal_edit_dialog_set_event_is_new: + * @dialog: a #GcalDialog + * @event_is_new: %TRUE if the event is new, %FALSE otherwise + * + * Sets whether the currently edited event is a new event, or not. + * The @dialog will adapt it's UI elements to reflect that. + */ void gcal_edit_dialog_set_event_is_new (GcalEditDialog *dialog, gboolean event_is_new) @@ -1046,6 +1081,14 @@ gcal_edit_dialog_set_event_is_new (GcalEditDialog *dialog, gtk_widget_set_visible (dialog->delete_button, !event_is_new); } +/** + * gcal_edit_dialog_get_event: + * @dialog: a #GcalDialog + * + * Retrieves the current event being edited by the @dialog. + * + * Returns: (transfer none)(nullable): a #GcalEvent + */ GcalEvent* gcal_edit_dialog_get_event (GcalEditDialog *dialog) { @@ -1054,6 +1097,14 @@ gcal_edit_dialog_get_event (GcalEditDialog *dialog) return dialog->event; } +/** + * gcal_edit_dialog_set_event: + * @dialog: a #GcalDialog + * @event: (nullable): a #GcalEvent + * + * Sets the event of the @dialog. When @event is + * %NULL, the current event information is unset. + */ void gcal_edit_dialog_set_event (GcalEditDialog *dialog, GcalEvent *event) @@ -1164,6 +1215,13 @@ out: GCAL_EXIT; } +/** + * gcal_edit_dialog_set_manager: + * @dialog: a #GcalEditDialog + * @manager: a #GcalManager + * + * Sets the #GcalManager instance of the @dialog. + */ void gcal_edit_dialog_set_manager (GcalEditDialog *dialog, GcalManager *manager) @@ -1220,6 +1278,14 @@ return_datetime_for_widgets (GcalEditDialog *dialog, return retval; } +/** + * gcal_edit_dialog_get_date_start: + * @dialog: a #GcalEditDialog + * + * Retrieves the start date of the edit dialog. + * + * Returns: (transfer full): a #GDateTime + */ GDateTime* gcal_edit_dialog_get_date_start (GcalEditDialog *dialog) { @@ -1231,6 +1297,14 @@ gcal_edit_dialog_get_date_start (GcalEditDialog *dialog) GCAL_TIME_SELECTOR (dialog->start_time_selector)); } +/** + * gcal_edit_dialog_get_date_end: + * @dialog: a #GcalEditDialog + * + * Retrieves the end date of the edit dialog. + * + * Returns: (transfer full): a #GDateTime + */ GDateTime* gcal_edit_dialog_get_date_end (GcalEditDialog *dialog) { diff --git a/src/gcal-event.c b/src/gcal-event.c index a9d0a7d7..907bb96c 100644 --- a/src/gcal-event.c +++ b/src/gcal-event.c @@ -23,6 +23,58 @@ #define LIBICAL_TZID_PREFIX "/freeassociation.sourceforge.net/" +/** + * SECTION:gcal-event + * @short_description: A class that represents an event + * @title:GcalEvent + * @stability:unstable + * @see_also:GcalEventWidget,GcalManager + * + * The #GcalEvent class represents an appointment, with + * various functions to modify it. All the changes are + * transient. To persistently store the changes, you + * need to call gcal_manager_update_event(). + * + * Although the #ECalComponent may have no end date. In this + * case, gcal_event_get_date_end() returns the same date that + * gcal_event_get_date_start(). + * + * #GcalEvent implements #GInitable, and creating it possibly + * can generate an error. At the moment, the only error that + * can be generate is #GCAL_EVENT_ERROR_INVALID_START_DATE. + * + * ## Timezones + * + * When a #GcalEvent is created, the timezone is parsed from + * the #ECalComponent. The start and end dates can possibly + * have different timezones, e.g. when the user is traveling + * across timezones and the departure time is in a different + * timezone of the arrival time. + * + * For the sake of sanity, gcal_event_get_timezone() returns + * the timezone of the start date. If you need to precisely + * check the timezones of the start and end dates, you have + * to use g_date_time_get_timezone_identifier(). + * + * ## Example: + * |[<!-- language="C" --> + * GcalEvent *event; + * GError *error; + * + * error = NULL; + * event = gcal_event_new (source, component, &error); + * + * if (error) + * { + * g_warning ("Error creating event: %s", error->message); + * g_clear_error (&error); + * return; + * } + * + * ... + * ]| + */ + struct _GcalEvent { GObject parent; @@ -739,7 +791,7 @@ gcal_event_get_color (GcalEvent *self) * @color: a #GdkRGBA * * Sets the color of the event, which is passed to the - * parent @ESource. + * parent #ESource. */ void gcal_event_set_color (GcalEvent *self, @@ -797,7 +849,9 @@ gcal_event_set_all_day (GcalEvent *self, * gcal_event_get_date_end: * @self: a #GcalEvent * - * Retrieves the end date of @self. + * Retrieves the end date of @self. If the component doesn't + * have an end date, then the returned date is the same of + * gcal_event_get_date_start(). * * Returns: (transfer none): a #GDateTime. */ diff --git a/src/gcal-event.h b/src/gcal-event.h index ce21b22d..3fe6d96d 100644 --- a/src/gcal-event.h +++ b/src/gcal-event.h @@ -26,6 +26,12 @@ G_BEGIN_DECLS +/** + * GcalEventError: + * @GCAL_EVENT_ERROR_INVALID_START_DATE: indicated an invalid start date + * + * Errors that #GcalEvent can generate. + */ typedef enum { GCAL_EVENT_ERROR_INVALID_START_DATE diff --git a/src/gcal-manager.c b/src/gcal-manager.c index f63235b7..91587b1d 100644 --- a/src/gcal-manager.c +++ b/src/gcal-manager.c @@ -25,6 +25,17 @@ #include <libedataserverui/libedataserverui.h> +/** + * SECTION:gcal-manager + * @short_description: The backend of GNOME Calendar + * @title:GcalManager + * @stability:unstable + * + * #GcalManager is the backend of GNOME Calendar. It sets everything + * up, connects to the Online Accounts daemon, and manages the events + * and calendars. + */ + typedef struct { GcalEvent *event; @@ -479,7 +490,7 @@ on_event_created (GObject *source_object, /** * on_component_updated: - * @source_object: {@link ECalClient} source + * @source_object: #ECalClient source * @result: result of the operation * @user_data: manager instance * @@ -510,9 +521,9 @@ on_event_updated (GObject *source_object, /** * on_event_removed: - * @source_object: {@link ECalClient} source + * @source_object: #ECalClient source * @result: result of the operation - * @user_data: an {@link ECalComponent} + * @user_data: an #ECalComponent * * Called when an component is removed. Currently, it only checks for * error, but a more sophisticated implementation will come in no time.* @@ -1076,12 +1087,12 @@ gcal_manager_init (GcalManager *self) /* Public API */ /** * gcal_manager_new_with_settings: - * @settings: + * @settings: a #GSettings * - * Since: 0.0.1 - * Return value: the new #GcalManager - * Returns: (transfer full): - **/ + * Creates a new #GcalManager with @settings. + * + * Returns: (transfer full): a newly created #GcalManager + */ GcalManager* gcal_manager_new_with_settings (GSettings *settings) { @@ -1092,29 +1103,32 @@ gcal_manager_new_with_settings (GSettings *settings) /** * gcal_manager_get_source: - * @manager: + * @manager: a #GcalManager + * @uid: the unique identifier of the source * * Retrieve a source according to it's UID. The source * is referenced for thread-safety and must be unreferenced * after user. * - * Returns: (Transfer full) an {@link ESource}, or NULL. - **/ + * Returns: (nullable)(transfer full): an #ESource, or %NULL. + */ ESource* gcal_manager_get_source (GcalManager *manager, const gchar *uid) { + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + return e_source_registry_ref_source (manager->source_registry, uid); } /** * gcal_manager_get_sources: - * @manager: + * @manager: a #GcalManager * * Retrieve a list of the enabled sources used in the application. * - * Returns: (Transfer full) a {@link GList} object to be freed with g_list_free() - **/ + * Returns: (nullable)(transfer container)(content-type ESource): a #GList + */ GList* gcal_manager_get_sources (GcalManager *manager) { @@ -1124,6 +1138,8 @@ gcal_manager_get_sources (GcalManager *manager) GCAL_ENTRY; + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + g_hash_table_iter_init (&iter, manager->clients); while (g_hash_table_iter_next (&iter, &key, &value)) @@ -1141,50 +1157,75 @@ gcal_manager_get_sources (GcalManager *manager) /** * gcal_manager_get_sources_connected: - * @manager: + * @manager: a #GcalManager * - * Returns a {@link GList} with every source connected on the app, whether they are enabled or not. + * Returns a #GList with every source connected on the app, + * whether they are enabled or not. * - * Returns: (Transfer full) a {@link GList} object to be freed with g_list_free() - **/ + * Returns: (nullable)(transfer container)(content-type ESource): a #GList + */ GList* gcal_manager_get_sources_connected (GcalManager *manager) { + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + return g_hash_table_get_keys (manager->clients); } /** * gcal_manager_get_default_source: - * @manager: App singleton {@link GcalManager} instance + * @manager: a #GcalManager * - * Returns: (Transfer full): an {@link ESource} object. Free with g_object_unref(). - **/ + * Returns: (transfer full): an #ESource object. Free + * with g_object_unref(). + */ ESource* gcal_manager_get_default_source (GcalManager *manager) { + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + return e_source_registry_ref_default_calendar (manager->source_registry); } /** * gcal_manager_set_default_source: - * @manager: App singleton {@link GcalManager} instance + * @manager: a #GcalManager * @source: the new default source. * - * Returns: - **/ + * Sets the default calendar. + */ void gcal_manager_set_default_source (GcalManager *manager, ESource *source) { + g_return_if_fail (GCAL_IS_MANAGER (manager)); + e_source_registry_set_default_calendar (manager->source_registry, source); } +/** + * gcal_manager_get_system_timezone: + * @manager: a #GcalManager + * + * Retireves the default timezone. + * + * Returns: (transfer none): the default timezone + */ icaltimezone* gcal_manager_get_system_timezone (GcalManager *manager) { + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + return manager->system_timezone; } +/** + * gcal_manager_setup_shell_search: + * @manager: a #GcalManager + * @subscriber: an #ECalDataModelSubscriber + * + * Sets up the GNOME Shell search subscriber. + */ void gcal_manager_setup_shell_search (GcalManager *self, ECalDataModelSubscriber *subscriber) @@ -1213,13 +1254,15 @@ gcal_manager_setup_shell_search (GcalManager *self, * @query: query string (an s-exp) * * Set the query terms of the #ECalDataModel used in the shell search - **/ + */ void gcal_manager_set_shell_search_query (GcalManager *manager, const gchar *query) { GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + manager->search_view_data->passed_start = FALSE; manager->search_view_data->search_done = FALSE; manager->search_view_data->sources_left = g_hash_table_size (manager->clients); @@ -1231,6 +1274,15 @@ gcal_manager_set_shell_search_query (GcalManager *manager, e_cal_data_model_set_filter (manager->shell_search_data_model, query); } +/** + * gcal_manager_set_shell_search_subscriber: + * @self: a #GcalManager + * @subscriber: the #ECalDataModelSubscriber to subscribe + * @range_start: the start of the range + * @range_end: the end of the range + * + * Subscribe @subscriber to the shell data modal at the given range. + */ void gcal_manager_set_shell_search_subscriber (GcalManager *manager, ECalDataModelSubscriber *subscriber, @@ -1244,12 +1296,30 @@ gcal_manager_set_shell_search_subscriber (GcalManager *manager, GCAL_EXIT; } +/** + * gcal_manager_shell_search_done: + * @self: a #GcalManager + * + * Retrieves whether the search at @manager is done or not. + * + * Returns: %TRUE if the search is finished. + */ gboolean gcal_manager_shell_search_done (GcalManager *manager) { + g_return_val_if_fail (GCAL_IS_MANAGER (manager), FALSE); + return manager->search_view_data->search_done; } +/** + * gcal_manager_get_shell_search_events: + * @self: a #GcalManager + * + * Retrieves all the events available for GNOME Shell search. + * + * Returns: (nullable)(transfer full)(content-type GcalEvent): a #GList + */ GList* gcal_manager_get_shell_search_events (GcalManager *manager) { @@ -1272,6 +1342,16 @@ gcal_manager_get_shell_search_events (GcalManager *manager) GCAL_RETURN (list); } +/** + * gcal_manager_set_subscriber: + * @self: a #GcalManager + * @subscriber: a #ECalDataModelSubscriber + * @range_start: the start of the range + * @range_end: the end of the range + * + * Sets the @subscriber to show events between @range_start + * and @range_end. + */ void gcal_manager_set_subscriber (GcalManager *manager, ECalDataModelSubscriber *subscriber, @@ -1280,6 +1360,8 @@ gcal_manager_set_subscriber (GcalManager *manager, { GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + e_cal_data_model_subscribe (manager->e_data_model, subscriber, range_start, @@ -1288,6 +1370,16 @@ gcal_manager_set_subscriber (GcalManager *manager, GCAL_EXIT; } +/** + * gcal_manager_set_search_subscriber: + * @self: a #GcalManager + * @subscriber: a #ECalDataModelSubscriber + * @range_start: the start of the range + * @range_end: the end of the range + * + * Sets the @subscriber to show events between @range_start + * and @range_end. + */ void gcal_manager_set_search_subscriber (GcalManager *manager, ECalDataModelSubscriber *subscriber, @@ -1296,6 +1388,8 @@ gcal_manager_set_search_subscriber (GcalManager *manager, { GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + e_cal_data_model_subscribe (manager->search_data_model, subscriber, range_start, @@ -1311,8 +1405,7 @@ gcal_manager_set_search_subscriber (GcalManager *manager, * * Set the query terms of the #ECalDataModel or clear it if %NULL is * passed - * - **/ + */ void gcal_manager_set_query (GcalManager *self, const gchar *query) @@ -1330,10 +1423,10 @@ gcal_manager_set_query (GcalManager *self, /** * gcal_manager_query_client_data: * - * Queries for a specific data field of - * the {@link ECalClient}. + * Queries for a specific data field of the #ECalClient * - * Returns: (Transfer none) a string representing the retrieved value, or NULL. + * Returns: (nullable)(transfer none): a string representing + * the retrieved value. */ gchar* gcal_manager_query_client_data (GcalManager *manager, @@ -1345,6 +1438,8 @@ gcal_manager_query_client_data (GcalManager *manager, GCAL_ENTRY; + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + unit = g_hash_table_lookup (manager->clients, source); if (!unit) @@ -1365,10 +1460,8 @@ gcal_manager_query_client_data (GcalManager *manager, * Add a new calendar by its URI. * The calendar is enabled by default * - * Return value: The UID of calendar's source, NULL in other case - * Returns: (transfer full): - * - * Since: 0.0.1 + * Returns: (nullable)(transfer full): unique identifier of calendar's source, or + * %NULL. */ gchar* gcal_manager_add_source (GcalManager *manager, @@ -1382,6 +1475,8 @@ gcal_manager_add_source (GcalManager *manager, GCAL_ENTRY; + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + source = e_source_new (NULL, NULL, NULL); extension = E_SOURCE_CALENDAR (e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR)); @@ -1427,6 +1522,9 @@ gcal_manager_enable_source (GcalManager *manager, GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + g_return_if_fail (E_IS_SOURCE (source)); + unit = g_hash_table_lookup (manager->clients, source); selectable = e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR); @@ -1469,6 +1567,9 @@ gcal_manager_disable_source (GcalManager *manager, GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + g_return_if_fail (E_IS_SOURCE (source)); + unit = g_hash_table_lookup (manager->clients, source); selectable = e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR); @@ -1511,6 +1612,9 @@ gcal_manager_save_source (GcalManager *manager, GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + g_return_if_fail (E_IS_SOURCE (source)); + e_source_registry_commit_source_sync (manager->source_registry, source, NULL, &error); if (error) @@ -1523,6 +1627,13 @@ gcal_manager_save_source (GcalManager *manager, GCAL_EXIT; } +/** + * gcal_manager_refresh: + * @manager: a #GcalManager + * + * Forces a full refresh and synchronization of all available + * calendars. + */ void gcal_manager_refresh (GcalManager *manager) { @@ -1531,6 +1642,8 @@ gcal_manager_refresh (GcalManager *manager) GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + clients = g_hash_table_get_values (manager->clients); /* refresh clients */ @@ -1552,6 +1665,15 @@ gcal_manager_refresh (GcalManager *manager) GCAL_EXIT; } +/** + * gcal_manager_is_client_writable: + * @manager: a #GcalManager + * @source: an #ESource + * + * Retrieves whether @source is writable. + * + * Returns: %TRUE if @source is writable, %FALSE otherwise. + */ gboolean gcal_manager_is_client_writable (GcalManager *manager, ESource *source) @@ -1568,9 +1690,16 @@ gcal_manager_is_client_writable (GcalManager *manager, GCAL_RETURN (unit->connected && !e_client_is_readonly (E_CLIENT (unit->client))); } +/** + * gcal_manager_create_event: + * @manager: a #GcalManager + * @event: a #GcalEvent + * + * Creates @event. + */ void -gcal_manager_create_event (GcalManager *manager, - GcalEvent *event) +gcal_manager_create_event (GcalManager *manager, + GcalEvent *event) { GcalManagerUnit *unit; icalcomponent *new_event_icalcomp; @@ -1580,6 +1709,9 @@ gcal_manager_create_event (GcalManager *manager, GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + g_return_if_fail (GCAL_IS_EVENT (event)); + source = gcal_event_get_source (event); component = gcal_event_get_component (event); unit = g_hash_table_lookup (manager->clients, source); @@ -1599,6 +1731,13 @@ gcal_manager_create_event (GcalManager *manager, GCAL_EXIT; } +/** + * gcal_manager_update_event: + * @manager: a #GcalManager + * @event: a #GcalEvent + * + * Saves all changes made to @event persistently. + */ void gcal_manager_update_event (GcalManager *manager, GcalEvent *event) @@ -1608,6 +1747,9 @@ gcal_manager_update_event (GcalManager *manager, GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + g_return_if_fail (GCAL_IS_EVENT (event)); + unit = g_hash_table_lookup (manager->clients, gcal_event_get_source (event)); component = gcal_event_get_component (event); @@ -1628,9 +1770,16 @@ gcal_manager_update_event (GcalManager *manager, GCAL_EXIT; } +/** + * gcal_manager_remove_event: + * @manager: a #GcalManager + * @event: a #GcalEvent + * + * Deletes @event. + */ void -gcal_manager_remove_event (GcalManager *manager, - GcalEvent *event) +gcal_manager_remove_event (GcalManager *manager, + GcalEvent *event) { GcalManagerUnit *unit; ECalComponentId *id; @@ -1638,6 +1787,9 @@ gcal_manager_remove_event (GcalManager *manager, GCAL_ENTRY; + g_return_if_fail (GCAL_IS_MANAGER (manager)); + g_return_if_fail (GCAL_IS_EVENT (event)); + component = gcal_event_get_component (event); unit = g_hash_table_lookup (manager->clients, gcal_event_get_source (event)); id = e_cal_component_get_id (component); @@ -1662,6 +1814,16 @@ gcal_manager_remove_event (GcalManager *manager, GCAL_EXIT; } +/** + * gcal_manager_move_event_to_source: + * @manager: a #GcalManager + * @event: a #GcalEvent + * @dest: the destination calendar + * + * Moves @event to @dest calendar. This is a fail-safe operation: + * worst case, the user will have two duplicated events, and we + * guarantee to never loose any data. + */ void gcal_manager_move_event_to_source (GcalManager *manager, GcalEvent *event, @@ -1677,6 +1839,8 @@ gcal_manager_move_event_to_source (GcalManager *manager, GCAL_ENTRY; g_return_if_fail (GCAL_IS_MANAGER (manager)); + g_return_if_fail (GCAL_IS_EVENT (event)); + g_return_if_fail (E_IS_SOURCE (dest)); error = NULL; @@ -1732,11 +1896,15 @@ gcal_manager_move_event_to_source (GcalManager *manager, /** * gcal_manager_get_events: + * @manager: a #GcalManager + * @start_date: the start of the dete range + * @end_date: the end of the dete range * - * Returns a list with {@link GcalEvent} objects owned by the caller, the list and the objects. - * The components inside the list are owned by the caller as well. So, don't ref the component. + * Returns a list with #GcalEvent objects owned by the caller, + * the list and the objects. The components inside the list are + * owned by the caller as well. * - * Returns: An {@link GList} object + * Returns: (nullable)(transfer full)(content-type GcalEvent):a #GList */ GList* gcal_manager_get_events (GcalManager *manager, @@ -1748,14 +1916,30 @@ gcal_manager_get_events (GcalManager *manager, GCAL_ENTRY; + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + range_start = icaltime_as_timet_with_zone (*start_date, manager->system_timezone); range_end = icaltime_as_timet_with_zone (*end_date, manager->system_timezone); - e_cal_data_model_foreach_component (manager->e_data_model, range_start, range_end, gather_events, &list); + e_cal_data_model_foreach_component (manager->e_data_model, + range_start, + range_end, + gather_events, + &list); GCAL_RETURN (list); } +/** + * gcal_manager_get_loading: + * @self: a #GcalManager + * + * Retrieves whether @self is still loading or not. Loading is + * complete when the Online Accounts client is retrieved, and all + * the calendars are loaded. + * + * Returns: %TRUE if manager is still loading; %FALSE otherwise + */ gboolean gcal_manager_get_loading (GcalManager *self) { @@ -1764,6 +1948,15 @@ gcal_manager_get_loading (GcalManager *self) return !self->goa_client_ready || self->sources_at_launch > 0; } +/** + * gcal_manager_get_event_from_shell_search: + * @manager: a #GcalManager + * @uuid: the unique identier of the event + * + * Retrieves the #GcalEvent with @uuid. + * + * Returns: (nullable)(transfer full): a #GcalEvent + */ GcalEvent* gcal_manager_get_event_from_shell_search (GcalManager *manager, const gchar *uuid) @@ -1774,12 +1967,21 @@ gcal_manager_get_event_from_shell_search (GcalManager *manager, GCAL_ENTRY; + g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL); + list = NULL; new_event = NULL; - e_cal_data_model_get_subscriber_range (manager->shell_search_data_model, manager->search_view_data->subscriber, - &range_start, &range_end); - e_cal_data_model_foreach_component (manager->shell_search_data_model, range_start, range_end, gather_events, &list); + e_cal_data_model_get_subscriber_range (manager->shell_search_data_model, + manager->search_view_data->subscriber, + &range_start, + &range_end); + + e_cal_data_model_foreach_component (manager->shell_search_data_model, + range_start, + range_end, + gather_events, + &list); for (l = list; l != NULL; l = g_list_next (l)) { @@ -1799,12 +2001,20 @@ gcal_manager_get_event_from_shell_search (GcalManager *manager, GCAL_RETURN (new_event); } +/** + * gcal_manager_get_goa_client: + * @self: a #GcalManager + * + * Retrieves the #GoaClient connected by @self. + * + * Returns: (transfer none): a #GoaClient + */ GoaClient* -gcal_manager_get_goa_client (GcalManager *manager) +gcal_manager_get_goa_client (GcalManager *self) { - g_return_val_if_fail (GCAL_IS_MANAGER (manager), FALSE); - GCAL_ENTRY; - GCAL_RETURN (manager->goa_client); + g_return_val_if_fail (GCAL_IS_MANAGER (self), NULL); + + GCAL_RETURN (self->goa_client); } diff --git a/src/gcal-source-dialog.c b/src/gcal-source-dialog.c index 42759e51..dfd30a44 100644 --- a/src/gcal-source-dialog.c +++ b/src/gcal-source-dialog.c @@ -26,6 +26,19 @@ #include <goa/goa.h> #include <libedataserverui/libedataserverui.h> +/** + * SECTION:gcal-source-dialog + * @short_description: Dialog to manage calendars + * @title:GcalSourceDialog + * @stability:unstable + * @image:gcal-source-dialog.png + * + * #GcalSourceDialog is the calendar management widget of GNOME + * Calendar. With it, users can create calendars from local files, + * local calendars or even import calendars from the Web or their + * online accounts. + */ + struct _GcalSourceDialog { GtkDialog parent; @@ -239,7 +252,7 @@ add_button_clicked (GtkWidget *button, if (self->source != NULL) { - // Commit the new source + /* Commit the new source */ gcal_manager_save_source (self->manager, self->source); self->source = NULL; @@ -251,14 +264,14 @@ add_button_clicked (GtkWidget *button, { GList *l; - // Commit each new remote source + /* Commit each new remote source */ for (l = self->remote_sources; l != NULL; l = l->next) gcal_manager_save_source (self->manager, l->data); g_list_free (self->remote_sources); self->remote_sources = NULL; - // Go back to overview + /* Go back to overview */ gcal_source_dialog_set_mode (GCAL_SOURCE_DIALOG (user_data), GCAL_SOURCE_DIALOG_MODE_NORMAL); } } @@ -311,16 +324,6 @@ add_source (GcalManager *manager, g_list_free (children); } -/** - * action_widget_activated: - * @widget: the button which emited the signal. - * @user_data: a {@link GcalSourceDialog} instance. - * - * Emit a response when action buttons - * are clicked. - * - * Returns: - */ static void action_widget_activated (GtkWidget *widget, gpointer user_data) @@ -333,13 +336,6 @@ action_widget_activated (GtkWidget *widget, gtk_dialog_response (GTK_DIALOG (user_data), response); } -/** - * back_button_clicked: - * - * Returns to the previous page. - * - * Returns: - */ static void back_button_clicked (GtkButton *button, gpointer user_data) @@ -348,10 +344,10 @@ back_button_clicked (GtkButton *button, if (gtk_stack_get_visible_child (GTK_STACK (self->stack)) == self->edit_grid) { - // Save the source before leaving + /* Save the source before leaving */ gcal_manager_save_source (self->manager, self->source); - // Release the source ref we acquired + /* Release the source ref we acquired */ g_clear_object (&self->source); } @@ -370,11 +366,11 @@ calendar_listbox_sort_func (GtkListBoxRow *row1, self = GCAL_SOURCE_DIALOG (user_data); - // first source + /* first source */ source1 = g_object_get_data (G_OBJECT (row1), "source"); is_goa1 = is_goa_source (GCAL_SOURCE_DIALOG (user_data), source1); - // second source + /* second source */ source2 = g_object_get_data (G_OBJECT (row2), "source"); is_goa2 = is_goa_source (GCAL_SOURCE_DIALOG (user_data), source2); @@ -383,13 +379,13 @@ calendar_listbox_sort_func (GtkListBoxRow *row1, gchar *parent_name1 = NULL; gchar *parent_name2 = NULL; - // Retrieve parent names + /* Retrieve parent names */ get_source_parent_name_color (self->manager, source1, &parent_name1, NULL); get_source_parent_name_color (self->manager, source2, &parent_name2, NULL); retval = g_strcmp0 (parent_name1, parent_name2); - // If they have the same parent names, compare by the source display names + /* If they have the same parent names, compare by the source display names */ if (retval == 0) retval = g_strcmp0 (e_source_get_display_name (source1), e_source_get_display_name (source2)); @@ -398,7 +394,7 @@ calendar_listbox_sort_func (GtkListBoxRow *row1, } else { - // If one is a GOA account and the other isn't, make the GOA one go first + /* If one is a GOA account and the other isn't, make the GOA one go first */ retval = is_goa1 ? -1 : 1; } @@ -424,10 +420,10 @@ cancel_button_clicked (GtkWidget *button, { GcalSourceDialog *self = GCAL_SOURCE_DIALOG (user_data); - // Destroy the ongoing created source + /* Destroy the ongoing created source */ g_clear_object (&self->source); - // Cleanup detected remote sources that weren't added + /* Cleanup detected remote sources that weren't added */ if (self->remote_sources != NULL) { g_list_free_full (self->remote_sources, g_object_unref); @@ -437,13 +433,6 @@ cancel_button_clicked (GtkWidget *button, gcal_source_dialog_set_mode (GCAL_SOURCE_DIALOG (user_data), GCAL_SOURCE_DIALOG_MODE_NORMAL); } -/** - * clear_pages: - * - * Clear local and web pages. - * - * Returns: - */ static void clear_pages (GcalSourceDialog *dialog) { @@ -452,7 +441,7 @@ clear_pages (GcalSourceDialog *dialog) gtk_entry_set_text (GTK_ENTRY (dialog->calendar_address_entry), ""); gtk_widget_set_sensitive (dialog->add_button, FALSE); - // Remove discovered web sources (if any) + /* Remove discovered web sources (if any) */ list = gtk_container_get_children (GTK_CONTAINER (dialog->web_sources_listbox)); g_list_free_full (list, (GDestroyNotify) gtk_widget_destroy); @@ -500,15 +489,6 @@ default_check_toggled (GObject *object, gcal_manager_set_default_source (self->manager, self->old_default_source); } - -/** - * description_label_link_activated: - * - * Show GNOME Control Center when - * the label's link is pressed. - * - * Returns: - */ static gboolean description_label_link_activated (GtkWidget *widget, gchar *uri, @@ -520,12 +500,6 @@ description_label_link_activated (GtkWidget *widget, return TRUE; } -/** - * display_header_func: - * - * Shows a separator before each row. - * - */ static void display_header_func (GtkListBoxRow *row, GtkListBoxRow *before, @@ -540,14 +514,6 @@ display_header_func (GtkListBoxRow *row, } } -/** - * is_goa_source: - * - * Checks whether the source comes from - * a online account. - * - * Returns: %TRUE if the source came from a GOA account - */ static gboolean is_goa_source (GcalSourceDialog *dialog, ESource *source) @@ -599,14 +565,6 @@ invalidate_calendar_listbox_sort (GObject *source, gtk_list_box_invalidate_sort (GTK_LIST_BOX (user_data)); } -/** - * make_row_from_source: - * - * Create a GtkListBoxRow for a given - * ESource. - * - * Returns: (transfer full) the new row - */ static GtkWidget* make_row_from_source (GcalSourceDialog *dialog, ESource *source) @@ -658,17 +616,6 @@ make_row_from_source (GcalSourceDialog *dialog, return row; } -/** - * name_entry_text_changed: - * - * Callend when the name entry's text - * is edited. It changes the source's - * display name, but wait's for the - * calendar's ::response signal to - * commit these changes. - * - * Returns: - */ static void name_entry_text_changed (GObject *object, GParamSpec *pspec, @@ -677,6 +624,14 @@ name_entry_text_changed (GObject *object, GcalSourceDialog *self = GCAL_SOURCE_DIALOG (user_data); gboolean valid = gtk_entry_get_text_length (GTK_ENTRY (object)) > 0; + /* + * Callend when the name entry's text + * is edited. It changes the source's + * display name, but wait's for the + * calendar's ::response signal to + * commit these changes. + */ + gtk_widget_set_sensitive (self->back_button, valid); gtk_widget_set_sensitive (self->add_button, valid); @@ -695,13 +650,6 @@ spawn_goa_with_args (const gchar *action, NULL, NULL, NULL, NULL); } -/** - * online_accounts_listbox_row_activated: - * - * Selects the online account, or add one. - * - * Returns: - */ static void online_accounts_listbox_row_activated (GtkListBox *box, GtkListBoxRow *row, @@ -736,14 +684,6 @@ online_accounts_listbox_row_activated (GtkListBox *box, } } -/** - * response_signal: - * - * Save the source when the dialog - * is close. - * - * Returns: - */ static void response_signal (GtkDialog *dialog, gint response_id, @@ -751,19 +691,19 @@ response_signal (GtkDialog *dialog, { GcalSourceDialog *self = GCAL_SOURCE_DIALOG (dialog); - /* save the source */ + /* Save the source */ if (self->mode == GCAL_SOURCE_DIALOG_MODE_EDIT && self->source != NULL) { gcal_manager_save_source (self->manager, self->source); g_clear_object (&self->source); } - /* commit the new source; save the current page's source */ + /* Commit the new source; save the current page's source */ if (self->mode == GCAL_SOURCE_DIALOG_MODE_NORMAL && response_id == GTK_RESPONSE_APPLY && self->remote_sources != NULL) { GList *l; - // Commit each new remote source + /* Commit each new remote source */ for (l = self->remote_sources; l != NULL; l = l->next) gcal_manager_save_source (self->manager, l->data); @@ -800,7 +740,7 @@ is_remote_source (ESource *source) auth = e_source_get_extension (source, E_SOURCE_EXTENSION_AUTHENTICATION); - // No host is set, it's not a remote source + /* No host is set, it's not a remote source */ if (e_source_authentication_get_host (auth) == NULL) return FALSE; } @@ -811,7 +751,7 @@ is_remote_source (ESource *source) webdav = e_source_get_extension (source, E_SOURCE_EXTENSION_WEBDAV_BACKEND); - // No resource path specified, not a remote source + /* No resource path specified, not a remote source */ if (e_source_webdav_get_resource_path (webdav) == NULL) return FALSE; } @@ -876,7 +816,7 @@ stack_visible_child_name_changed (GObject *object, get_source_parent_name_color (self->manager, self->source, &parent_name, NULL); - // update headerbar buttons + /* update headerbar buttons */ gtk_header_bar_set_show_close_button (GTK_HEADER_BAR (self->headerbar), !creation_mode); gtk_widget_set_visible (self->calendar_visible_check, !creation_mode); gtk_widget_set_visible (self->back_button, !creation_mode); @@ -885,7 +825,7 @@ stack_visible_child_name_changed (GObject *object, gtk_widget_set_visible (self->account_box, is_goa); gtk_widget_set_visible (self->calendar_url_button, !is_goa && (is_file || is_remote)); - // If it's a file, set the file path + /* If it's a file, set the file path */ if (is_file) { ESourceLocal *local; @@ -902,7 +842,7 @@ stack_visible_child_name_changed (GObject *object, g_free (uri); } - // If it's remote, build the uri + /* If it's remote, build the uri */ if (is_remote) { ESourceAuthentication *auth; @@ -940,7 +880,7 @@ stack_visible_child_name_changed (GObject *object, /* entry */ gtk_entry_set_text (GTK_ENTRY (self->name_entry), e_source_get_display_name (self->source)); - // enabled check + /* enabled check */ gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (self->calendar_visible_check), is_source_enabled (self->source)); @@ -968,14 +908,6 @@ stack_visible_child_name_changed (GObject *object, } } -/** - * calendar_file_selected: - * - * Opens a file selector dialog and - * parse the resulting selection. - * - * Returns: - */ static void calendar_file_selected (GtkFileChooser *button, gpointer user_data) @@ -1007,23 +939,13 @@ calendar_file_selected (GtkFileChooser *button, /* update the source properties */ e_source_set_display_name (source, g_file_get_basename (file)); - // Jump to the edit page + /* Jump to the edit page */ gcal_source_dialog_set_source (GCAL_SOURCE_DIALOG (user_data), source); gcal_source_dialog_set_mode (GCAL_SOURCE_DIALOG (user_data), GCAL_SOURCE_DIALOG_MODE_CREATE); gtk_widget_set_sensitive (self->add_button, TRUE); } -/** - * calendar_listbox_row_activated: - * - * Edits the selected calendar for the - * 'Calendars' listbox or goes to the - * calendar selection for the Online - * Accounts listbox. - * - * Returns: - */ static void calendar_listbox_row_activated (GtkListBox *box, GtkListBoxRow *row, @@ -1046,13 +968,6 @@ calendar_listbox_row_activated (GtkListBox *box, } } -/** - * pulse_web_entry: - * - * Update the url's entry with a pulse fraction. - * - * Returns: FALSE - */ static gboolean pulse_web_entry (GcalSourceDialog *dialog) { @@ -1063,14 +978,6 @@ pulse_web_entry (GcalSourceDialog *dialog) return FALSE; } -/** - * url_entry_text_changed: - * - * Performs a validation of the URL - * 1 second after the user inputs. - * - * Returns: - */ static void url_entry_text_changed (GObject *object, GParamSpec *pspec, @@ -1098,7 +1005,7 @@ url_entry_text_changed (GObject *object, if (g_utf8_strlen (text, -1) != 0) { - // Remove any previous unreleased resource + /* Remove any previous unreleased resource */ if (self->validate_url_resource_id != 0) g_source_remove (self->validate_url_resource_id); @@ -1117,14 +1024,6 @@ url_entry_text_changed (GObject *object, } } -/** - * online_accounts_settings_button_clicked: - * - * Spawns the GNOME Control Center app - * with Online Accounts openned. - * - * Returns: - */ static void online_accounts_settings_button_clicked (GtkWidget *button, gpointer user_data) @@ -1141,7 +1040,7 @@ on_file_activated (GSimpleAction *action, GtkFileFilter *filter; gint response; - // Dialog + /* Dialog */ dialog = gtk_file_chooser_dialog_new (_("Select a calendar file"), GTK_WINDOW (gtk_widget_get_toplevel (GTK_WIDGET (user_data))), GTK_FILE_CHOOSER_ACTION_SAVE, @@ -1151,7 +1050,7 @@ on_file_activated (GSimpleAction *action, g_signal_connect (dialog, "file-activated", G_CALLBACK (calendar_file_selected), user_data); - // File filter + /* File filter */ filter = gtk_file_filter_new (); gtk_file_filter_set_name (filter, _("Calendar files")); gtk_file_filter_add_mime_type (filter, "text/calendar"); @@ -1166,14 +1065,6 @@ on_file_activated (GSimpleAction *action, gtk_widget_destroy (dialog); } -/** - * on_local_activated: - * - * Creates a new local calendar, and let - * the user adjust the settings after. - * - * Returns: - */ static void on_local_activated (GSimpleAction *action, GVariant *param, @@ -1197,21 +1088,13 @@ on_local_activated (GSimpleAction *action, /* update the source properties */ e_source_set_display_name (source, _("Unnamed Calendar")); - // Jump to the edit page + /* Jump to the edit page */ gcal_source_dialog_set_source (GCAL_SOURCE_DIALOG (user_data), source); gcal_source_dialog_set_mode (GCAL_SOURCE_DIALOG (user_data), GCAL_SOURCE_DIALOG_MODE_CREATE); gtk_widget_set_sensitive (self->add_button, TRUE); } -/** - * on_web_activated: - * - * Redirect to the web calendar creation - * page - * - * Returns: - */ static void on_web_activated (GSimpleAction *action, GVariant *param, @@ -1229,14 +1112,6 @@ calendar_address_activated (GtkEntry *entry, validate_url_cb (GCAL_SOURCE_DIALOG (user_data)); } -/** - * validate_url_cb: - * - * Query the given URL for possible - * calendar data. - * - * Returns:FALSE - */ static gboolean validate_url_cb (GcalSourceDialog *dialog) { @@ -1260,15 +1135,15 @@ validate_url_cb (GcalSourceDialog *dialog) dialog->remote_sources = NULL; } - // Remove previous results + /* Remove previous results */ g_list_free_full (gtk_container_get_children (GTK_CONTAINER (dialog->web_sources_listbox)), (GDestroyNotify) gtk_widget_destroy); gtk_revealer_set_reveal_child (GTK_REVEALER (dialog->web_sources_revealer), FALSE); - // Clear the entry icon + /* Clear the entry icon */ gtk_entry_set_icon_from_icon_name (GTK_ENTRY (dialog->calendar_address_entry), GTK_ENTRY_ICON_SECONDARY, NULL); - // Get the hostname and file path from the server + /* Get the hostname and file path from the server */ uri_valid = uri_get_fields (gtk_entry_get_text (GTK_ENTRY (dialog->calendar_address_entry)), NULL, &host, &path); g_debug ("[source-dialog] host: '%s', path: '%s'", host, path); @@ -1286,11 +1161,11 @@ validate_url_cb (GcalSourceDialog *dialog) ext = e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR); e_source_backend_set_backend_name (E_SOURCE_BACKEND (ext), "webcal"); - // Authentication + /* Authentication */ auth = e_source_get_extension (source, E_SOURCE_EXTENSION_AUTHENTICATION); e_source_authentication_set_host (auth, host); - // Webdav + /* Webdav */ webdav = e_source_get_extension (source, E_SOURCE_EXTENSION_WEBDAV_BACKEND); e_source_webdav_set_resource_path (webdav, path); @@ -1301,17 +1176,17 @@ validate_url_cb (GcalSourceDialog *dialog) */ if (g_str_has_suffix (path, ".ics")) { - // Set the private source so it saves at closing + /* Set the private source so it saves at closing */ dialog->remote_sources = g_list_append (dialog->remote_sources, source); - // Update buttons + /* Update buttons */ gtk_widget_set_sensitive (dialog->add_button, source != NULL); } else { ENamedParameters *credentials; - // Pulse the entry while it performs the check + /* Pulse the entry while it performs the check */ dialog->calendar_address_id = g_timeout_add (ENTRY_PROGRESS_TIMEOUT, (GSourceFunc) pulse_web_entry, dialog); /* @@ -1325,7 +1200,7 @@ validate_url_cb (GcalSourceDialog *dialog) { g_debug ("[source-dialog] Trying to connect without credentials..."); - // NULL credentials + /* NULL credentials */ e_named_parameters_set (credentials, E_SOURCE_CREDENTIAL_USERNAME, NULL); e_named_parameters_set (credentials, E_SOURCE_CREDENTIAL_PASSWORD, NULL); @@ -1349,7 +1224,7 @@ validate_url_cb (GcalSourceDialog *dialog) */ if (response == GTK_RESPONSE_OK) { - // User inputted credentials + /* User inputted credentials */ e_named_parameters_set (credentials, E_SOURCE_CREDENTIAL_USERNAME, user); e_named_parameters_set (credentials, E_SOURCE_CREDENTIAL_PASSWORD, password); @@ -1398,13 +1273,13 @@ prompt_credentials (GcalSourceDialog *dialog, { gint response; - // Cleanup last credentials + /* Cleanup last credentials */ gtk_entry_set_text (GTK_ENTRY (dialog->credentials_password_entry), ""); gtk_entry_set_text (GTK_ENTRY (dialog->credentials_user_entry), ""); gtk_widget_grab_focus (dialog->credentials_user_entry); - // Show the dialog, then destroy it + /* Show the dialog, then destroy it */ response = gtk_dialog_run (GTK_DIALOG (dialog->credentials_dialog)); if (response == GTK_RESPONSE_OK) @@ -1435,7 +1310,7 @@ duplicate_source (ESource *source) ext = e_source_get_extension (new_source, E_SOURCE_EXTENSION_CALENDAR); e_source_backend_set_backend_name (E_SOURCE_BACKEND (ext), "local"); - // Copy Authentication data + /* Copy Authentication data */ if (e_source_has_extension (source, E_SOURCE_EXTENSION_AUTHENTICATION)) { ESourceAuthentication *new_auth, *parent_auth; @@ -1450,7 +1325,7 @@ duplicate_source (ESource *source) e_source_authentication_set_proxy_uid (new_auth, e_source_authentication_get_proxy_uid (parent_auth)); } - // Copy Webdav data + /* Copy Webdav data */ if (e_source_has_extension (source, E_SOURCE_EXTENSION_WEBDAV_BACKEND)) { ESourceWebdav *new_webdav, *parent_webdav; @@ -1507,7 +1382,7 @@ discover_sources_cb (GObject *source, self = GCAL_SOURCE_DIALOG (user_data); error = NULL; - // Stop the pulsing entry + /* Stop the pulsing entry */ if (self->calendar_address_id != 0) { gtk_entry_set_progress_fraction (GTK_ENTRY (self->calendar_address_entry), 0); @@ -1518,7 +1393,7 @@ discover_sources_cb (GObject *source, if (!e_webdav_discover_sources_finish (E_SOURCE (source), result, NULL, NULL, &discovered_sources, &user_addresses, &error)) { - // Don't add an source with errors + /* Don't add an source with errors */ gtk_widget_set_sensitive (self->add_button, FALSE); /* @@ -1543,15 +1418,15 @@ discover_sources_cb (GObject *source, return; } - // Add a success icon to the entry + /* Add a success icon to the entry */ gtk_entry_set_icon_from_icon_name (GTK_ENTRY (self->calendar_address_entry), GTK_ENTRY_ICON_SECONDARY, "emblem-ok-symbolic"); - // Remove previous results + /* Remove previous results */ g_list_free_full (gtk_container_get_children (GTK_CONTAINER (self->web_sources_listbox)), (GDestroyNotify) gtk_widget_destroy); - // Show the list of calendars + /* Show the list of calendars */ gtk_revealer_set_reveal_child (GTK_REVEALER (self->web_sources_revealer), TRUE); gtk_widget_show (self->web_sources_revealer); @@ -1563,7 +1438,7 @@ discover_sources_cb (GObject *source, src = aux->data; - // Get the new resource path from the uri + /* Get the new resource path from the uri */ uri_valid = uri_get_fields (src->href, NULL, NULL, &resource_path); if (uri_valid) @@ -1606,7 +1481,7 @@ discover_sources_cb (GObject *source, g_free (resource_path); } - // Free things up + /* Free things up */ e_webdav_discover_free_discovered_sources (discovered_sources); g_slist_free_full (user_addresses, g_free); } @@ -1671,7 +1546,7 @@ notification_child_revealed_changed (GtkWidget *notification, if (!e_source_get_removable (self->removed_source)) return; - // Enable the source again to remove it's name from disabled list + /* Enable the source again to remove it's name from disabled list */ gcal_manager_enable_source (self->manager, self->removed_source); e_source_remove_sync (self->removed_source, NULL, &error); @@ -1712,7 +1587,7 @@ undo_remove_action (GtkButton *button, /* if there's any set source, unremove it */ if (self->removed_source != NULL) { - // Enable the source before adding it again + /* Enable the source before adding it again */ gcal_manager_enable_source (self->manager, self->removed_source); add_source (self->manager, @@ -1726,7 +1601,7 @@ undo_remove_action (GtkButton *button, */ self->removed_source = NULL; - // Hide notification + /* Hide notification */ gtk_revealer_set_reveal_child (GTK_REVEALER (self->notification), FALSE); } } @@ -1788,7 +1663,7 @@ remove_button_clicked (GtkWidget *button, gtk_revealer_set_reveal_child (GTK_REVEALER (self->notification), TRUE); - // Remove the listbox entry (if any) + /* Remove the listbox entry (if any) */ for (l = children; l != NULL; l = l->next) { if (g_object_get_data (l->data, "source") == self->removed_source) @@ -1798,17 +1673,17 @@ remove_button_clicked (GtkWidget *button, } } - // Update notification label + /* Update notification label */ str = g_markup_printf_escaped (_("Calendar <b>%s</b> removed"), e_source_get_display_name (self->removed_source)); gtk_label_set_markup (GTK_LABEL (self->notification_label), str); - // Remove old notifications + /* Remove old notifications */ if (self->notification_timeout_id != 0) g_source_remove (self->notification_timeout_id); self->notification_timeout_id = g_timeout_add_seconds (5, hide_notification_scheduled, user_data); - // Disable the source, so it gets hidden + /* Disable the source, so it gets hidden */ gcal_manager_disable_source (self->manager, self->removed_source); g_list_free (children); @@ -1840,7 +1715,7 @@ gcal_source_dialog_constructed (GObject *object) g_object_set_data (G_OBJECT (self->remove_button), "response", GINT_TO_POINTER (GCAL_RESPONSE_REMOVE_SOURCE)); - // Setup listbox header functions + /* Setup listbox header functions */ gtk_list_box_set_header_func (GTK_LIST_BOX (self->calendars_listbox), display_header_func, NULL, NULL); gtk_list_box_set_sort_func (GTK_LIST_BOX (self->calendars_listbox), (GtkListBoxSortFunc) calendar_listbox_sort_func, object, NULL); @@ -1849,13 +1724,13 @@ gcal_source_dialog_constructed (GObject *object) gtk_list_box_set_sort_func (GTK_LIST_BOX (self->online_accounts_listbox), (GtkListBoxSortFunc) online_accounts_listbox_sort_func, object, NULL); - // Action group + /* Action group */ self->action_group = g_simple_action_group_new (); gtk_widget_insert_action_group (GTK_WIDGET (object), "source", G_ACTION_GROUP (self->action_group)); g_action_map_add_action_entries (G_ACTION_MAP (self->action_group), actions, G_N_ELEMENTS (actions), object); - // Load the "Add" button menu + /* Load the "Add" button menu */ builder = gtk_builder_new_from_resource ("/org/gnome/calendar/gtk/menus.ui"); menu = G_MENU_MODEL (gtk_builder_get_object (builder, "add-source-menu")); @@ -2186,11 +2061,11 @@ loading_changed_cb (GcalSourceDialog *dialog) /** * gcal_source_dialog_set_manager: + * @dialog: a #GcalSourceDialog + * @manager: a #GcalManager * - * Setup the {@link GcalManager} singleton + * Setup the #GcalManager singleton * instance of the application. - * - * Returns: */ void gcal_source_dialog_set_manager (GcalSourceDialog *dialog, @@ -2221,13 +2096,12 @@ gcal_source_dialog_set_manager (GcalSourceDialog *dialog, /** * gcal_source_dialog_set_mode: + * @dialog: a #GcalSourceDialog + * @mode: a #GcalSourceDialogMode * - * Set the source dialog mode. Creation - * mode means that a new calendar will - * be created, while edit mode means a - * calendar will be edited. - * - * Returns: + * Set the source dialog mode. Creation mode means that a new + * calendar will be created, while edit mode means a calendar + * will be edited. */ void gcal_source_dialog_set_mode (GcalSourceDialog *dialog, @@ -2237,7 +2111,7 @@ gcal_source_dialog_set_mode (GcalSourceDialog *dialog, dialog->mode = mode; - // Cleanup old data + /* Cleanup old data */ clear_pages (dialog); switch (mode) @@ -2258,7 +2132,7 @@ gcal_source_dialog_set_mode (GcalSourceDialog *dialog, break; case GCAL_SOURCE_DIALOG_MODE_EDIT: - // Bind title + /* Bind title */ if (dialog->title_bind == NULL) { dialog->title_bind = g_object_bind_property (dialog->name_entry, "text", dialog->headerbar, "title", @@ -2287,10 +2161,10 @@ gcal_source_dialog_set_mode (GcalSourceDialog *dialog, /** * gcal_source_dialog_set_source: + * @dialog: a #GcalSourceDialog + * @source: an #ESource * * Sets the source to be edited by the user. - * - * Returns: */ void gcal_source_dialog_set_source (GcalSourceDialog *dialog, diff --git a/src/gcal-source-dialog.h b/src/gcal-source-dialog.h index 4daf640f..11aec38f 100644 --- a/src/gcal-source-dialog.h +++ b/src/gcal-source-dialog.h @@ -35,6 +35,15 @@ G_BEGIN_DECLS G_DECLARE_FINAL_TYPE (GcalSourceDialog, gcal_source_dialog, GCAL, SOURCE_DIALOG, GtkDialog) +/** + * GcalSourceDialogMode: + * @GCAL_SOURCE_DIALOG_MODE_CREATE: creating a new calendar + * @GCAL_SOURCE_DIALOG_MODE_CREATE_WEB: creating a new web-based calendar + * @GCAL_SOURCE_DIALOG_MODE_EDIT: editing an existing calendar + * @GCAL_SOURCE_DIALOG_MODE_NORMAL: showing the list of calendars and online accounts + * + * The current action of the #GcalSourceDialog + */ typedef enum { GCAL_SOURCE_DIALOG_MODE_CREATE, diff --git a/src/gcal-utils.c b/src/gcal-utils.c index 5a9dfb36..d0646b11 100644 --- a/src/gcal-utils.c +++ b/src/gcal-utils.c @@ -36,6 +36,12 @@ #include <string.h> #include <math.h> +/** + * SECTION:gcal-utils + * @short_description: Utility functions + * @title:Utility functions + */ + static const gint ab_day[7] = { @@ -69,6 +75,16 @@ month_item[12] = G_DEFINE_BOXED_TYPE (icaltimetype, icaltime, gcal_dup_icaltime, g_free) +/** + * datetime_compare_date: + * @dt1: (nullable): a #GDateTime + * @dt2: (nullable): a #GDateTime + * + * Compares the dates of @dt1 and @dt2. The times are + * ignored. + * + * Returns: negative, 0 or positive + */ gint datetime_compare_date (GDateTime *dt1, GDateTime *dt2) @@ -92,6 +108,14 @@ datetime_compare_date (GDateTime *dt1, return 0; } +/** + * datetime_to_icaltime: + * @dt: a #GDateTime + * + * Converts the #GDateTime's @dt to an #icaltimetype. + * + * Returns: (transfer full): a #icaltimetype. + */ icaltimetype* datetime_to_icaltime (GDateTime *dt) { @@ -115,6 +139,15 @@ datetime_to_icaltime (GDateTime *dt) return idt; } +/** + * icaltime_to_datetime: + * @date: an #icaltimetype + * + * Converts the #icaltimetype's @date to a #GDateTime. The + * timezone is preserved. + * + * Returns: (transfer full): a #GDateTime. + */ GDateTime* icaltime_to_datetime (const icaltimetype *date) { @@ -135,6 +168,17 @@ icaltime_to_datetime (const icaltimetype *date) return dt; } +/** + * datetime_is_date: + * @dt: a #GDateTime + * + * Checks if @dt represents a date. A pure date + * has the values of hour, minutes and seconds set + * to 0. + * + * Returns: %TRUE if @dt is a date, %FALSE if it's a + * timed datetime. + */ gboolean datetime_is_date (GDateTime *dt) { @@ -143,6 +187,14 @@ datetime_is_date (GDateTime *dt) g_date_time_get_seconds (dt) == 0; } +/** + * gcal_dup_icaltime: + * @date: an #icaltimetype + * + * Creates an exact copy of @date. + * + * Returns: (transfer full): an #icaltimetype + */ icaltimetype* gcal_dup_icaltime (const icaltimetype *date) { @@ -166,12 +218,28 @@ gcal_dup_icaltime (const icaltimetype *date) return new_date; } +/** + * gcal_get_weekday: + * @i: the weekday index + * + * Retrieves the weekday name. + * + * Returns: (transfer full): the weekday name + */ gchar* gcal_get_weekday (gint i) { return nl_langinfo (ab_day[i]); } +/** + * gcal_get_month_name: + * @i: the month index + * + * Retrieves the month name. + * + * Returns: (transfer full): the month name + */ gchar* gcal_get_month_name (gint i) { @@ -179,14 +247,15 @@ gcal_get_month_name (gint i) } /** - * gcal_get_pixbuf_from_color: - * @color: - * @size: + * gcal_get_surface_from_color: + * @color: a #GdkRGBA + * @size: the size of the surface * - * Create a pixbuf of a simple {@link GdkRGBA} color. + * Creates a squared surface filled with @color. The + * surface is always @size x @size. * - * Returns: (Transfer full): An instance of {@link GdkPixbuf} to be freed with g_object_unref() - **/ + * Returns: (transfer full): a #cairo_surface_t + */ cairo_surface_t* gcal_get_surface_from_color (GdkRGBA *color, gint size) @@ -210,6 +279,16 @@ gcal_get_surface_from_color (GdkRGBA *color, return surface; } +/** + * get_circle_surface_from_color: + * @color: a #GdkRGBA + * @size: the size of the surface + * + * Creates a circular surface filled with @color. The + * surface is always @size x @size. + * + * Returns: (transfer full): a #cairo_surface_t + */ cairo_surface_t* get_circle_surface_from_color (GdkRGBA *color, gint size) @@ -232,8 +311,16 @@ get_circle_surface_from_color (GdkRGBA *color, return surface; } +/** + * get_color_name_from_source: + * @source: an #ESource + * @out_color: return value for the color + * + * Utility function to retrieve the color from @source. + */ void -get_color_name_from_source (ESource *source, GdkRGBA *out_color) +get_color_name_from_source (ESource *source, + GdkRGBA *out_color) { ESourceSelectable *extension = E_SOURCE_SELECTABLE (e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR)); @@ -244,13 +331,15 @@ get_color_name_from_source (ESource *source, GdkRGBA *out_color) /** * get_desc_from_component: - * @component: + * @component: an #ECalComponent + * @joint_char: the character to use when merging event comments * * Utility method to handle the extraction of the description from an * #ECalComponent. This cycle through the list of #ECalComponentText * and concatenate each string into one. * - * Returns: (Transfer full) a new allocated string with the description + * Returns: (nullable)(transfer full) a new allocated string with the + * description **/ gchar* get_desc_from_component (ECalComponent *component, @@ -387,7 +476,7 @@ get_first_weekday (void) * * Create a component with the provided details * - * Returns: (Transfer full): an {@link ECalComponent} object + * Returns: (transfer full): an {@link ECalComponent} object **/ ECalComponent* build_component_from_details (const gchar *summary, @@ -459,12 +548,15 @@ build_component_from_details (const gchar *summary, /** * icaltime_compare_date: - * @date1: - * @date2: + * @date1: an #icaltimetype + * @date2: an #icaltimetype + * + * Compare date parts of #icaltimetype objects. Returns negative value, + * 0 or positive value accordingly if @date1 is before, same day of + * after date2. * - * Compare date parts of {@link icaltimetype} objects. Return negative value, 0 or positive value - * accordingly if date1 is before, same day of after date2. - * As a bonus it returns the amount of days passed between two days on the same year. + * As a bonus it returns the amount of days passed between two days on the + * same year. * * Returns: negative, 0 or positive **/ @@ -484,6 +576,18 @@ icaltime_compare_date (const icaltimetype *date1, time_day_of_year (date2->day, date2->month - 1, date2->year); } +/** + * icaltime_compare_with_current: + * @date1: an #icaltimetype + * @date2: an #icaltimetype + * @current_time_t: the current time + * + * Compares @date1 and @date2 against the current time. Dates + * closer to the current date are sorted before. + * + * Returns: negative if @date1 comes after @date2, 0 if they're + * equal, positive otherwise + */ gint icaltime_compare_with_current (const icaltimetype *date1, const icaltimetype *date2, @@ -517,6 +621,17 @@ icaltime_compare_with_current (const icaltimetype *date1, return result; } +/** + * get_start_of_week: + * @date: an #icaltimetype + * + * Retrieves the start of the week that @date + * falls in. This function already takes the + * first weekday into account. + * + * Returns: (transfer full): a #GDateTime with + * the start of the week. + */ GDateTime* get_start_of_week (icaltimetype *date) { @@ -541,6 +656,17 @@ get_start_of_week (icaltimetype *date) return dt; } +/** + * get_end_of_week: + * @date: an #icaltimetype + * + * Retrieves the end of the week that @date + * falls in. This function already takes the + * first weekday into account. + * + * Returns: (transfer full): a #GDateTime with + * the end of the week. + */ GDateTime* get_end_of_week (icaltimetype *date) { @@ -554,6 +680,15 @@ get_end_of_week (icaltimetype *date) return week_end; } +/** + * is_clock_format_24h: + * + * Retrieves whether the current clock format is + * 12h or 24h based. + * + * Returns: %TRUE if the clock format is 24h, %FALSE + * otherwise. + */ gboolean is_clock_format_24h (void) { @@ -568,7 +703,10 @@ is_clock_format_24h (void) return g_strcmp0 (clock_format, "24h") == 0; } -/* Function to do a last minute fixup of the AM/PM stuff if the locale +/** + * e_strftime_fix_am_pm: + * + * Function to do a last minute fixup of the AM/PM stuff if the locale * and gettext haven't done it right. Most English speaking countries * except the USA use the 24 hour clock (UK, Australia etc). However * since they are English nobody bothers to write a language @@ -584,7 +722,6 @@ is_clock_format_24h (void) * TODO: Actually remove the '%p' from the fixed up string so that * there isn't a stray space. */ - gsize e_strftime_fix_am_pm (gchar *str, gsize max, @@ -627,6 +764,14 @@ e_strftime_fix_am_pm (gchar *str, return (ret); } +/** + * e_utf8_strftime_fix_am_pm: + * + * Stolen from Evolution codebase. Selects the + * correct time format. + * + * Returns: the size of the string + */ gsize e_utf8_strftime_fix_am_pm (gchar *str, gsize max, @@ -748,9 +893,12 @@ fix_popover_menu_icons (GtkPopover *popover) /** * uri_get_fields: + * @uri: the URI + * @schema: (nullable): return location for the schema of the URI + * @host: (nullable): return location for the host of the URI + * @path: (nullable): return location for the resource path * - * Split the given URI into the - * fields. + * Split the given URI into the fields. * * Returns: #TRUE if @uri could be parsed, #FALSE otherwise */ @@ -809,6 +957,16 @@ uri_get_fields (const gchar *uri, return valid; } +/** + * get_source_parent_name_color: + * @manager: a #GcalManager + * @source: an #ESource + * @name: (nullable): return location for the name + * @color: (nullable): return location for the color + * + * Retrieves the name and the color of the #ESource that is + * parent of @source. + */ void get_source_parent_name_color (GcalManager *manager, ESource *source, @@ -834,6 +992,16 @@ get_source_parent_name_color (GcalManager *manager, } } +/** + * format_utc_offset: + * @offset: an UTC offset + * + * Formats the UTC offset to a string that GTimeZone can + * parse. E.g. "-0300" or "+0530". + * + * Returns: (transfer full): a string representing the + * offset + */ gchar* format_utc_offset (gint64 offset) { @@ -859,6 +1027,17 @@ format_utc_offset (gint64 offset) return g_strdup_printf ("%s%02i%02i", sign, hours, minutes); } +/** + * get_alarm_trigger_minutes: + * @event: a #GcalEvent + * @alarm: a #ECalComponentAlarm + * + * Calculates the number of minutes before @event's + * start time that the alarm should be triggered. + * + * Returns: the number of minutes before the event + * start that @alarm will be triggered. + */ gint get_alarm_trigger_minutes (GcalEvent *event, ECalComponentAlarm *alarm) @@ -891,6 +1070,18 @@ get_alarm_trigger_minutes (GcalEvent *event, return diff; } +/** + * should_change_date_for_scroll: + * @scroll_value: the current scroll value + * @scroll_event: the #GdkEventScroll that is being parsed + * + * Utility function to check if the date should change based + * on the scroll. The date is changed when the user scrolls + * too much on touchpad, or performs a rotation of the scroll + * button in a mouse. + * + * Returns: %TRUE if the date should change, %FALSE otherwise. + */ gboolean should_change_date_for_scroll (gdouble *scroll_value, GdkEventScroll *scroll_event) @@ -925,6 +1116,15 @@ should_change_date_for_scroll (gdouble *scroll_value, return FALSE; } +/** + * is_source_enabled: + * @source: an #ESource + * + * Retrieves whether the @source is enabled or not. + * Disabled sources don't show their events. + * + * Returns: %TRUE if @source is enabled, %FALSE otherwise. + */ gboolean is_source_enabled (ESource *source) { diff --git a/src/gcal-utils.h b/src/gcal-utils.h index 2f65a8b6..90345ace 100644 --- a/src/gcal-utils.h +++ b/src/gcal-utils.h @@ -33,6 +33,17 @@ #define gcal_clear_datetime(dt) g_clear_pointer (dt, g_date_time_unref) +/** + * GcalWindowViewType: + * @GCAL_WINDOW_VIEW_DAY: Day view (not implemented) + * @GCAL_WINDOW_VIEW_WEEK: Week view + * @GCAL_WINDOW_VIEW_MONTH: Month view + * @GCAL_WINDOW_VIEW_YEAR: Year view + * @GCAL_WINDOW_VIEW_LIST: List (not implemented) + * @GCAL_WINDOW_VIEW_SEARCH: Search view (partially implemented) + * + * Enum with the available views. + */ typedef enum { GCAL_WINDOW_VIEW_DAY, @@ -43,19 +54,6 @@ typedef enum GCAL_WINDOW_VIEW_SEARCH, } GcalWindowViewType; -typedef enum -{ - EVENT_SUMMARY = 0, - EVENT_START_DATE, - EVENT_END_DATE, - EVENT_LOCATION, - EVENT_DESCRIPTION, - EVENT_SOURCE, -} EventEditableProperty; - -typedef -const gchar* (*GcalTranslateFunc) (GtkWidget *source_widget); - GType icaltime_get_type (void) G_GNUC_CONST; gint datetime_compare_date (GDateTime *dt1, diff --git a/src/gcal-window.c b/src/gcal-window.c index 066f742c..662d3d8e 100644 --- a/src/gcal-window.c +++ b/src/gcal-window.c @@ -39,6 +39,48 @@ #include <libecal/libecal.h> #include <libical/icaltime.h> +/** + * SECTION:gcal-window + * @short_description: Main window of GNOME Calendar + * @title:GcalWindow + * @stability:unstable + * @image:gcal-window.png + * + * #GcalWindow is the main window of GNOME Calendar, and contains + * the views, the source dialog, the edit dialog, and manages the + * calendar toggler popover menu. + * + * Besides that, #GcalWindow is also responsible for #GcalQuickAddPopover, + * and it responds to the #GcalView:create-event signal by positioning + * the quick add popover at the requested position. + * + * ## Calendar popover + * + *  + * + * The calendar popover enables/disables the selected calendars. + * This is simply an UI for gcal_manager_enable_source() and + * gcal_manager_disable_source(). + * + * The calendar popover also contains a button to open the source + * dialog. + * + * ## Edit dialog + * + * When an event is clicked, the views send the `event-activated` + * signal. #GcalWindow responds to this signal opening #GcalEditDialog + * with the clicked event. + * + * When #GcalEditDialog sends a response, #GcalWindow reacts by + * either propagating to gcal_manager_update_event(), or hiding + * the delete event widgets from the views. + * + * ## Source dialog + * + * The interaction with the source dialog is almost none. #GcalWindow + * just shows and hides it. + */ + typedef struct { gint x; @@ -1572,6 +1614,17 @@ gcal_window_init (GcalWindow *self) } /* Public API */ +/** + * gcal_window_new_with_view_and_date: + * @app: a #GcalApplication + * @view_type: a #GcalWindowViewType + * @date: the active date + * + * Creates a #GcalWindow, positions it at @date and shows + * @view_type view by default. + * + * Returns: (transfer full): a #GcalWindow + */ GtkWidget* gcal_window_new_with_view_and_date (GcalApplication *app, GcalWindowViewType view_type, @@ -1609,6 +1662,12 @@ gcal_window_new_with_view_and_date (GcalApplication *app, } /* new-event interaction: first variant */ +/** + * gcal_window_new_event: + * @self: a #GcalWindow + * + * Makes #GcalWindow create a new event. + */ void gcal_window_new_event (GcalWindow *self) { @@ -1640,6 +1699,15 @@ gcal_window_new_event (GcalWindow *self) create_event_detailed_cb (NULL, start_date, end_date, self); } +/** + * gcal_window_set_search_mode: + * @self: a #GcalWindow + * @enabled: whether the search mode is enabled or not + * + * Sets whether #GcalWindow is in search mode. This is used by + * #GcalShellSearchProvider to respond to the user clicking on + * GNOME Calendar icon at the search. + */ void gcal_window_set_search_mode (GcalWindow *self, gboolean enabled) @@ -1650,6 +1718,15 @@ gcal_window_set_search_mode (GcalWindow *self, gtk_search_bar_set_search_mode (GTK_SEARCH_BAR (self->search_bar), enabled); } +/** + * gcal_window_set_search_query: + * @self: a #GcalWindow + * @query: sets the search query of @self + * + * Sets the search query of the search. #GcalWindow only + * propagates this to the search bar, which ends up + * triggering the search. + */ void gcal_window_set_search_query (GcalWindow *self, const gchar *query) @@ -1659,6 +1736,14 @@ gcal_window_set_search_query (GcalWindow *self, gtk_entry_set_text (GTK_ENTRY (self->search_entry), query); } +/** + * gcal_window_open_event_by_uuid: + * @self: a #GcalWindow + * @uuid: the unique identifier of the event to be opened + * + * Tells @self to open the event with @uuid. When it fails to + * open the event, it waits for 2 seconds before trying again. + */ void gcal_window_open_event_by_uuid (GcalWindow *self, const gchar *uuid) diff --git a/src/views/gcal-range-tree.c b/src/views/gcal-range-tree.c index 7fb5b9c7..7bab24c5 100644 --- a/src/views/gcal-range-tree.c +++ b/src/views/gcal-range-tree.c @@ -20,6 +20,28 @@ #include "gcal-range-tree.h" +/** + * SECTION:gcal-range-tree + * @short_description: Augmented AVL tree to handle ranges + * @title:GcalRangeTree + * @stability:stable + * + * #GcalRangeTree is an augmented AVL tree implemented to be + * able to handle ranges rather than point values. This tree + * is used by @GcalWeekGrid to store events according to their + * start and end minutes, and thus all the data structure was + * optimized to handle a limited subset of values. + * + * In the future, we may need to extend support for broader + * range values, and move away from guint16 in function params. + * + * # Ranges + * + * Conforming to the overall standard of iCal and Calendar, + * the start of a range is inclusive but the end of the range + * is always exclusive. + */ + typedef struct _Node { struct _Node *left; @@ -587,6 +609,17 @@ gcal_range_tree_get_data_at_range (GcalRangeTree *self, return data; } +/** + * gcal_range_tree_count_entries_at_range: + * @self: a #GcalRangeTree + * @start: start of the range + * @end: end of the range + * + * Counts the number of entries available in the given + * range. + * + * Returns: the number of entries in the given range + */ guint64 gcal_range_tree_count_entries_at_range (GcalRangeTree *self, guint16 start, diff --git a/src/views/gcal-range-tree.h b/src/views/gcal-range-tree.h index 3f8b75d5..a9b2d473 100644 --- a/src/views/gcal-range-tree.h +++ b/src/views/gcal-range-tree.h @@ -27,6 +27,17 @@ G_BEGIN_DECLS typedef struct _GcalRangeTree GcalRangeTree; +/** + * GcalRangeTraverseFunc: + * @start: start of range of the entry + * @end: end of range of the entry + * @data: (nullable): the data of the entry + * @user_data: (closure): user data passed to the function + * + * Function type to be called when traversing a #GcalRangeTree. + * + * Returns: %TRUE to stop traversing, %FALSE to continue traversing + */ typedef gboolean (*GcalRangeTraverseFunc) (guint16 start, guint16 end, gpointer data, |
