This is a manual merge of branch drop split view intro trunk.
[modest] / src / widgets / modest-header-view.h
1 /* Copyright (c) 2006, Nokia Corporation
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  * * Redistributions of source code must retain the above copyright
9  *   notice, this list of conditions and the following disclaimer.
10  * * Redistributions in binary form must reproduce the above copyright
11  *   notice, this list of conditions and the following disclaimer in the
12  *   documentation and/or other materials provided with the distribution.
13  * * Neither the name of the Nokia Corporation nor the names of its
14  *   contributors may be used to endorse or promote products derived from
15  *   this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
18  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
20  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
21  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
24  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
25  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
26  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29
30 #ifndef __MODEST_HEADER_VIEW_H__
31 #define __MODEST_HEADER_VIEW_H__
32
33 #include <tny-folder.h>
34 #include <tny-folder-change.h>
35 #include <tny-gtk-account-list-model.h>
36 #include <tny-msg.h>
37 #include <tny-header.h>
38 #include <tny-gtk-header-list-model.h>
39 #include "modest-mail-operation.h"
40 #include "modest-header-view-observer.h"
41
42 G_BEGIN_DECLS
43
44 /* convenience macros */
45 #define MODEST_TYPE_HEADER_VIEW             (modest_header_view_get_type())
46 #define MODEST_HEADER_VIEW(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj),MODEST_TYPE_HEADER_VIEW,ModestHeaderView))
47 #define MODEST_HEADER_VIEW_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),MODEST_TYPE_HEADER_VIEW,ModestHeaderViewClass))
48 #define MODEST_IS_HEADER_VIEW(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),MODEST_TYPE_HEADER_VIEW))
49 #define MODEST_IS_HEADER_VIEW_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),MODEST_TYPE_HEADER_VIEW))
50 #define MODEST_HEADER_VIEW_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj),MODEST_TYPE_HEADER_VIEW,ModestHeaderViewClass))
51
52 typedef struct _ModestHeaderView      ModestHeaderView;
53 typedef struct _ModestHeaderViewClass ModestHeaderViewClass;
54
55 struct _ModestHeaderView {
56          GtkTreeView parent;
57         /* insert public members, if any */
58 };
59
60 #define MODEST_HEADER_VIEW_COLUMN    "header-view-column"
61 #define MODEST_HEADER_VIEW_FLAG_SORT "header-view-flags-sort"
62
63 typedef enum _ModestHeaderViewColumn {
64         MODEST_HEADER_VIEW_COLUMN_FROM,
65         MODEST_HEADER_VIEW_COLUMN_TO,
66         MODEST_HEADER_VIEW_COLUMN_SUBJECT,
67         MODEST_HEADER_VIEW_COLUMN_SENT_DATE,
68         MODEST_HEADER_VIEW_COLUMN_RECEIVED_DATE,
69         MODEST_HEADER_VIEW_COLUMN_ATTACH,
70         MODEST_HEADER_VIEW_COLUMN_SIZE,
71         MODEST_HEADER_VIEW_COLUMN_STATUS,
72
73         /*
74          * these two are for compact display on small devices,
75          * with two line display with all relevant headers
76          */
77         MODEST_HEADER_VIEW_COLUMN_COMPACT_FLAG, /* priority and attachments */
78         MODEST_HEADER_VIEW_COLUMN_COMPACT_HEADER_IN, /* incoming mail */
79         MODEST_HEADER_VIEW_COLUMN_COMPACT_HEADER_OUT,/* outgoing mail */
80         MODEST_HEADER_VIEW_COLUMN_COMPACT_SENT_DATE,
81         MODEST_HEADER_VIEW_COLUMN_COMPACT_RECEIVED_DATE,
82
83         MODEST_HEADER_VIEW_COLUMN_NUM
84         
85 } ModestHeaderViewColumn;
86
87 /*
88  * this can be extended with more style thingies,
89  * to make a small-device specific display
90  */
91 typedef enum _ModestHeaderViewStyle {
92         MODEST_HEADER_VIEW_STYLE_DETAILS   = 0, /* many columns, single line, col headers visible */
93         MODEST_HEADER_VIEW_STYLE_TWOLINES  = 1, /* two-line headers, col headers invisible */
94         
95         MODEST_HEADER_VIEW_STYLE_NUM    
96 } ModestHeaderViewStyle;
97
98 typedef enum _ModestItemType {
99         MODEST_ITEM_TYPE_MESSAGE,
100         MODEST_ITEM_TYPE_FOLDER,
101         MODEST_ITEM_TYPE_NUM
102 } ModestItemType;
103
104
105 struct _ModestHeaderViewClass {
106         GtkTreeViewClass parent_class;
107
108         void (*header_selected) (ModestHeaderView* self,
109                                  TnyHeader *header,
110                                  gpointer user_data);
111
112         void (*item_not_found) (ModestHeaderView* self,
113                                 ModestItemType type,
114                                 gpointer user_data);
115
116         void (*header_activated) (ModestHeaderView* self,
117                                   TnyHeader *header,
118                                   GtkTreePath *path,
119                                   gpointer user_data);
120
121         void (*msg_count_changed) (ModestHeaderView* self,
122                                    TnyFolder *folder,
123                                    TnyFolderChange *change,
124                                    gpointer user_data);
125
126         void (*updating_msg_list) (ModestHeaderView *self,
127                                    gboolean starting,
128                                    gpointer user_data);
129 };
130
131 /**
132  * modest_header_view_get_type:
133  * 
134  * get the GType for ModestHeaderView
135  *  
136  * Returns: the GType
137  */
138 GType        modest_header_view_get_type    (void) G_GNUC_CONST;
139
140
141 /**
142  * modest_header_view_new:
143  * @folder: a TnyMsgFolder object
144  * @style: a ModestHeaderViewColumn with the style of this listview
145  *  (   MODEST_HEADER_VIEW_STYLE_NORMAL or MODEST_HEADER_VIEW_STYLE_COMPACT)
146  * 
147  * create a new ModestHeaderView instance, based on a folder iface
148  *   
149  * Returns: a new GtkWidget (a GtkTreeView-subclass)
150  */
151 GtkWidget*   modest_header_view_new        (TnyFolder *folder,
152                                             ModestHeaderViewStyle style);
153
154 /**
155  * modest_header_view_set_folder:
156  * @self: a ModestHeaderView instance
157  * @folder: a TnyFolder object
158  * 
159  * set the folder for this ModestHeaderView
160  */
161 void         modest_header_view_set_folder (ModestHeaderView *self,
162                                             TnyFolder *folder,
163                                             gboolean refresh,
164                                             ModestWindow *progress_window,
165                                             RefreshAsyncUserCallback callback,
166                                             gpointer user_data);
167
168 /**
169  * modest_header_view_get_folder:
170  * @self: a ModestHeaderView instance
171  * 
172  * get the folder in this ModestHeaderView
173  *  
174  * Returns: the tny folder instance or NULL if there is none
175  */
176 TnyFolder *modest_header_view_get_folder (ModestHeaderView *self);
177
178
179 /**
180  * modest_header_view_set_columns:
181  * @self: a ModestHeaderView instance
182  * @columns: a list of gint ModestHeaderViewColumn column IDs, using GINT_TO_POINTER() and GPOINTER_TO_INT().
183  * @type: #TnyFolderType type
184  * 
185  * set the columns for this ModestHeaderView.
186  *  
187  * Returns: TRUE if it succeeded, FALSE otherwise
188  */
189 gboolean modest_header_view_set_columns (ModestHeaderView *self,
190                                          const GList *columns,
191                                          TnyFolderType type);
192 /**
193  * modest_header_view_get_columns:
194  * @self: a ModestHeaderView instance
195  * 
196  * get the GtkTreeColumns for this ModestHeaderView. Each one of the
197  * tree columns will have property  than can be retrieved
198  * with g_object_get_data MODEST_HEADER_VIEW_COLUMN (#define),
199  * and which contains the corresponding ModestHeaderViewColumn
200  *  
201  * Returns: newly allocated list of #GtkTreeViewColumns objects, or NULL in case of no columns or error
202  * You must free the list with g_list_free
203  */
204 GList*  modest_header_view_get_columns (ModestHeaderView *self);
205
206
207 /**
208  * modest_header_view_set_style:
209  * @self: a ModestHeaderView instance
210  * @style: the style for this tree view
211  * 
212  * set the style for this ModestHeaderView
213  *  
214  * Returns: TRUE if it succeeded, FALSE otherwise
215  */
216 gboolean   modest_header_view_set_style (ModestHeaderView *self,
217                                          ModestHeaderViewStyle style);
218
219 /**
220  * modest_header_view_set_folder:
221  * @self: a ModestHeaderView instance
222  * 
223  * get the style for this ModestHeaderView
224  *  
225  * Returns: the current style
226  */
227 ModestHeaderViewStyle   modest_header_view_get_style (ModestHeaderView *self);
228
229 /**
230  * modest_header_view_count_selected_headers:
231  * @self: a ModestHeaderView instance
232  * 
233  * Check selected headers counter. 
234  * Returns: the number of selected headers.
235  */
236 guint
237 modest_header_view_count_selected_headers (ModestHeaderView *self);
238
239 /**
240  * modest_header_view_has_selected_headers:
241  * @self: a ModestHeaderView instance
242  * 
243  * Check if any row is selected on headers tree view. 
244  * Returns: TRUE if any header is selected, FALSE otherwise.
245  */
246 gboolean
247 modest_header_view_has_selected_headers (ModestHeaderView *self);
248
249 /**
250  * modest_header_view_get_selected_headers:
251  * @self: a ModestHeaderView instance
252  * 
253  * get the list of the currently selected TnyHeader's. The list and
254  * the headers should be freed by the caller
255  *  
256  * Returns: the list with the currently selected headers
257  */
258 TnyList* modest_header_view_get_selected_headers (ModestHeaderView *self);
259
260
261 /**
262  * modest_header_view_is_empty:
263  * @self: a valid ModestHeaderView instance
264  * 
265  * see if this header view is empty; use this function instead of
266  * using the GtkTreeView parent directly, as 'empty' in this case
267  * may mean that there is one "This is empty"-message, and of course
268  * GtkTreeView then thinks it is *not* empty
269  *  
270  * Returns: TRUE if the header view is empty, FALSE otherwise
271  */
272 gboolean  modest_header_view_is_empty (ModestHeaderView *self);
273
274
275
276 /**
277  * modest_header_view_select_next:
278  * @self: a #ModestHeaderView
279  * 
280  * Selects the header next to the current selected one
281  **/
282 void         modest_header_view_select_next          (ModestHeaderView *self);
283
284 /**
285  * modest_header_view_select_prev:
286  * @self: a #ModestHeaderView
287  * 
288  * Selects the previous header of the current selected one
289  **/
290 void         modest_header_view_select_prev          (ModestHeaderView *self);
291
292
293 /* PROTECTED method. It's useful when we want to force a given
294    selection to reload a msg. For example if we have selected a header
295    in offline mode, when Modest become online, we want to reload the
296    message automatically without an user click over the header */
297 void 
298 _modest_header_view_change_selection (GtkTreeSelection *selection,
299                                       gpointer user_data);
300
301 /**
302  * modest_header_view_get_sort_column_id:
303  * @self: a #ModestHeaderView
304  * @type: #TnyFolderType type
305  * 
306  * Gets the selected logical columnd id for sorting.
307  **/
308 gint
309 modest_header_view_get_sort_column_id (ModestHeaderView *self, TnyFolderType type);
310
311 /**
312  * modest_header_view_get_sort_type:
313  * @self: a #ModestHeaderView
314  * @type: #TnyFolderType type
315  * 
316  * Gets the selected sort type.
317  **/
318 GtkSortType
319 modest_header_view_get_sort_type (ModestHeaderView *self, TnyFolderType type);
320
321 /**
322  * modest_header_view_set_sort_params:
323  * @self: a #ModestHeaderView
324  * @sort_colid: logical column id to sort
325  * @sort_type: #GtkSortType sort type
326  * @type: #TnyFolderType type
327  * 
328  * Sets the logical columnd id and sort type for sorting operations.
329  **/
330 void
331 modest_header_view_set_sort_params (ModestHeaderView *self, guint sort_colid, GtkSortType sort_type, TnyFolderType type);
332
333 /**
334  * modest_header_view_set_sort_params:
335  * @self: a #ModestHeaderView
336  * @sort_colid: logical column id to sort
337  * @sort_type: #GtkSortType sort type
338  * 
339  * Sorts headers treeview by logical column id, @sort_colid, using a 
340  * @sort_type sorting method. In addition, new headder settings will be 
341  * stored in @self object. 
342  **/
343 void
344 modest_header_view_sort_by_column_id (ModestHeaderView *self, 
345                                       guint sort_colid,
346                                       GtkSortType sort_type);
347
348 /**
349  * modest_header_view_clear:
350  * @self: a #ModestHeaderView
351  *
352  * Clear the contents of a header view. It internally calls the
353  * set_folder function with last three arguments as NULL
354  **/
355 void
356 modest_header_view_clear (ModestHeaderView *self);
357
358 /**
359  * modest_header_view_copy_selection:
360  * @self: a #ModestHeaderView
361  * 
362  * Stores a #TnyList of selected headers in the own clibpoard of 
363  * @self header view.
364  **/
365 void 
366 modest_header_view_copy_selection (ModestHeaderView *header_view);
367
368 /**
369  * modest_header_view_cut_selection:
370  * @self: a #ModestHeaderView
371  * 
372  * Stores a #TnyList of selected headers in the own clibpoard of 
373  * @self header view and filter them into headers tree model to
374  * hide these rows in treeview.
375  **/
376 void 
377 modest_header_view_cut_selection (ModestHeaderView *header_view);
378
379
380 /**
381  * modest_header_view_paste_selection:
382  * @self: a #ModestHeaderView
383  * @headers: ouput parameter with a #TnyList of headers which will be returned.
384  * @delete: output parameter with indication about delete or not the selected headers. 
385  * 
386  * Gets the selected headers to copy/cut.
387  **/
388 void
389 modest_header_view_paste_selection (ModestHeaderView *header_view,
390                                     TnyList **headers,
391                                     gboolean *delete);
392
393 void modest_header_view_refilter (ModestHeaderView *header_view);
394
395 /**
396  * modest_header_view_add_observer:
397  * @header_view: a #ModestHeaderView
398  * @observer: The observer to notify.
399  * 
400  * Registers a new observer. Warning! Each added observer object must
401  * removed using @modest_header_view_remove_observer before destroying
402  * the observer, or at least when it is under destruction. Also you
403  * should care about that the observer's #update function might be
404  * called any time until the observer is removed.
405  **/
406 void modest_header_view_add_observer(
407                 ModestHeaderView *header_view,
408                 ModestHeaderViewObserver *observer);
409
410 /**
411  * modest_header_view_remove_observer:
412  * @header_view: a #ModestHeaderView
413  * @observer: The observer to remove.
414  * 
415  * Removes exactly one observer from the notification list. If you
416  * added an observer twice, you should call this remove funtion twice
417  * as well.
418  **/
419 void modest_header_view_remove_observer(
420                 ModestHeaderView *header_view,
421                 ModestHeaderViewObserver *observer);
422
423 G_END_DECLS
424
425
426
427 #endif /* __MODEST_HEADER_VIEW_H__ */
428