diff options
Diffstat (limited to 'doc/devel')
| -rw-r--r-- | doc/devel/ChangeLog | 2 | ||||
| -rw-r--r-- | doc/devel/calendar/cal-client/tmpl/cal-client.sgml | 148 |
2 files changed, 108 insertions, 42 deletions
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: +--> |