[gnome-calendar/wip/gbsneto/docs: 2/2] wip: document classes
- From: Georges Basile Stavracas Neto <gbsneto src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-calendar/wip/gbsneto/docs: 2/2] wip: document classes
- Date: Tue, 28 Mar 2017 14:47:51 +0000 (UTC)
commit 61b232ab308d4312967b2f1bf6756fb6b9c69211
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 | 7 +-
doc/reference/gnome-calendar-decl-list.txt | 4 -
doc/reference/gnome-calendar-decl.txt | 26 --
doc/reference/gnome-calendar-undeclared.txt | 2 +
doc/reference/gnome-calendar-undocumented.txt | 100 ++-------
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-event.c | 58 +++++-
src/gcal-event.h | 6 +
src/gcal-manager.c | 308 +++++++++++++++++++++----
src/gcal-utils.c | 232 +++++++++++++++++--
src/gcal-utils.h | 18 +-
src/gcal-window.c | 85 +++++++
src/views/gcal-range-tree.c | 33 +++
src/views/gcal-range-tree.h | 11 +
21 files changed, 858 insertions(+), 219 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 2e72e5c..389752c 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..4f68cb4 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,11 @@ CFILE_GLOB = \
IGNORE_HFILES = $(NULL)
# Images to copy into HTML directory.
-HTML_IMAGES = $(NULL)
+HTML_IMAGES = \
+ images/gcal-event-widget.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..b7bb8f5 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
diff --git a/doc/reference/gnome-calendar-decl.txt b/doc/reference/gnome-calendar-decl.txt
index 1f79541..66167a6 100644
--- a/doc/reference/gnome-calendar-decl.txt
+++ b/doc/reference/gnome-calendar-decl.txt
@@ -1023,15 +1023,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 +1060,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..79a0ab7 100644
--- a/doc/reference/gnome-calendar-undeclared.txt
+++ b/doc/reference/gnome-calendar-undeclared.txt
@@ -0,0 +1,2 @@
+EventEditableProperty
+GcalTranslateFunc
diff --git a/doc/reference/gnome-calendar-undocumented.txt b/doc/reference/gnome-calendar-undocumented.txt
index a222a9d..bcefc4c 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.
+59% symbol docs coverage.
+329 symbols documented.
+133 symbols incomplete.
+231 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,7 +65,6 @@ GcalMultiChoice
GcalMultiChoice::wrapped
GcalMultiChoiceFormatCallback (<parameters>)
GcalQuickAddPopover
-GcalRangeTraverseFunc (<parameters>)
GcalSearchView
GcalShellSearchProvider
GcalShellSearchProviderClass (<items>)
@@ -83,7 +73,7 @@ GcalSourceDialogMode (<items>)
GcalSubscriberView::event-activated
GcalSubscriberViewPrivate (<items>)
GcalTimeSelector
-GcalTranslateFunc (<parameters>)
+GcalTranslateFunc
GcalView
GcalViewInterface (<items>)
GcalWeekGrid
@@ -99,6 +89,7 @@ GcalYearView::event-activated
ICAL_TIME_TYPE
MAX_MINUTES
MINUTES_PER_DAY
+_GCAL_BUG
action_widget_activated (Returns)
back_button_clicked (Returns)
build_component_from_details (summary, initial_date, final_date)
@@ -106,16 +97,12 @@ 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 (fmt, tm, str, max)
+e_utf8_strftime_fix_am_pm (fmt, tm, str, max)
fix_popover_menu_icons (popover)
-format_utc_offset (<parameters>)
free_row_data (Returns)
gcal_application_get_manager (<parameters>)
gcal_application_get_settings (<parameters>)
@@ -143,7 +130,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>)
@@ -163,36 +149,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_manager_get_events (range_start, range_end)
+gcal_manager_get_goa_client (manager)
+gcal_manager_get_shell_search_events (manager)
+gcal_manager_query_client_data (source, field, 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_get_final_date
gcal_month_view_motion_notify_event (widget, event, Returns)
gcal_month_view_set_first_weekday (self)
@@ -204,7 +172,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
@@ -243,29 +210,12 @@ 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)
@@ -276,10 +226,8 @@ 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)
@@ -297,28 +245,20 @@ 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
@@ -345,7 +285,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-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-utils.c b/src/gcal-utils.c
index 5a9dfb3..4287c25 100644
--- a/src/gcal-utils.c
+++ b/src/gcal-utils.c
@@ -69,6 +69,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 +102,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 +133,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 +162,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 +181,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 +212,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 +241,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 +273,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 +305,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 +325,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 +470,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 +542,15 @@ build_component_from_details (const gchar *summary,
/**
* icaltime_compare_date:
- * @date1:
- * @date2:
+ * @date1: an #icaltimetype
+ * @date2: an #icaltimetype
*
- * 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.
+ * Compare date parts of #icaltimetype objects. Returns 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.
*
* Returns: negative, 0 or positive
**/
@@ -484,6 +570,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 +615,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 +650,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 +674,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 +697,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 +716,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 +758,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 +887,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 +951,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 +986,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 +1021,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 +1064,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 +1110,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..5bfbc92 100644
--- a/src/gcal-utils.h
+++ b/src/gcal-utils.h
@@ -33,6 +33,11 @@
#define gcal_clear_datetime(dt) g_clear_pointer (dt, g_date_time_unref)
+/**
+ * GcalWindowViewType:
+ *
+ * Enum with the available views.
+ */
typedef enum
{
GCAL_WINDOW_VIEW_DAY,
@@ -43,19 +48,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]
