aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--calendar/ChangeLog1
-rw-r--r--calendar/cal-client/cal-client.c10
-rw-r--r--doc/devel/ChangeLog2
-rw-r--r--doc/devel/calendar/cal-client/tmpl/cal-client.sgml148
-rw-r--r--help/devel/ChangeLog2
-rw-r--r--help/devel/calendar/cal-client/tmpl/cal-client.sgml148
6 files changed, 227 insertions, 84 deletions
diff --git a/calendar/ChangeLog b/calendar/ChangeLog
index 8934fb9fa0..b7a7dcea40 100644
--- a/calendar/ChangeLog
+++ b/calendar/ChangeLog
@@ -3,6 +3,7 @@
* cal-client/cal-client.c (cal_client_get_object): Fixed inline
docs.
(cal_client_new): Ditto.
+ (cal_client_get_n_objects): Added inline docs.
2000-07-14 Federico Mena Quintero <federico@helixcode.com>
diff --git a/calendar/cal-client/cal-client.c b/calendar/cal-client/cal-client.c
index 90b4dcdbed..1e0a0561d5 100644
--- a/calendar/cal-client/cal-client.c
+++ b/calendar/cal-client/cal-client.c
@@ -550,6 +550,16 @@ cal_client_create_calendar (CalClient *client, const char *str_uri)
return load_or_create (client, str_uri, FALSE);
}
+/**
+ * cal_client_get_n_objects:
+ * @client: A calendar client.
+ * @type: Type of objects that will be counted.
+ *
+ * Counts the number of calendar components of the specified @type. This can be
+ * used to count how many events, to-dos, or journals there are, for example.
+ *
+ * Return value: Number of components.
+ **/
int
cal_client_get_n_objects (CalClient *client, CalObjType type)
{
diff --git a/doc/devel/ChangeLog b/doc/devel/ChangeLog
index b273c5c657..c13966da75 100644
--- a/doc/devel/ChangeLog
+++ b/doc/devel/ChangeLog
@@ -1,5 +1,7 @@
2000-07-17 Federico Mena Quintero <federico@helixcode.com>
+ * calendar/cal-client/tmpl/cal-client.sgml: Populated.
+
* evolution-devel-guide.sgml: New <book> toplevel for the
Evolution Developer's Guide.
diff --git a/doc/devel/calendar/cal-client/tmpl/cal-client.sgml b/doc/devel/calendar/cal-client/tmpl/cal-client.sgml
index 7fdc69bfdc..d2205b5b22 100644
--- a/doc/devel/calendar/cal-client/tmpl/cal-client.sgml
+++ b/doc/devel/calendar/cal-client/tmpl/cal-client.sgml
@@ -2,46 +2,90 @@
CalClient
<!-- ##### SECTION Short_Description ##### -->
-
+GTK+ object for communication with personal calendar server.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
+ <para>
+ The #CalClient object provides a nice GTK+ wrapper for the CORBA
+ interfaces that are used to communicate between calendar clients
+ and the personal calendar server in the user's Wombat daemon.
+ </para>
+
+ <para>
+ After a #CalClient object is created with cal_client_new(), it
+ should be asked to send a request to the personal calendar server
+ to load or create a calendar based on its URI. The server will
+ asynchronously notify the client about completion of the request,
+ and will return an appropriate result code; this should be noted
+ by the client with the <link
+ linkend="CalClient--cal-loaded">cal_loaded</link> signal.
+ </para>
+
+ <para>
+ When a client asks the server to update or delete a calendar
+ component from the storage, the server will do so and then notify
+ all the clients about the update or removal. This is the core of
+ the model/view split between calendar clients and the storage in
+ the personal calendar server. Clients should watch the <link
+ linkend="calclient-obj-updated">obj_updated</link> and <link
+ linkend="calclient-obj-removed">obj_removed</link> signals on the
+ CalClient objects they create so that they can be notified about
+ changes in the storage.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
+ <para>
-</para>
+ </para>
<!-- ##### MACRO CAL_CLIENT ##### -->
-<para>
+ <para>
+ Casts a #GtkObject to a #CalClient.
+ </para>
-</para>
-
-@obj:
+@obj: A GTK+ object.
<!-- ##### ENUM CalClientLoadStatus ##### -->
-<para>
-
-</para>
-
-@CAL_CLIENT_LOAD_SUCCESS:
-@CAL_CLIENT_LOAD_ERROR:
-@CAL_CLIENT_LOAD_IN_USE:
-@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED:
+ <para>
+ These values describe the status of a calendar load or create
+ request. After asking a calendar factory to load or create a
+ calendar, the provided listener will get notification about the
+ result in asynchronous fashion. Such notification is represented
+ by one of these enumeration values. For values other than
+ #CAL_CLIENT_LOAD_SUCCESS, the #CalClient object will not accept
+ any other operations on the calendar and it should just be
+ destroyed.
+ </para>
+
+@CAL_CLIENT_LOAD_SUCCESS: Indicates a successful load or create
+ operation; the corresponding calendar is ready for use.
+
+@CAL_CLIENT_LOAD_ERROR: Indicates an error while loading or creating
+ the calendar.
+
+@CAL_CLIENT_LOAD_IN_USE: Indicates that a create request failed
+ because the specified calendar was already being used by another
+ client.
+
+@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED: Indicates an error due to
+ trying to load a calendar for which a backend type is not present.
<!-- ##### ENUM CalClientGetStatus ##### -->
-<para>
+ <para>
+ These values describe the result of the cal_client_get_object()
+ function.
+ </para>
-</para>
+@CAL_CLIENT_GET_SUCCESS: Indicates a successful get operation.
+
+@CAL_CLIENT_GET_NOT_FOUND: Indicates that the requested object was
+ not found.
-@CAL_CLIENT_GET_SUCCESS:
-@CAL_CLIENT_GET_NOT_FOUND:
-@CAL_CLIENT_GET_SYNTAX_ERROR:
+@CAL_CLIENT_GET_SYNTAX_ERROR: Indicates a syntax error when parsing
+ the requested object. This could indicate a bug in the calendar
+ client libraries or in the Wombat server.
<!-- ##### FUNCTION cal_client_new ##### -->
<para>
@@ -180,26 +224,46 @@ CalClient
<!-- ##### SIGNAL CalClient::cal-loaded ##### -->
-<para>
-
-</para>
-
-@calclient: the object which received the signal.
-@arg1:
+ <para>
+ This signal is emitted some time after the calendar clients sends
+ a load or create request to the personal calendar server. The
+ server will notify the client asynchronously of the completion of
+ the request. The @status parameter indicates the status of the
+ request.
+ </para>
+
+@client: Calendar client which received the notification.
+@status: Status of the request. See the description of
+ #CalClientLoadStatus for more details.
<!-- ##### SIGNAL CalClient::obj-updated ##### -->
-<para>
+ <para>
+ This signal is emitted when the calendar clients receives
+ notification of a calendar component's data being changed in the
+ personal calendar server. Graphical clients may want to get the
+ new version of the object and update their display, for example.
+ </para>
-</para>
-
-@calclient: the object which received the signal.
-@arg1:
+@client: Calendar client which received the notification.
+@uid: Unique identifier of the calendar component that changed in the
+ personal calendar server's storage.
<!-- ##### SIGNAL CalClient::obj-removed ##### -->
-<para>
-
-</para>
-
-@calclient: the object which received the signal.
-@arg1:
-
+ <para>
+ This signal is emitted when the calendar client receives
+ notification for a calendar component being removed from the
+ storage in the personal calendar server. Graphical clients may
+ want to delete the corresponding object from their display, for
+ example.
+ </para>
+
+@client: Calendar client which received the notification.
+@uid: Unique identifier of the calendar component that was removed
+ from the personal calendar server's storage.
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../../../evolution-devel-guide.sgml" "book" "refsect2" "")
+End:
+-->
diff --git a/help/devel/ChangeLog b/help/devel/ChangeLog
index b273c5c657..c13966da75 100644
--- a/help/devel/ChangeLog
+++ b/help/devel/ChangeLog
@@ -1,5 +1,7 @@
2000-07-17 Federico Mena Quintero <federico@helixcode.com>
+ * calendar/cal-client/tmpl/cal-client.sgml: Populated.
+
* evolution-devel-guide.sgml: New <book> toplevel for the
Evolution Developer's Guide.
diff --git a/help/devel/calendar/cal-client/tmpl/cal-client.sgml b/help/devel/calendar/cal-client/tmpl/cal-client.sgml
index 7fdc69bfdc..d2205b5b22 100644
--- a/help/devel/calendar/cal-client/tmpl/cal-client.sgml
+++ b/help/devel/calendar/cal-client/tmpl/cal-client.sgml
@@ -2,46 +2,90 @@
CalClient
<!-- ##### SECTION Short_Description ##### -->
-
+GTK+ object for communication with personal calendar server.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
+ <para>
+ The #CalClient object provides a nice GTK+ wrapper for the CORBA
+ interfaces that are used to communicate between calendar clients
+ and the personal calendar server in the user's Wombat daemon.
+ </para>
+
+ <para>
+ After a #CalClient object is created with cal_client_new(), it
+ should be asked to send a request to the personal calendar server
+ to load or create a calendar based on its URI. The server will
+ asynchronously notify the client about completion of the request,
+ and will return an appropriate result code; this should be noted
+ by the client with the <link
+ linkend="CalClient--cal-loaded">cal_loaded</link> signal.
+ </para>
+
+ <para>
+ When a client asks the server to update or delete a calendar
+ component from the storage, the server will do so and then notify
+ all the clients about the update or removal. This is the core of
+ the model/view split between calendar clients and the storage in
+ the personal calendar server. Clients should watch the <link
+ linkend="calclient-obj-updated">obj_updated</link> and <link
+ linkend="calclient-obj-removed">obj_removed</link> signals on the
+ CalClient objects they create so that they can be notified about
+ changes in the storage.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
+ <para>
-</para>
+ </para>
<!-- ##### MACRO CAL_CLIENT ##### -->
-<para>
+ <para>
+ Casts a #GtkObject to a #CalClient.
+ </para>
-</para>
-
-@obj:
+@obj: A GTK+ object.
<!-- ##### ENUM CalClientLoadStatus ##### -->
-<para>
-
-</para>
-
-@CAL_CLIENT_LOAD_SUCCESS:
-@CAL_CLIENT_LOAD_ERROR:
-@CAL_CLIENT_LOAD_IN_USE:
-@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED:
+ <para>
+ These values describe the status of a calendar load or create
+ request. After asking a calendar factory to load or create a
+ calendar, the provided listener will get notification about the
+ result in asynchronous fashion. Such notification is represented
+ by one of these enumeration values. For values other than
+ #CAL_CLIENT_LOAD_SUCCESS, the #CalClient object will not accept
+ any other operations on the calendar and it should just be
+ destroyed.
+ </para>
+
+@CAL_CLIENT_LOAD_SUCCESS: Indicates a successful load or create
+ operation; the corresponding calendar is ready for use.
+
+@CAL_CLIENT_LOAD_ERROR: Indicates an error while loading or creating
+ the calendar.
+
+@CAL_CLIENT_LOAD_IN_USE: Indicates that a create request failed
+ because the specified calendar was already being used by another
+ client.
+
+@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED: Indicates an error due to
+ trying to load a calendar for which a backend type is not present.
<!-- ##### ENUM CalClientGetStatus ##### -->
-<para>
+ <para>
+ These values describe the result of the cal_client_get_object()
+ function.
+ </para>
-</para>
+@CAL_CLIENT_GET_SUCCESS: Indicates a successful get operation.
+
+@CAL_CLIENT_GET_NOT_FOUND: Indicates that the requested object was
+ not found.
-@CAL_CLIENT_GET_SUCCESS:
-@CAL_CLIENT_GET_NOT_FOUND:
-@CAL_CLIENT_GET_SYNTAX_ERROR:
+@CAL_CLIENT_GET_SYNTAX_ERROR: Indicates a syntax error when parsing
+ the requested object. This could indicate a bug in the calendar
+ client libraries or in the Wombat server.
<!-- ##### FUNCTION cal_client_new ##### -->
<para>
@@ -180,26 +224,46 @@ CalClient
<!-- ##### SIGNAL CalClient::cal-loaded ##### -->
-<para>
-
-</para>
-
-@calclient: the object which received the signal.
-@arg1:
+ <para>
+ This signal is emitted some time after the calendar clients sends
+ a load or create request to the personal calendar server. The
+ server will notify the client asynchronously of the completion of
+ the request. The @status parameter indicates the status of the
+ request.
+ </para>
+
+@client: Calendar client which received the notification.
+@status: Status of the request. See the description of
+ #CalClientLoadStatus for more details.
<!-- ##### SIGNAL CalClient::obj-updated ##### -->
-<para>
+ <para>
+ This signal is emitted when the calendar clients receives
+ notification of a calendar component's data being changed in the
+ personal calendar server. Graphical clients may want to get the
+ new version of the object and update their display, for example.
+ </para>
-</para>
-
-@calclient: the object which received the signal.
-@arg1:
+@client: Calendar client which received the notification.
+@uid: Unique identifier of the calendar component that changed in the
+ personal calendar server's storage.
<!-- ##### SIGNAL CalClient::obj-removed ##### -->
-<para>
-
-</para>
-
-@calclient: the object which received the signal.
-@arg1:
-
+ <para>
+ This signal is emitted when the calendar client receives
+ notification for a calendar component being removed from the
+ storage in the personal calendar server. Graphical clients may
+ want to delete the corresponding object from their display, for
+ example.
+ </para>
+
+@client: Calendar client which received the notification.
+@uid: Unique identifier of the calendar component that was removed
+ from the personal calendar server's storage.
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../../../evolution-devel-guide.sgml" "book" "refsect2" "")
+End:
+-->
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-03 22:32:12 +0800