1 /*
2  * e-shell-view.h
3  *
4  * This program is free software; you can redistribute it and/or modify it
5  * under the terms of the GNU Lesser General Public License as published by
6  * the Free Software Foundation.
7  *
8  * This program is distributed in the hope that it will be useful, but
9  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
11  * for more details.
12  *
13  * You should have received a copy of the GNU Lesser General Public License
14  * along with this program; if not, see <http://www.gnu.org/licenses/>.
15  *
16  *
17  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
18  *
19  */
20 
21 #ifndef E_SHELL_VIEW_H
22 #define E_SHELL_VIEW_H
23 
24 #include <libedataserver/libedataserver.h>
25 
26 #include <e-util/e-util.h>
27 
28 #include <shell/e-shell-common.h>
29 #include <shell/e-shell-backend.h>
30 #include <shell/e-shell-content.h>
31 #include <shell/e-shell-sidebar.h>
32 #include <shell/e-shell-taskbar.h>
33 #include <shell/e-shell-window.h>
34 
35 /* Standard GObject macros */
36 #define E_TYPE_SHELL_VIEW \
37 	(e_shell_view_get_type ())
38 #define E_SHELL_VIEW(obj) \
39 	(G_TYPE_CHECK_INSTANCE_CAST \
40 	((obj), E_TYPE_SHELL_VIEW, EShellView))
41 #define E_SHELL_VIEW_CLASS(cls) \
42 	(G_TYPE_CHECK_CLASS_CAST \
43 	((cls), E_TYPE_SHELL_VIEW, EShellViewClass))
44 #define E_IS_SHELL_VIEW(obj) \
45 	(G_TYPE_CHECK_INSTANCE_TYPE \
46 	((obj), E_TYPE_SHELL_VIEW))
47 #define E_IS_SHELL_VIEW_CLASS(cls) \
48 	(G_TYPE_CHECK_CLASS_TYPE \
49 	((cls), E_TYPE_SHELL_VIEW))
50 #define E_SHELL_VIEW_GET_CLASS(obj) \
51 	(G_TYPE_INSTANCE_GET_CLASS \
52 	((obj), E_TYPE_SHELL_VIEW, EShellViewClass))
53 
54 G_BEGIN_DECLS
55 
56 typedef struct _EShellView EShellView;
57 typedef struct _EShellViewClass EShellViewClass;
58 typedef struct _EShellViewPrivate EShellViewPrivate;
59 
60 /**
61  * EShellView:
62  *
63  * Contains only private data that should be read and manipulated using the
64  * functions below.
65  **/
66 struct _EShellView {
67 	GObject parent;
68 	EShellViewPrivate *priv;
69 };
70 
71 /**
72  * EShellViewClass:
73  * @parent_class:	The parent class structure.
74  * @label:		The initial value for the switcher action's
75  *			#GtkAction:label property.  See
76  *			e_shell_view_get_action().
77  * @icon_name:		The initial value for the switcher action's
78  *			#GtkAction:icon-name property.  See
79  *			e_shell_view_get_action().
80  * @ui_definition:	Base name of the UI definition file to add
81  *			when the shell view is activated.
82  * @ui_manager_id:	The #GtkUIManager ID for #EPluginUI.  Plugins
83  *			should use to this ID in their "eplug" files to
84  *			add menu and toolbar items to the shell view.
85  * @search_context_type:GType of the search context, which should be an
86  *			instance of ERuleContextClass or a custom subclass.
87  * @search_context:	A unique @search_context_type instance is created
88  *			automatically for each subclass and shared across
89  *			all instances of that subclass.
90  * @search_options:	Widget path in the UI definition to the search
91  *			options popup menu.  The menu gets shown when the
92  *			user clicks the "find" icon in the search entry.
93  * @search_rules:	Base name of the XML file containing predefined
94  *			search rules for this shell view.  The XML files
95  *			are usually named something like <filename>
96  *			<emphasis>view</emphasis>types.xml</filename>.
97  * @view_collection:	A unique #GalViewCollection instance is created
98  *			for each subclass and shared across all instances
99  *			of that subclass.  That much is done automatically
100  *			for subclasses, but subclasses are still responsible
101  *			for adding the appropriate #GalView factories to the
102  *			view collection.
103  * @shell_backend:	The corresponding #EShellBackend for the shell view.
104  * @new_shell_content:	Factory method for the shell view's #EShellContent.
105  *			See e_shell_view_get_shell_content().
106  * @new_shell_sidebar:	Factory method for the shell view's #EShellSidebar.
107  *			See e_shell_view_get_shell_sidebar().
108  * @new_shell_taskbar:	Factory method for the shell view's #EShellTaskbar.
109  *			See e_shell_view_get_shell_taskbar().
110  * @new_shell_searchbar:
111  *			Factory method for the shell view's #EShellSearchbar.
112  *			See e_shell_view_get_searchbar().
113  * @construct_searchbar:
114  *			Class method to create, configure and pack a search
115  *			bar widget.  The search bar differs in normal shell
116  *			mode versus "express" mode.
117  * @get_search_name:	Class method to obtain a suitable name for the
118  *			current search criteria.  Subclasses should rarely
119  *			need to override the default behavior.
120  * @toggled:		Class method for the #EShellView::toggled signal.
121  *			Subclasses should rarely need to override the
122  *			default behavior.
123  * @clear_search:	Class method for the #EShellView::clear-search
124  *			signal.  The default method sets the
125  *			#EShellView:search-rule to %NULL and then emits
126  *			the #EShellView::execute-search signal.
127  * @custom_search:	Class method for the #EShellView::custom-search
128  *			signal.  This is emitted prior to executing an
129  *			advanced or saved search.  The default method sets
130  *			the #EShellView:search-rule property and then emits
131  *			the #EShellView::execute-search signal.
132  * @execute_search:	Class method for the #EShellView::execute-search
133  *			signal.  There is no default behavior; subclasses
134  *			should override this.
135  * @update_actions:	Class method for the #EShellView::update-actions
136  *			signal.  There is no default behavior; subclasses
137  *			should override this.
138  *
139  * #EShellViewClass contains a number of important settings for subclasses.
140  **/
141 struct _EShellViewClass {
142 	GObjectClass parent_class;
143 
144 	/* Initial switcher action values. */
145 	const gchar *label;
146 	const gchar *icon_name;
147 
148 	/* Base name of the UI definition file. */
149 	const gchar *ui_definition;
150 
151 	/* GtkUIManager identifier for use with EPluginUI.
152 	 * Usually "org.gnome.evolution.$(VIEW_NAME)". */
153 	const gchar *ui_manager_id;
154 
155 	/* Search context.  Subclasses may override the type.
156 	 * A unique instance is created for each subclass. */
157 	GType search_context_type;
158 	ERuleContext *search_context;
159 
160 	/* Widget path to the search options popup menu. */
161 	const gchar *search_options;
162 
163 	/* Base name of the search rule definition file. */
164 	const gchar *search_rules;
165 
166 	/* A unique instance is created for each subclass. */
167 	GalViewCollection *view_collection;
168 
169 	/* This is set by the corresponding EShellBackend. */
170 	EShellBackend *shell_backend;
171 
172 	/* Factory Methods */
173 	GtkWidget *	(*new_shell_content)	(EShellView *shell_view);
174 	GtkWidget *	(*new_shell_sidebar)	(EShellView *shell_view);
175 	GtkWidget *	(*new_shell_taskbar)	(EShellView *shell_view);
176 	GtkWidget *	(*new_shell_searchbar)	(EShellView *shell_view);
177 
178 	/* Create, configure and pack a search bar widget. */
179 	GtkWidget *	(*construct_searchbar)	(EShellView *shell_view);
180 	gchar *		(*get_search_name)	(EShellView *shell_view);
181 
182 	/* Signals */
183 	void		(*toggled)		(EShellView *shell_view);
184 	void		(*clear_search)		(EShellView *shell_view);
185 	void		(*custom_search)	(EShellView *shell_view,
186 						 EFilterRule *custom_rule);
187 	void		(*execute_search)	(EShellView *shell_view);
188 	void		(*update_actions)	(EShellView *shell_view);
189 };
190 
191 GType		e_shell_view_get_type		(void);
192 const gchar *	e_shell_view_get_name		(EShellView *shell_view);
193 GtkAction *	e_shell_view_get_action		(EShellView *shell_view);
194 const gchar *	e_shell_view_get_title		(EShellView *shell_view);
195 void		e_shell_view_set_title		(EShellView *shell_view,
196 						 const gchar *title);
197 const gchar *	e_shell_view_get_view_id	(EShellView *shell_view);
198 void		e_shell_view_set_view_id	(EShellView *shell_view,
199 						 const gchar *view_id);
200 GalViewInstance *
201 		e_shell_view_new_view_instance	(EShellView *shell_view,
202 						 const gchar *instance_id);
203 GalViewInstance *
204 		e_shell_view_get_view_instance	(EShellView *shell_view);
205 void		e_shell_view_set_view_instance	(EShellView *shell_view,
206 						 GalViewInstance *view_instance);
207 gboolean	e_shell_view_is_active		(EShellView *shell_view);
208 gint		e_shell_view_get_page_num	(EShellView *shell_view);
209 void		e_shell_view_set_page_num	(EShellView *shell_view,
210 						 gint page_num);
211 GtkWidget *	e_shell_view_get_searchbar	(EShellView *shell_view);
212 gchar *		e_shell_view_get_search_name	(EShellView *shell_view);
213 EFilterRule *	e_shell_view_get_search_rule	(EShellView *shell_view);
214 void		e_shell_view_set_search_rule	(EShellView *shell_view,
215 						 EFilterRule *search_rule);
216 gchar *		e_shell_view_get_search_query	(EShellView *shell_view);
217 GtkSizeGroup *	e_shell_view_get_size_group	(EShellView *shell_view);
218 EShellBackend *	e_shell_view_get_shell_backend	(EShellView *shell_view);
219 EShellContent *	e_shell_view_get_shell_content	(EShellView *shell_view);
220 EShellSidebar *	e_shell_view_get_shell_sidebar	(EShellView *shell_view);
221 EShellTaskbar *	e_shell_view_get_shell_taskbar	(EShellView *shell_view);
222 EShellWindow *	e_shell_view_get_shell_window	(EShellView *shell_view);
223 GKeyFile *	e_shell_view_get_state_key_file	(EShellView *shell_view);
224 void		e_shell_view_set_state_dirty	(EShellView *shell_view);
225 void		e_shell_view_save_state_immediately
226 						(EShellView *shell_view);
227 void		e_shell_view_clear_search	(EShellView *shell_view);
228 void		e_shell_view_custom_search	(EShellView *shell_view,
229 						 EFilterRule *custom_rule);
230 void		e_shell_view_execute_search	(EShellView *shell_view);
231 void		e_shell_view_block_execute_search
232 						(EShellView *shell_view);
233 void		e_shell_view_unblock_execute_search
234 						(EShellView *shell_view);
235 gboolean	e_shell_view_is_execute_search_blocked
236 						(EShellView *shell_view);
237 void		e_shell_view_update_actions	(EShellView *shell_view);
238 void		e_shell_view_update_actions_in_idle
239 						(EShellView *shell_view);
240 GtkWidget *	e_shell_view_show_popup_menu	(EShellView *shell_view,
241 						 const gchar *widget_path,
242 						 GdkEvent *button_event);
243 void		e_shell_view_write_source	(EShellView *shell_view,
244 						 ESource *source);
245 void		e_shell_view_remove_source	(EShellView *shell_view,
246 						 ESource *source);
247 void		e_shell_view_remote_delete_source
248 						(EShellView *shell_view,
249 						 ESource *source);
250 
251 EActivity *	e_shell_view_submit_thread_job	(EShellView *shell_view,
252 						 const gchar *description,
253 						 const gchar *alert_ident,
254 						 const gchar *alert_arg_0,
255 						 EAlertSinkThreadJobFunc func,
256 						 gpointer user_data,
257 						 GDestroyNotify free_user_data);
258 
259 G_END_DECLS
260 
261 #endif /* E_SHELL_VIEW_H */
262