Changeset 1002

Show
Ignore:
Timestamp:
10/16/06 00:09:02
Author:
pvanhoof
Message:

Docs updated

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r900 r1002  
    2828 * @account_store: A #TnyAccountStore instace 
    2929 * 
    30  * Set the account store of the view 
    31  *  
     30 * Set the account store of the view. 
     31 * 
     32 * Implementors: This should let the account store view @self display the  
     33 * account store @account_store. 
    3234 **/ 
    3335void 

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

    r908 r1002  
    2222#include <tny-header-view.h> 
    2323 
    24  
    2524/** 
    2625 * tny_header_view_clear: 
    …… 
    2928 * Clear the view @self (show nothing) 
    3029 * 
    31  * Implementors: this method should clear @self (display nothing, or display 
    32  * a picture with flowers and nude people if that is how your E-mail client 
    33  * indicates that there's no header loaded) 
     30 * Implementors: this method should clear view @self (display nothing and  
     31 * clearup) 
    3432 *  
    3533 **/ 
    …… 
    5553 *  
    5654 * Implementors: this method should cause the view @self to show the header 
    57  * @header to the user. Often this means showing the from, to, subject, date 
     55 * @header to the user. This typically means showing the from, to, subject, date 
    5856 * and cc labels. 
    5957 * 
    60  * #TnyHeaderView is often used in a composition with the #TnyMsgView 
    61  * type (the #TnyMsgView implementation contains a #TnyHeaderView). 
     58 * #TnyHeaderView is often used in a composition with a #TnyMsgView 
     59 * type (the #TnyMsgView implementation contains or aggregates a #TnyHeaderView). 
    6260 * 
    6361 **/ 

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

    r998 r1002  
    2929 * Performs the saving of a mime part 
    3030 * 
     31 * A save strategy for a mime part is used with a type that implements the  
     32 * #TnyMimePartSaver interface. Types that do, will often also implement the  
     33 * #TnyMsgView interface (it's not a requirement). In this case they say that  
     34 * the view has functionality for saving mime parts. 
     35 * 
     36 * You can for example inherit an implementation of a #TnyMsgView, like the  
     37 * #TnyGtkMsgView one, and let yours also implement #TnyMimePartSaver. The  
     38 * example shown here is such a situation 
     39 * 
    3140 * Example: 
    3241 * <informalexample><programlisting> 
    3342 * static void  
    34  * tny_my_msg_view_on_mime_part_save_clicked (TnyMsgView *self_i, TnyMimePart *attachment) 
     43 * tny_my_msg_view_perform_save (TnyMimePartView *self_i, TnyMimePart *attachment) 
    3544 * { 
    3645 *     TnyMyMsgView *self = TNY_MY_MSG_VIEW (self_i); 
    …… 
    3948 * </programlisting></informalexample> 
    4049 * 
    41  * Implementors: the idea is that devices can have a specific such strategy. 
    42  * For example a strategy that sends it to another computer or a strategy that 
    43  * saves it to a flash disk.  
     50 * Implementors: The idea is that devices can have specific such strategies. 
     51 * For example a strategy that sends it to another computer and/or a strategy 
     52 * that saves it to a flash disk. Configurable at runtime by simply switching 
     53 * the strategy property of a #TnyMimePartSaver. 
     54 * 
     55 * The implementation shown in the example implements it using the gtk+ toolkit. 
     56 * Saving a mime part can also be doing nothing, if your device doesn't support 
     57 * it. Maybe you will implement it by letting it contact a service and sending 
     58 * the mime part to it? It's up to you. 
    4459 * 
    4560 * Example: 
    …… 
    7489 * #TnyMsgView implementation. 
    7590 *  
     91 * Note that a mime can mean both the entire message (without its headers) and 
     92 * one individual mime part in such a message. A #TnyMsg inherits from #TnyMimePart 
     93 * which means that if you use the message instance with a #TnyMimePartSaveStrategy 
     94 * instance, that the strategy for saving it will save the entire message. Whereas 
     95 * when you pass it just one individual mime part instance, the strategy will  
     96 * save only that part. 
    7697 **/ 
    7798void 

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

    r994 r1002  
    7575 * @mime_part: A #TnyMimePart instace 
    7676 * 
    77  * Set mime part of the view @self 
     77 * Set mime part which the view @self should display. 
    7878 *  
    7979 * Implementors: this method should cause the view @self to show the mime part 

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

    r994 r1002  
    2727 * @part: A #TnyMimePart instance 
    2828 * 
    29  * Create a #TnyMimePartView instance for viewing @part 
     29 * Create a #TnyMimePartView instance for viewing @part. The returned instance 
     30 * must be unreferenced after use. 
     31 * 
     32 * Implementors: This method should create and return a new #TnyMimePartView  
     33 * that is suitable for displaying the #TnyMimePart @part. 
     34 * 
     35 * Example: 
     36 * <informalexample><programlisting> 
     37 * static TnyMimePartView* 
     38 * tny_gtk_msg_view_create_mime_part_view_for (TnyMsgView *self, TnyMimePart *part) 
     39 * { 
     40 *     TnyGtkMsgViewPriv *priv = TNY_GTK_MSG_VIEW_GET_PRIVATE (self); 
     41 *     TnyMimePartView *retval = NULL; 
     42 *     if (tny_mime_part_content_type_is (part, "text/*")) 
     43 *     { 
     44 *         retval = tny_gtk_text_mime_part_view_new (); 
     45 *         gtk_box_pack_start (GTK_BOX (TNY_GTK_MSG_VIEW (self)->viewers),  
     46 *                GTK_WIDGET (retval), TRUE, TRUE, 0); 
     47 *         gtk_widget_show (GTK_WIDGET (retval)); 
     48 *    } else if (tny_mime_part_get_content_type (part) && 
     49 *           tny_mime_part_is_attachment (part)) 
     50 *    { 
     51 *         static gboolean first = TRUE; 
     52 *         GtkTreeModel *model; 
     53 *         gtk_widget_show (priv->attachview_sw); 
     54 *         if (first) 
     55 *         { 
     56 *              model = tny_gtk_attach_list_model_new (); 
     57 *              gtk_icon_view_set_model (priv->attachview, model); 
     58 *              first = FALSE; 
     59 *         } else 
     60 *             model = gtk_icon_view_get_model (priv->attachview); 
     61 *             retval = tny_gtk_attachment_mime_part_view_new (TNY_GTK_ATTACH_LIST_MODEL (model)); 
     62 *         } 
     63 *         return retval; 
     64 * } 
     65 * </programlisting></informalexample> 
     66 * 
     67 * This example is the implementation of #TnyGtkMsgView. If you are planning to 
     68 * use libtinymailui-gtk, which contains this type, it's also possible to inherit 
     69 * from this type. Take for example another type in libtinymailui-mozembed that 
     70 * implements one that adds support for a text/html mime part. 
     71 * 
     72 * Example: 
     73 * <informalexample><programlisting> 
     74 * static TnyMimePartView* 
     75 * tny_moz_embed_msg_view_create_mime_part_view_for (TnyMsgView *self, TnyMimePart *part) 
     76 * { 
     77 *     TnyMimePartView *retval = NULL; 
     78 *     if (tny_mime_part_content_type_is (part, "text/html")) 
     79 *     { 
     80 *         retval = tny_moz_embed_html_mime_part_view_new (); 
     81 *         gtk_box_pack_start (GTK_BOX (TNY_GTK_MSG_VIEW (self)->viewers), GTK_WIDGET (retval), TRUE, TRUE, 0); 
     82 *         gtk_widget_show (GTK_WIDGET (retval)); 
     83 *     } 
     84 *     if (!retval) 
     85 *              retval = TNY_MOZ_EMBED_MSG_VIEW_GET_CLASS (self)->create_mime_part_view_for_orig_func (self, part); 
     86 *     return retval; 
     87 * } 
     88 * static void  
     89 * tny_moz_embed_msg_view_class_init (TnyMozEmbedMsgViewClass *class) 
     90 * { 
     91 *      GObjectClass *object_class; 
     92 *      parent_class = g_type_class_peek_parent (class); 
     93 *      object_class = (GObjectClass*) class; 
     94 *      object_class->finalize = tny_moz_embed_msg_view_finalize; 
     95 *      class->create_mime_part_view_for_orig_func = TNY_GTK_MSG_VIEW_CLASS (class)->create_mime_part_view_for_func;     
     96 *      TNY_GTK_MSG_VIEW_CLASS (class)->create_mime_part_view_for_func = tny_moz_embed_msg_view_create_mime_part_view_for; 
     97 * } 
     98 * </programlisting></informalexample> 
    3099 * 
    31100 * Return value: A #TnyMimePartView instance for viewing @part 
    …… 
    48117 * Clear the view @self (show nothing) 
    49118 *  
    50  * Implementors: this method should clear @self (display nothing, or display 
    51  * a picture with flowers and nude people if that is how your E-mail client 
    52  * indicates that there's no message loaded) 
    53  * 
     119 * Implementors: this method should clear @self (display nothing and clearup) 
    54120 **/ 
    55121void 
    …… 
    94160 * @self: A #TnyMsgView instance 
    95161 * 
    96  * Get message of the view @self The return value must be unreferenced after 
    97  * use. 
     162 * Get the current message of the view @self. The returned instance must be  
     163 * unreferenced after use. 
    98164 *  
    99165 * Implementors: this method should return the message this view is currently 
    …… 
    119185 * @msg: A #TnyMsg instace 
    120186 * 
    121  * Set message of the view @self 
     187 * Set the message which view @self must display. 
    122188 *  
    123189 * Implementors: this method should cause the view @self to show the message 
    124190 * @msg to the user. This includes showing the header (for which you can 
    125191 * make a composition with a #TnyHeaderView), the message body and the 
    126  * attachments. 
     192 * attachments (for which you typically use the #TnyMimePartView interface and 
     193 * implementations). 
    127194 * 
    128195 * You can get a list of mime-parts using the tny_msg_get_parts API of 
    129  * the #TnyMsg type. If the mime-part has as content type a type that your 
    130  * viewer supports and recognises as an E-mail body (you can check the content 
    131  * type if a mime-part using tny_mime_part_content_type_is), the view 
    132  * should show it. 
    133  * 
    134  * It's advised to use the #TnyStream API for streaming the decoded content 
    135  * of the mime-part to the model of your view that will display the body. 
    136  * Examples are #TnyMsgView in libtinymailui-gtk and #TnyMozEmbedMsgView in 
    137  * libtinymailui-mozembed. If you don't decode the content of the mime-part, 
    138  * for example using tny_mime_part_decode_to_stream, the content might be 
    139  * encoded in a format suitable for data transfer over for example SMTP. 
    140  * 
     196 * the #TnyMsg type. You can use the tny_msg_view_create_mime_part_view_for 
     197 * API to get an instance of a #TnyMimePartView that can view the mime part. 
     198 * 
     199 * Example: 
     200 * <informalexample><programlisting> 
     201 * static void  
     202 * tny_my_msg_view_set_msg (TnyMsgView *self, TnyMsg *msg) 
     203 * { 
     204 *     TnyIterator *iterator; 
     205 *     TnyList *list = tny_simple_list_new (); 
     206 *     tny_msg_view_clear (self); 
     207 *     header = tny_msg_get_header (msg); 
     208 *     tny_header_view_set_header (priv->headerview, header); 
     209 *     g_object_unref (G_OBJECT (header)); 
     210 *     tny_msg_get_parts (msg, list); 
     211 *     iterator = tny_list_create_iterator (list); 
     212 *     while (!tny_iterator_is_done (iterator)) 
     213 *     { 
     214 *         TnyMimePart *part = tny_iterator_get_current (iterator); 
     215 *         TnyMimePartView *mpview; 
     216 *         mpview = tny_msg_view_create_mime_part_view_for (self, part); 
     217 *         if (mpview) 
     218 *             tny_mime_part_view_set_part (mpview, part); 
     219 *         g_object_unref (G_OBJECT(part)); 
     220 *         tny_iterator_next (iterator); 
     221 *     } 
     222 *     g_object_unref (G_OBJECT (iterator)); 
     223 *     g_object_unref (G_OBJECT (list)); 
     224 * } 
     225 * </programlisting></informalexample> 
    141226 **/ 
    142227void 

  • trunk/libtinymailui/tny-platform-factory.c

    r900 r1002  
    2929 * @self: a TnyPlatformFactory object 
    3030 * 
     31 * Get a new #TnyAccountStore instance. The returned instance must be  
     32 * unreferenced after use. 
     33 * 
    3134 * Implementors: when implementing a platform-specific library, return a  
    3235 * new #TnyAccountStore instance. 
    3336 * 
    3437 * Return value: a #TnyAccountStore instance 
    35  * 
    3638 **/ 
    3739TnyAccountStore* 
    …… 
    4951 * tny_platform_factory_new_device: 
    5052 * @self: a TnyPlatformFactory object 
     53 * 
     54 * 
     55 * Get a new #TnyDevice instance. The returned instance must be  
     56 * unreferenced after use. 
    5157 * 
    5258 * Implementors: when implementing a platform-specific library, return a  
    …… 
    7177 * @self: a TnyPlatformFactory object 
    7278 * 
     79 * Get a new #TnyMsgView instance. The returned instance must be  
     80 * unreferenced after use. 
     81 * 
    7382 * Implementors: when implementing a platform-specific library, return a  
    7483 * new #TnyMsgView instance. 
    7584 * 
    7685 * Return value: a #TnyMsgView instance 
    77  * 
    7886 **/ 
    7987TnyMsgView*