Changeset 3151

Show
Ignore:
Timestamp:
12/18/07 22:53:03
Author:
pvanhoof
Message:

2007-12-18 Philip Van Hoof <pvanhoof@gnome.org>

        • This was a major API change
Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/ChangeLog

    r3150 r3151  
     12007-12-18  Philip Van Hoof <pvanhoof@gnome.org> 
     2 
     3        * New documentation style, second commit (GtkDocFuture) 
     4        * API fixes in TnyMimePart and TnyGtkImageMimePartView 
     5        * Fixes for the unit tests and functional tests 
     6 
     7        * This was a major API change 
     8 
    192007-12-17  Philip Van Hoof <pvanhoof@gnome.org> 
    210 

  • trunk/docs/devel/reference/libtinymail-docs.sgml

    r2572 r3151  
    3737<!ENTITY libtinymail-TnyShared SYSTEM "xml/tny-shared.xml"> 
    3838<!ENTITY libtinymail-TnyCombinedAccount SYSTEM "xml/tny-combined-account.xml"> 
     39<!ENTITY libtinymail-TnyConnectionPolicy "xml/tny-connection-policy.xml"> 
    3940 
    4041<!ENTITY libtinymail-camel-TnyCamelSendQueue SYSTEM "xml/tny-camel-send-queue.xml"> 
    …… 
    5556<!ENTITY libtinymail-camel-TnyCamelMimePart SYSTEM "xml/tny-camel-mime-part.xml"> 
    5657<!ENTITY libtinymail-camel-TnyCamelMsg SYSTEM "xml/tny-camel-msg.xml"> 
     58<!ENTITY libtinymail-camel-TnyCamelBsMsg SYSTEM "xml/tny-camel-bs-msg.xml"> 
     59<!ENTITY libtinymail-camel-TnyCamelBsMsgReceiveStrategy SYSTEM "xml/tny-camel-bs-msg-receive-strategy.xml"> 
     60<!ENTITY libtinymail-camel-TnyCamelBsMimePart SYSTEM "xml/tny-camel-bs-mime-part.xml"> 
     61<!ENTITY libtinymail-camel-TnyCamelRecoverConnectionPolicy SYSTEM "xml/tny-camel-recover-connection-policy.xml"> 
     62<!ENTITY libtinymail-camel-TnyCamelDefaultConnectionPolicy SYSTEM "xml/tny-camel-default-connection-policy.xml"> 
    5763<!ENTITY libtinymail-camel-TnySessionCamel SYSTEM "xml/tny-session-camel.xml"> 
    5864<!ENTITY libtinymail-camel-TnyStreamCamel SYSTEM "xml/tny-stream-camel.xml"> 
    …… 
    7581<!ENTITY libtinymailui-gtk-TnyGtkLockable SYSTEM "xml/tny-gtk-lockable.xml"> 
    7682<!ENTITY libtinymailui-gtk-TnyGtkPasswordDialog SYSTEM "xml/tny-gtk-password-dialog.xml"> 
     83<!ENTITY libtinymailui-gtk-TnyGtkExpanderMimePartView SYSTEM "xml/tny-gtk-expander-mime-part-view.xml"> 
     84<!ENTITY libtinymailui-gtk-TnyGtkPixbufStream SYSTEM "xml/tny-gtk-pixbuf-stream.xml"> 
     85<!ENTITY libtinymailui-gtk-TnyGtkImageMimePartView SYSTEM "xml/tny-gtk-image-mime-part-view.xml"> 
    7786 
    7887<!ENTITY libtinymailui-TnyMimePartSaver SYSTEM "xml/tny-mime-part-saver.xml"> 
    …… 
    163172                &libtinymail-TnyFolderStoreChange; 
    164173                &libtinymail-TnyPasswordGetter; 
     174                &libtinymail-TnyConnectionPolicy; 
    165175                &libtinymail-TnyEnums; 
    166176                &libtinymail-TnyShared; 
    …… 
    197207                &libtinymailui-gtk-TnyGtkLockable; 
    198208                &libtinymailui-gtk-TnyGtkPasswordDialog; 
     209                &libtinymailui-gtk-TnyGtkExpanderMimePartView; 
     210                &libtinymailui-gtk-TnyGtkPixbufStream; 
     211                &libtinymailui-gtk-TnyGtkImageMimePartView; 
    199212                &libtinymailui-gtk-TnyGtkEnums; 
    200213        </chapter> 
    …… 
    252265                &libtinymail-camel-TnyCamelMimePart; 
    253266                &libtinymail-camel-TnyCamelMsg; 
     267                &libtinymail-camel-TnyCamelDefaultConnectionPolicy; 
     268                &libtinymail-camel-TnyCamelRecoverConnectionPolicy; 
     269                &libtinymail-camel-TnyCamelBsMimePart; 
     270                &libtinymail-camel-TnyCamelBsMsgReceiveStrategy; 
     271                &libtinymail-camel-TnyCamelBsMsg; 
    254272                &libtinymail-camel-TnySessionCamel; 
    255273                &libtinymail-camel-TnyStreamCamel; 

  • trunk/docs/devel/reference/tmpl/tny-account-store.sgml

    r3143 r3151  
    4949 
    5050</para> 
     51 
     52@: 
    5153 
    5254@tnyaccountstore: the object which received the signal. 

  • trunk/docs/devel/reference/tmpl/tny-account.sgml

    r3150 r3151  
    2828 
    2929</para> 
    30  
    31 @: 
    3230 
    3331@tnyaccount: the object which received the signal. 

  • trunk/docs/devel/reference/tmpl/tny-device.sgml

    r3143 r3151  
    3636 
    3737</para> 
     38 
     39@:  
     40@: 
    3841 
    3942@tnydevice: the object which received the signal. 

  • trunk/docs/devel/reference/tmpl/tny-send-queue.sgml

    r3143 r3151  
    4040</para> 
    4141 
    42 @:  
    43 @:  
    44 @:  
    45 @: 
    46  
    4742@tnysendqueue: the object which received the signal. 
    4843@arg1:  
    …… 
    5449 
    5550</para> 
    56  
    57 @:  
    58 @:  
    59 @:  
    60 @:  
    61 @: 
    6251 
    6352@tnysendqueue: the object which received the signal. 
    …… 
    7160 
    7261</para> 
    73  
    74 @:  
    75 @:  
    76 @:  
    77 @:  
    78 @: 
    7962 
    8063@tnysendqueue: the object which received the signal. 

  • trunk/docs/devel/reference/tmpl/tny-shared.sgml

    r3143 r3151  
    5454</para> 
    5555 
    56 @:  
     56@tnyaccountstore: the object which received the signal. 
    5757 
    5858<!-- ##### STRUCT TnyAccountStoreIface ##### --> 
    …… 
    259259</para> 
    260260 
    261 @tnyaccount: the object which received the signal. 
     261@:  
    262262 
    263263<!-- ##### SIGNAL TnyAccount::connection-status-changed ##### --> 
    …… 
    318318</para> 
    319319 
    320 @:  
    321 @:  
     320@tnydevice: the object which received the signal. 
     321@arg1:  
    322322 
    323323<!-- ##### STRUCT TnyDeviceIface ##### --> 
    …… 
    490490</para> 
    491491 
    492 @tnysendqueue: the object which received the signal. 
    493 @arg1:  
    494 @arg2:  
    495 @arg3:  
     492@:  
     493@:  
     494@:  
     495@:  
    496496 
    497497<!-- ##### SIGNAL TnySendQueue::msg-sending ##### --> 
    …… 
    500500</para> 
    501501 
    502 @tnysendqueue: the object which received the signal. 
    503 @arg1:  
    504 @arg2:  
    505 @arg3:  
    506 @arg4:  
     502@:  
     503@:  
     504@:  
     505@:  
     506@:  
    507507 
    508508<!-- ##### SIGNAL TnySendQueue::msg-sent ##### --> 
    …… 
    511511</para> 
    512512 
    513 @tnysendqueue: the object which received the signal. 
    514 @arg1:  
    515 @arg2:  
    516 @arg3:  
    517 @arg4:  
     513@:  
     514@:  
     515@:  
     516@:  
     517@:  
    518518 
    519519<!-- ##### STRUCT TnySendQueueIface ##### --> 
    …… 
    744744 
    745745@self:  
    746 @canceled:  
     746@cancelled:  
    747747@err:  
    748748@user_data:  
    …… 
    755755 
    756756@self:  
    757 @canceled:  
     757@cancelled:  
    758758@new_folder:  
    759759@err:  
    …… 
    767767 
    768768@self:  
     769@cancelled:  
    769770@stream:  
    770 @canceled:  
    771771@err:  
    772772@user_data:  
    …… 
    779779 
    780780@self:  
    781 @canceled:  
     781@cancelled:  
    782782@headers:  
    783783@err:  
    …… 
    792792 
    793793@folder: the #TnyFolder instance from which the message was requested 
    794 @canceled:  
     794@cancelled:  
    795795@msg: the #TnyMsg instance that was requested 
    796796@err: in case there was an error, this !GError instance is not NULL 
    …… 
    805805 
    806806@folder: the #TnyFolder instance from which the messages where transferred 
    807 @canceled:  
     807@cancelled:  
    808808@err: in case there was an error, this !GError instance is not NULL 
    809809@user_data: user data passed at the caller 
    …… 
    826826 
    827827@self: the #TnyFolderStore from which the child folders where requested 
    828 @canceled:  
     828@cancelled:  
    829829@list: a #TnyList with #TnyFolder instances (the requested children of @self) 
    830830@err: in case there was an error, this !GError instance is not NULL 
    …… 
    838838 
    839839@self:  
    840 @canceled:  
     840@cancelled:  
    841841@into:  
    842842@new_folder:  
    …… 
    851851 
    852852@self:  
    853 @canceled:  
     853@cancelled:  
    854854@msg:  
    855855@err:  

  • trunk/libtinymail-camel/tny-camel-bs-mime-part.c

    r3070 r3151  
    472472 
    473473        if (info->callback) {  
    474                 info->callback (TNY_MIME_PART (info->self), TNY_STREAM (info->stream),  
    475                         info->cancelled, info->err, info->user_data); 
     474                info->callback (TNY_MIME_PART (info->self),   
     475                        info->cancelled, TNY_STREAM (info->stream),  
     476                        info->err, info->user_data); 
    476477        } 
    477478 
    …… 
    510511        if (info->callback) {  
    511512                tny_lockable_lock (info->session->priv->ui_lock); 
    512                 info->callback (TNY_MIME_PART (info->self), TNY_STREAM (info->stream), TRUE, info->err, info->user_data); 
     513                info->callback (TNY_MIME_PART (info->self), TRUE, 
     514                        TNY_STREAM (info->stream), info->err,  
     515                        info->user_data); 
    513516                tny_lockable_unlock (info->session->priv->ui_lock); 
    514517        } 

  • trunk/libtinymail-camel/tny-camel-mime-part.c

    r3148 r3151  
    224224        if (info->callback) {  
    225225                /* TODO: tny_lockable_lock (priv->ui_locker); */ 
    226                 info->callback (TNY_MIME_PART (info->self), TNY_STREAM (info->stream),  
    227                         FALSE, info->err, info->user_data); 
     226                info->callback (TNY_MIME_PART (info->self),  
     227                        FALSE, TNY_STREAM (info->stream), info->err, info->user_data); 
    228228                /* TODO: tny_lockable_unlock (priv->ui_locker); */ 
    229229        } 

  • trunk/libtinymail-queues/tny-get-msg-queue.c

    r2825 r3151  
    9090 
    9191        if (info->callback && info->folder) 
    92                 info->callback (info->folder, FALSE, msg, &info->err, info->user_data); 
     92                info->callback (info->folder, FALSE, msg, info->err, info->user_data); 
    9393 
    9494        if (msg) 
    …… 
    242242 
    243243static void 
    244 refresh_done (TnyFolder *folder, gboolean cancelled, GError **err, gpointer user_data) 
     244refresh_done (TnyFolder *folder, gboolean cancelled, GError *err, gpointer user_data) 
    245245{ 
    246246        IntFolderMonitor *mon = user_data; 

  • trunk/libtinymail/tny-folder-store.c

    r3150 r3151  
    205205        return retval; 
    206206} 
     207 
     208 
     209 
     210/**  
     211 * TnyCreateFolderCallback: 
     212 * @self: a #TnyFolderStore that caused the callback 
     213 * @cancelled: if the operation got cancelled 
     214 * @new_folder (null-ok): a newly created #TnyFolder or NULL 
     215 * @err (null-ok): if an error occurred 
     216 * @user_data (null-ok):  user data that was passed to the callbacks 
     217 * 
     218 * A folder store callback for when a folder creation was requested. If allocated, 
     219 * you must cleanup @user_data at the end of your implementation of the callback. 
     220 * All other fields in the parameters of the callback are read-only. 
     221 * 
     222 * When cancelled, @cancelled will be TRUE while @err might nonetheless be NULL. 
     223 * If @err is not NULL, an error occurred that you should handle gracefully. 
     224 * The @new_folder folder parameter will only not be NULL if the creation of the 
     225 * folder in @self was considered successful. 
     226 * 
     227 * since: 1.0 
     228 * audience: application-developer 
     229 **/ 
    207230 
    208231/** 
    …… 
    289312        return; 
    290313} 
     314 
     315 
     316 
     317/**  
     318 * TnyGetFoldersCallback: 
     319 * @self: a #TnyFolderStore that caused the callback 
     320 * @cancelled: if the operation got cancelled 
     321 * @list (null-ok): a #TnyList with fetched #TnyFolder instances or NULL 
     322 * @err (null-ok): if an error occurred 
     323 * @user_data (null-ok):  user data that was passed to the callbacks 
     324 * 
     325 * A folder store callback for when a list of folders was requested. If allocated, 
     326 * you must cleanup @user_data at the end of your implementation of the callback. 
     327 * All other fields in the parameters of the callback are read-only. 
     328 * 
     329 * When cancelled, @cancelled will be TRUE while @err might nonetheless be NULL. 
     330 * If @err is not NULL, an error occurred that you should handle gracefully. 
     331 * The @list parameter might be NULL in case of cancellation or error. If not 
     332 * NULL it contains the list of folders in @self that got fetched during the 
     333 * request. 
     334 * 
     335 * since: 1.0 
     336 * audience: application-developer 
     337 **/ 
    291338 
    292339/** 

  • trunk/libtinymail/tny-folder.c

    r3150 r3151  
    4141#include <tny-folder.h> 
    4242guint tny_folder_signals [TNY_FOLDER_LAST_SIGNAL]; 
     43 
    4344 
    4445 
    …… 
    372373        return retval; 
    373374} 
     375 
     376 
     377/**  
     378 * TnyCopyFolderCallback: 
     379 * @self: a #TnyFolder that caused the callback 
     380 * @cancelled: if the operation got cancelled 
     381 * @into (null-ok): where @self got copied to 
     382 * @new_folder (null-ok): the new folder in @into 
     383 * @err (null-ok): if an error occurred 
     384 * @user_data (null-ok):  user data that was passed to the callbacks 
     385 * 
     386 * A folder callback for when a copy of a folder was requested. If allocated, 
     387 * you must cleanup @user_data at the end of your implementation of the callback. 
     388 * All other fields in the parameters of the callback are read-only. 
     389 * 
     390 * When cancelled, @cancelled will be TRUE while @err might nonetheless be NULL. 
     391 * If @err is not NULL, an error occurred that you should handle gracefully. 
     392 * The parameter @into is the #TnyFolderStore where you copied @self to. The 
     393 * parameter @new_folder is the folder instance in @into that got created by 
     394 * copying @self into it. 
     395 * 
     396 * Note that you should not use @self without care. It's possible that when you 
     397 * requested tny_folder_copy_async(), you specified to delete the original folder. 
     398 * Therefore will @self point to an instance that is about to be removed as an 
     399 * instance locally, and of which the remote folder has already been removed in 
     400 * case the copy was indeed successful and the requested included deleting the 
     401 * original. In such a case is @self as a folder not to be trusted any longer. 
     402 * In this case wont @self be NULL, but any operation that you'll do on it will 
     403 * yield unexpected and more importantly unspecified results. Please do not  
     404 * ignore this warning. 
     405 * 
     406 * since: 1.0 
     407 * audience: application-developer 
     408 **/ 
    374409 
    375410 
    …… 
    581616 
    582617 
     618/**  
     619 * TnyFolderCallback: 
     620 * @self: a #TnyFolder that caused the callback 
     621 * @cancelled: if the operation got cancelled 
     622 * @err (null-ok): if an error occurred 
     623 * @user_data (null-ok):  user data that was passed to the callbacks 
     624 * 
     625 * A generic folder callback. If allocated, you must cleanup @user_data at the 
     626 * end of your implementation of the callback. All other fields in the parameters 
     627 * of the callback are read-only. 
     628 * 
     629 * since: 1.0 
     630 * audience: application-developer 
     631 **/ 
     632 
    583633/** 
    584634 * tny_folder_add_msg_async: 
    …… 
    9941044} 
    9951045 
     1046/**  
     1047 * TnyTransferMsgsCallback: 
     1048 * @self: a #TnyFolder that caused the callback 
     1049 * @cancelled: if the operation got cancelled 
     1050 * @err (null-ok): if an error occurred 
     1051 * @user_data (null-ok):  user data that was passed to the callbacks 
     1052 * 
     1053 * A folder callback for when a transfer of messages was requested. If allocated, 
     1054 * you must cleanup @user_data at the end of your implementation of the callback. 
     1055 * All other fields in the parameters of the callback are read-only. 
     1056 * 
     1057 * When cancelled, @cancelled will be TRUE while @err might nonetheless be NULL. 
     1058 * If @err is not NULL, an error occurred that you should handle gracefully. 
     1059 * 
     1060 * since: 1.0 
     1061 * audience: application-developer 
     1062 **/ 
     1063 
    9961064/** 
    9971065 * tny_folder_transfer_msgs_async: 
    …… 
    11331201} 
    11341202 
     1203 
     1204/**  
     1205 * TnyGetMsgCallback: 
     1206 * @self: a #TnyFolder that caused the callback 
     1207 * @cancelled: if the operation got cancelled 
     1208 * @msg (null-ok): a #TnyMsg with the fetched message or NULL 
     1209 * @err (null-ok): if an error occurred 
     1210 * @user_data (null-ok):  user data that was passed to the callbacks 
     1211 * 
     1212 * A folder callback for when a message fetch was requested. If allocated, you 
     1213 * must cleanup @user_data at the end of your implementation of the callback. All  
     1214 * other fields in the parameters of the callback are read-only. 
     1215 * 
     1216 * When cancelled, @cancelled will be TRUE while @err might nonetheless be NULL. 
     1217 * If @err is not NULL, an error occurred that you should handle gracefully. 
     1218 * The @msg parameter might be NULL in case of error or cancellation. 
     1219 * 
     1220 * since: 1.0 
     1221 * audience: application-developer 
     1222 **/ 
    11351223 
    11361224/** 
    …… 
    12311319} 
    12321320 
     1321/**  
     1322 * TnyGetHeadersCallback: 
     1323 * @self: a #TnyFolder that caused the callback 
     1324 * @cancelled: if the operation got cancelled 
     1325 * @headers (null-ok): a #TnyList with fetched #TnyHeader instances or NULL 
     1326 * @err (null-ok): if an error occurred 
     1327 * @user_data (null-ok):  user data that was passed to the callbacks 
     1328 * 
     1329 * A folder callback for when headers where requested. If allocated, you must 
     1330 * cleanup @user_data at the end of your implementation of the callback. All 
     1331 * other fields in the parameters of the callback are read-only. 
     1332 * 
     1333 * When cancelled, @cancelled will be TRUE while @err might nonetheless be NULL. 
     1334 * If @err is not NULL, an error occurred that you should handle gracefully. 
     1335 * The @headers parameter might be NULL in case of error or cancellation. 
     1336 * 
     1337 * since: 1.0 
     1338 * audience: application-developer 
     1339 **/ 
    12331340 
    12341341/** 

  • trunk/libtinymail/tny-shared.h

    r3125 r3151  
    104104typedef struct _TnyConnectionPolicyIface TnyConnectionPolicyIface; 
    105105 
     106typedef void (*TnyStatusCallback) (GObject *self, TnyStatus *status, gpointer user_data); 
     107 
    106108typedef gchar* (*TnyGetPassFunc) (TnyAccount *self, const gchar *prompt, gboolean *cancel); 
    107109typedef void (*TnyForgetPassFunc) (TnyAccount *self); 
    108 typedef void (*TnyFolderCallback) (TnyFolder *self, gboolean canceled, GError *err, gpointer user_data); 
    109 typedef void (*TnyCreateFolderCallback) (TnyFolderStore *self, gboolean canceled, TnyFolder *new_folder, GError *err, gpointer user_data); 
    110 typedef void (*TnyMimePartCallback) (TnyMimePart *self, TnyStream *stream, gboolean canceled, GError *err, gpointer user_data); 
    111 typedef void (*TnyGetHeadersCallback) (TnyFolder *self, gboolean canceled, TnyList *headers, GError *err, gpointer user_data); 
    112 typedef void (*TnyGetMsgCallback) (TnyFolder *folder, gboolean canceled, TnyMsg *msg, GError *err, gpointer user_data); 
    113 typedef void (*TnyTransferMsgsCallback) (TnyFolder *folder, gboolean canceled, GError *err, gpointer user_data); 
    114 typedef void (*TnyStatusCallback) (GObject *self, TnyStatus *status, gpointer user_data); 
    115 typedef void (*TnyGetFoldersCallback) (TnyFolderStore *self, gboolean canceled, TnyList *list, GError *err, gpointer user_data); 
    116 typedef void (*TnyCopyFolderCallback) (TnyFolder *self, gboolean canceled, TnyFolderStore *into, TnyFolder *new_folder, GError *err, gpointer user_data); 
    117 typedef void (*TnySendQueueAddCallback) (TnySendQueue *self, gboolean canceled, TnyMsg *msg, GError *err, gpointer user_data); 
     110 
     111typedef void (*TnyMimePartCallback) (TnyMimePart *self, gboolean cancelled, TnyStream *stream, GError *err, gpointer user_data); 
     112 
     113typedef void (*TnyGetFoldersCallback) (TnyFolderStore *self, gboolean cancelled, TnyList *list, GError *err, gpointer user_data); 
     114typedef void (*TnyCreateFolderCallback) (TnyFolderStore *self, gboolean cancelled, TnyFolder *new_folder, GError *err, gpointer user_data); 
     115 
     116typedef void (*TnyFolderCallback) (TnyFolder *self, gboolean cancelled, GError *err, gpointer user_data); 
     117typedef void (*TnyGetHeadersCallback) (TnyFolder *self, gboolean cancelled, TnyList *headers, GError *err, gpointer user_data); 
     118typedef void (*TnyGetMsgCallback) (TnyFolder *folder, gboolean cancelled, TnyMsg *msg, GError *err, gpointer user_data); 
     119typedef void (*TnyTransferMsgsCallback) (TnyFolder *folder, gboolean cancelled, GError *err, gpointer user_data); 
     120typedef void (*TnyCopyFolderCallback) (TnyFolder *self, gboolean cancelled, TnyFolderStore *into, TnyFolder *new_folder, GError *err, gpointer user_data); 
     121 
     122typedef void (*TnySendQueueAddCallback) (TnySendQueue *self, gboolean cancelled, TnyMsg *msg, GError *err, gpointer user_data); 
    118123 
    119124G_END_DECLS 

  • trunk/libtinymailui-gtk/tny-gtk-image-mime-part-view.c

    r3070 r3151  
    8080 
    8181static void  
    82 on_mime_part_decoded (TnyMimePart *part, TnyStream *dest, gboolean canceled, GError *err, gpointer user_data) 
     82on_mime_part_decoded (TnyMimePart *part, gboolean canceled, TnyStream *dest, GError *err, gpointer user_data) 
    8383{ 
    8484        TnyMimePartView *self = (TnyMimePartView *) user_data; 

  • trunk/libtinymailui/tny-account-store-view.c

    r2825 r3151  
    1818 */ 
    1919 
     20 
     21/** 
     22 * TnyAccountStoreView: 
     23 *  
     24 * A view for a #TnyAccountStore 
     25 * 
     26 * free-function: g_object_unref 
     27 **/ 
     28 
    2029#include <config.h> 
    2130 
    …… 
    2534/** 
    2635 * tny_account_store_view_set_account_store: 
    27  * @self: A #TnyAccountStoreView instance 
    28  * @account_store: A #TnyAccountStore instace 
     36 * @self: A #TnyAccountStoreView 
     37 * @account_store: A #TnyAccountStore 
    2938 * 
    3039 * Set the account store of the view. 
    3140 * 
    32  * Implementors: This should let @self display @account_store. 
     41 * since: 1.0 
     42 * audience: application-developer, type-implementer 
    3343 **/ 
    3444void 

  • trunk/libtinymailui/tny-header-view.c

    r2825 r3151  
    1818 */ 
    1919 
     20 
     21/** 
     22 * TnyHeaderView: 
     23 *  
     24 * A view for a #TnyHeader 
     25 * 
     26 * free-function: g_object_unref 
     27 **/ 
     28 
    2029#include <config.h> 
    2130 
    …… 
    2433/** 
    2534 * tny_header_view_clear: 
    26  * @self: A #TnyHeaderView instance 
     35 * @self: A #TnyHeaderView 
    2736 * 
    28  * Clear @self (show nothing) 
     37 * Clear @self, show nothing 
    2938 * 
    30  * Implementors: this method should clear view @self (display nothing and  
    31  * clearup) 
    32  *  
     39 * since: 1.0 
     40 * audience: application-developer, type-implementer  
    3341 **/ 
    3442void 
    …… 
    4755/** 
    4856 * tny_header_view_set_header: 
    49  * @self: A #TnyHeaderView instance 
    50  * @header: A #TnyHeader instace 
     57 * @self: A #TnyHeaderView 
     58 * @header: A #TnyHeader 
    5159 * 
    5260 * Set @self to display @header 
    5361 *  
    54  * Implementors: this method should cause @self to show @header to the user. 
    55  * This typically means showing the from, to, subject, date and cc labels. 
     62 * Note that the #TnyHeaderView type is often used in a composition with a  
     63 * #TnyMsgView type (the #TnyMsgView implementation contains  or aggregates a  
     64 * #TnyHeaderView). 
    5665 * 
    57  * The #TnyHeaderView type is often used in a composition with a #TnyMsgView 
    58  * type (the #TnyMsgView implementation contains or aggregates a #TnyHeaderView). 
    59  * 
     66 * since: 1.0 
     67 * audience: application-developer, type-implementer 
    6068 **/ 
    6169void 

  • trunk/libtinymailui/tny-mime-part-save-strategy.c

    r2825 r3151  
    1818 */ 
    1919 
     20/** 
     21 * TnyMimePartSaveStrategy: 
     22 *  
     23 * A strategy for saving a #TnyMimePart 
     24 * 
     25 * free-function: g_object_unref 
     26 **/ 
     27 
    2028#include <config.h> 
    2129 
    …… 
    2432/** 
    2533 * tny_mime_part_save_strategy_perform_save: 
    26  * @self: A #TnyMimePartSaveStrategy instance 
    27  * @part: The #TnyMimePart instance that must be saved 
     34 * @self: a #TnyMimePartSaveStrategy 
     35 * @part: a #TnyMimePart that must be saved 
    2836 * 
    2937 * With @self being a delegate of a #TnyMimePartSaver, this method performs the 
    …… 
    3139 * 
    3240 * A save strategy for a mime part is used with a type that implements the  
    33  * #TnyMimePartSaver interface. Types that do, will often also implement the  
    34  * #TnyMsgView or #TnyMimePartView interface (it's not a requirement). In this 
    35  * case they say that the view has functionality for saving mime parts. 
    36  * 
    37  * You can for example inherit an implementation of a #TnyMsgView, like the  
    38  * #TnyGtkMsgView one, and let yours also implement #TnyMimePartSaver. The  
    39  * example shown here is for example such a situation. 
     41 * #TnyMimePartSaver interface. Very often are such types also implementing the 
     42 * #TnyMsgView and/or #TnyMimePartView interfaces (although it's not a 
     43 * requirement). When implementing #TnyMimePartSaver you say that the view has 
     44 * functionality for saving mime parts. 
    4045 * 
    4146 * Example: 
    …… 
    4550 * { 
    4651 *     TnyMyMsgView *self = TNY_MY_MSG_VIEW (self_i); 
    47  *     tny_mime_part_save_strategy_perform_save (self->mime_part_save_strategy, attachment); 
     52 *     tny_mime_part_save_strategy_perform_save (self->mime_part_save_strategy,  
     53 *              attachment); 
    4854 * } 
    4955 * </programlisting></informalexample> 
    5056 * 
    51  * Implementors: The idea is that devices can have specific strategies that can 
    52  * be changed at runtime. 
    53  * 
    54  * For example a strategy that sends it to another computer and/or a strategy 
    55  * that saves it to a flash disk. Configurable at runtime by simply switching 
    56  * the strategy property of a #TnyMimePartSaver. 
    57  * 
    58  * The implementation shown in this example implements it using the gtk+ toolkit. 
    59  * If your device doesn't support saving mime parts, saving a mime part can also 
    60  * be implemented by doing nothing. For example a #TnyMyDoNothingSaveStrategy.  
    61  * Maybe you will implement it by letting it contact a service and sending the 
    62  * mime part to it? It's up to you. 
     57 * Devices can have specific strategies that are changed at runtime. For example 
     58 * a save-strategy that sends the content of the mime part it to another computer 
     59 * and/or a save-strategy that saves it to a flash disk. Configurable at runtime 
     60 * by simply switching the save-strategy property of a #TnyMimePartSaver. 
    6361 * 
    6462 * Example: 
    …… 
    6967 *      GtkFileChooserDialog *dialog; 
    7068 *      dialog = GTK_FILE_CHOOSER_DIALOG  
    71  *            (gtk_file_chooser_dialog_new (_("MimePartSave File"), NULL, 
     69 *            (gtk_file_chooser_dialog_new (_("Save attachment"), NULL, 
    7270 *            GTK_FILE_CHOOSER_ACTION_MIME_PART_SAVE, 
    7371 *            GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL, GTK_STOCK_MIME_PART_SAVE,  
    …… 
    7573 *      gtk_file_chooser_set_current_name (dialog,  
    7674 *                    tny_mime_part_get_filename (part)); 
    77  *      if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)  
    78  *      { 
     75 *      if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT) { 
    7976 *            gchar *uri; int fd; 
    8077 *            uri = gtk_file_chooser_get_filename (dialog); 
    …… 
    8279 *            if (fd != -1) { 
    8380 *                      TnyStream *stream = tny_fs_stream_new (fd); 
    84  *                      tny_mime_part_decode_to_stream (part, TNY_STREAM (stream)); 
    85  *                      g_object_unref (G_OBJECT (stream)); 
     81 *                      tny_mime_part_decode_to_stream (part, stream); 
     82 *                      g_object_unref (stream); 
    8683 *            } 
    8784 *      } 
    …… 
    9087 * </programlisting></informalexample> 
    9188 * 
    92  * The method is typically called by the implementation of a #TnyMsgView. 
    93  * For example a clicked handler of a popup menu of a attachment view in your 
    94  * #TnyMsgView implementation. 
     89 * An example when to use this method is in a clicked handler of a popup menu 
     90 * of a attachment #TnyMimePartView in your #TnyMsgView. 
    9591 *  
    9692 * Note that a mime part can mean both the entire message (without its headers) 
    …… 
    9894 * case of a messge/rfc822 mime part). 
    9995 * 
    100  * A #TnyMsg inherits from #TnyMimePart which means that if you use the message 
    101  * instance with a #TnyMimePartSaveStrategy instance that the strategy for 
    102  * saving it must save the entire message. Whereas when you pass it just one 
    103  * individual mime part instance, the strategy must save only that part. 
     96 * since: 1.0 
     97 * audience: application-developer, type-implementer 
    10498 **/ 
    10599void 

  • trunk/libtinymailui/tny-mime-part-saver.c

    r2825 r3151  
    1818 */ 
    1919 
     20/** 
     21 * TnyMimePartSaver: 
     22 *  
     23 * A type that can save a #TnyMimePart 
     24 * 
     25 * free-function: g_object_unref 
     26 **/ 
     27 
    2028#include <config.h> 
    2129 
    …… 
    2533/** 
    2634 * tny_mime_part_saver_set_save_strategy: 
    27  * @self: A #TnyMimePartSaver instance 
    28  * @strategy: A TnyMimePartSaveStrategy instace 
     35 * @self: a #TnyMimePartSaver 
     36 * @strategy: a #TnyMimePartSaveStrategy 
    2937 * 
    3038 * Set the strategy for saving mime-parts 
    3139 * 
    32  * Implementors: This method must set (store) the strategy for saving a 
    33  * mime-part. 
     40 * Devices can have a specific strategy for storing a #TnyMimePart. For example 
     41 * a strategy that sends it to another computer or a strategy that saves it to 
     42 * a flash disk. In the message view component, you don't care about that: You 
     43 * only care about the API of the save-strategy interface. 
     44 * 
     45 * For more information take a look at tny_mime_part_save_strategy_perform_save() 
     46 * of #TnyMimePartSaveStrategy. 
     47 * 
    3448 * 
    3549 * Example: 
    …… 
    4054 *      TnyMyMsgView *self = TNY_MY_MSG_VIEW (self_i); 
    4155 *      if (self->save_strategy) 
    42  *            g_object_unref (G_OBJECT (self->save_strategy)); 
    43  *      self->save_strategy = g_object_ref (G_OBJECT (strat)); 
     56 *            g_object_unref (self->save_strategy); 
     57 *      self->save_strategy = g_object_ref (strat); 
    4458 * } 
    4559 * static void 
    …… 
    4761 * { 
    4862 *      if (self->save_strategy)) 
    49  *          g_object_unref (G_OBJECT (self->save_strategy)); 
     63 *          g_object_unref (self->save_strategy); 
    5064 * } 
    5165 * </programlisting></informalexample> 
    5266 * 
    53  * The idea is that devices can have a specific such strategy. For example a 
    54  * strategy that sends it to another computer or a strategy that saves it to 
    55  * a flash disk. However. In the message view component, you don't care about 
    56  * that. You only care about the API of the save-strategy interface. 
    57  * 
    58  * For more information take a look at tny_mime_part_save_strategy_perform_save 
    59  * of #TnyMimePartSaveStrategy. 
    60  * 
     67 * since: 1.0 
     68 * audience: application-developer, type-implementer 
    6169 **/ 
    6270void  
    …… 
    7684/** 
    7785 * tny_mime_part_saver_get_save_strategy: 
    78  * @self: A #TnyMsgView instance 
     86 * @self: a #TnyMsgView 
    7987 * 
    80  * Get the strategy for saving mime-parts. The return value must be 
     88 * Get the strategy for saving mime-parts. The returned value must be 
    8189 * unreferenced after use. 
     90 * 
     91 * For more information take a look at tny_mime_part_save_strategy_perform_save() 
     92 * of #TnyMimePartSaveStrategy. 
    8293 * 
    8394 * Example: 
    …… 
    8899 *     TnyMimePartSaveStrategy *strategy = tny_mime_part_saver_get_save_strategy (self); 
    89100 *     tny_save_strategy_save (strategy, attachment); 
    90  *     g_object_unref (G_OBJECT (strategy)); 
     101 *     g_object_unref (strategy); 
    91102 * } 
    92103 * </programlisting></informalexample> 
    93104 * 
    94  * Implementors: This method must return the strategy for saving a mime-part. 
    95  * being the implementer, you must add a reference before returning the instance. 
    96  * 
    97  * Example: 
    98  * <informalexample><programlisting> 
    99  * static *TnyMimePartSaveStrategy 
    100  * tny_my_msg_view_get_save_strategy (TnyMimePartSaver *self_i) 
    101  * { 
    102  *      TnyMyMsgView *self = TNY_MY_MSG_VIEW (self_i); 
    103  *      return TNY_MIME_PART_SAVE_STRATEGY (g_object_ref (self->mime_part_save_strategy)); 
    104  * } 
    105  * </programlisting></informalexample> 
    106  * 
    107  * For more information take a look at tny_mime_part_save_strategy_perform_save 
    108  * of #TnyMimePartSaveStrategy. 
    109  * 
    110  * Return value: the #TnyMimePartSaveStrategy for @self 
     105 * returns (caller-owns): the #TnyMimePartSaveStrategy for @self 
     106 * since: 1.0 
     107 * audience: application-developer, type-implementer 
    111108 **/ 
    112109TnyMimePartSaveStrategy* 
    …… 
    124121/** 
    125122 * tny_mime_part_saver_save: 
    126  * @self: A #TnyMimePartSaver instance 
    127  * @part: A #TnyMimePart instace 
     123 * @self: a #TnyMimePartSaver 
     124 * @part: a #TnyMimePart 
    128125 * 
    129  * Saves @mime_part using the save strategy 
     126 * Saves @mime_part using the save strategy of @self. 
    130127 * 
     128 * since: 1.0 
     129 * audience: application-developer, type-implementer 
    131130 **/ 
    132131void 
    …… 
    179178} 
    180179 
    181  

  • trunk/libtinymailui/tny-mime-part-view.c

    r3070 r3151  
    1818 */