[gnome-calendar/wip/gbsneto/docs: 9/9] wip: document classes
- From: Georges Basile Stavracas Neto <gbsneto src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-calendar/wip/gbsneto/docs: 9/9] wip: document classes
- Date: Tue, 11 Apr 2017 12:12:47 +0000 (UTC)
commit 0a34dc8ef2ed4a46421dba1ab7246d3cc9ed5376
Author: Georges Basile Stavracas Neto <georges stavracas gmail com>
Date: Mon Mar 20 17:55:09 2017 -0300
wip: document classes
.gitignore | 2 +-
doc/reference/Makefile.am | 9 +-
doc/reference/gnome-calendar-decl-list.txt | 6 -
doc/reference/gnome-calendar-decl.txt | 40 ----
doc/reference/gnome-calendar-undeclared.txt | 4 +
doc/reference/gnome-calendar-undocumented.txt | 136 ++---------
doc/reference/gnome-calendar-unused.txt | 8 +
doc/reference/gnome-calendar.hierarchy | 43 ++--
doc/reference/gnome-calendar.types | 1 -
doc/reference/images/gcal-event-widget.png | Bin 0 -> 3782 bytes
doc/reference/images/gcal-window.png | Bin 0 -> 35329 bytes
doc/reference/images/gcal-window_agendas.png | Bin 0 -> 33195 bytes
src/gcal-debug.h.in | 133 +++++++++++
src/gcal-edit-dialog.c | 74 ++++++
src/gcal-event.c | 58 +++++-
src/gcal-event.h | 6 +
src/gcal-manager.c | 308 +++++++++++++++++++++----
src/gcal-source-dialog.c | 308 ++++++++-----------------
src/gcal-source-dialog.h | 9 +
src/gcal-utils.c | 238 ++++++++++++++++++--
src/gcal-utils.h | 24 +-
src/gcal-window.c | 85 +++++++
src/views/gcal-range-tree.c | 33 +++
src/views/gcal-range-tree.h | 11 +
24 files changed, 1050 insertions(+), 486 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 01c53e2..62bc73a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -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 a1e6351..7437317 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 d9c201e..bdf4514 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 1f79541..17db120 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 e69de29..2b4034e 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 a222a9d..e6ad0f5 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 8b2221e..b3ac489 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 7e24ac9..bc548ab 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 833da84..954780f 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
new file mode 100644
index 0000000..431ed87
Binary files /dev/null and b/doc/reference/images/gcal-event-widget.png differ
diff --git a/doc/reference/images/gcal-window.png b/doc/reference/images/gcal-window.png
new file mode 100644
index 0000000..d7d2c53
Binary files /dev/null and b/doc/reference/images/gcal-window.png differ
diff --git a/doc/reference/images/gcal-window_agendas.png b/doc/reference/images/gcal-window_agendas.png
new file mode 100644
index 0000000..b7a3bb0
Binary files /dev/null and b/doc/reference/images/gcal-window_agendas.png differ
diff --git a/src/gcal-debug.h.in b/src/gcal-debug.h.in
index bc2d1eb..199624c 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 59fc74a..f54ebf1 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 a9d0a7d..907bb96 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 ce21b22..3fe6d96 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 f63235b..91587b1 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 42759e5..dfd30a4 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 4daf640..11aec38 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 5a9dfb3..d0646b1 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 2f65a8b..90345ac 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 066f742..662d3d8 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 7fb5b9c..7bab24c 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 3f8b75d..a9b2d47 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,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
