From 86ec303a21211ab79c4e7a0c160e59b5605bfe15 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Mon, 17 Jul 2000 23:57:22 +0000 Subject: Docs docs docs - Federico svn path=/trunk/; revision=4206 --- calendar/ChangeLog | 1 + calendar/cal-client/cal-client.c | 10 ++ doc/devel/ChangeLog | 2 + doc/devel/calendar/cal-client/tmpl/cal-client.sgml | 148 +++++++++++++++------ help/devel/ChangeLog | 2 + .../devel/calendar/cal-client/tmpl/cal-client.sgml | 148 +++++++++++++++------ 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 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 + * calendar/cal-client/tmpl/cal-client.sgml: Populated. + * evolution-devel-guide.sgml: New 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 - +GTK+ object for communication with personal calendar server. - - - - + + 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. + + + + 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 cal_loaded signal. + + + + 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 obj_updated and obj_removed signals on the + CalClient objects they create so that they can be notified about + changes in the storage. + - + - + - + + Casts a #GtkObject to a #CalClient. + - - -@obj: +@obj: A GTK+ object. - - - - -@CAL_CLIENT_LOAD_SUCCESS: -@CAL_CLIENT_LOAD_ERROR: -@CAL_CLIENT_LOAD_IN_USE: -@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED: + + 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. + + +@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. - + + These values describe the result of the cal_client_get_object() + function. + - +@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. @@ -180,26 +224,46 @@ CalClient - - - - -@calclient: the object which received the signal. -@arg1: + + 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. + + +@client: Calendar client which received the notification. +@status: Status of the request. See the description of + #CalClientLoadStatus for more details. - + + 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. + - - -@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. - - - - -@calclient: the object which received the signal. -@arg1: - + + 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. + + +@client: Calendar client which received the notification. +@uid: Unique identifier of the calendar component that was removed + from the personal calendar server's storage. + + 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 + * calendar/cal-client/tmpl/cal-client.sgml: Populated. + * evolution-devel-guide.sgml: New 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 - +GTK+ object for communication with personal calendar server. - - - - + + 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. + + + + 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 cal_loaded signal. + + + + 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 obj_updated and obj_removed signals on the + CalClient objects they create so that they can be notified about + changes in the storage. + - + - + - + + Casts a #GtkObject to a #CalClient. + - - -@obj: +@obj: A GTK+ object. - - - - -@CAL_CLIENT_LOAD_SUCCESS: -@CAL_CLIENT_LOAD_ERROR: -@CAL_CLIENT_LOAD_IN_USE: -@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED: + + 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. + + +@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. - + + These values describe the result of the cal_client_get_object() + function. + - +@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. @@ -180,26 +224,46 @@ CalClient - - - - -@calclient: the object which received the signal. -@arg1: + + 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. + + +@client: Calendar client which received the notification. +@status: Status of the request. See the description of + #CalClientLoadStatus for more details. - + + 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. + - - -@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. - - - - -@calclient: the object which received the signal. -@arg1: - + + 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. + + +@client: Calendar client which received the notification. +@uid: Unique identifier of the calendar component that was removed + from the personal calendar server's storage. + + -- cgit v1.2.3