c++-gtk-utils

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

file_print_manager.h
Go to the documentation of this file.
1 /* Copyright (C) 2006 to 2013 Chris Vine
2
3 The library comprised in this file or of which this file is part is
4 distributed by Chris Vine under the GNU Lesser General Public
5 License as follows:
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public License
9 as published by the Free Software Foundation; either version 2.1 of
10 the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License, version 2.1, for more details.
16
17 You should have received a copy of the GNU Lesser General Public
18 License, version 2.1, along with this library (see the file LGPL.TXT
19 which came with this source code package in the c++-gtk-utils
20 sub-directory); if not, write to the Free Software Foundation, Inc.,
21 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22
23 */
24
25 #ifndef CGU_FILE_PRINTMANAGER_H
26 #define CGU_FILE_PRINTMANAGER_H
27
28 #include <string>
29
30 #include <c++-gtk-utils/cgu_config.h>
31
32 #ifdef CGU_USE_GTK
33 #include <gtk/gtk.h>
34 #include <gdk/gdk.h>
35 #if GTK_CHECK_VERSION(2,14,0)
36 #include <gtk/gtkunixprint.h>
37 #else
38 #include <gtk/gtkprintunixdialog.h>
39 #include <gtk/gtkprintjob.h>
40 #include <gtk/gtkprinter.h>
41 #endif
42 #endif
43
44 #include <c++-gtk-utils/window.h>
45 #include <c++-gtk-utils/notifier.h>
46 #include <c++-gtk-utils/mutex.h>
47 #include <c++-gtk-utils/gobj_handle.h>
48 #include <c++-gtk-utils/intrusive_ptr.h>
49 #include <c++-gtk-utils/emitter.h>
50
51
52 namespace Cgu {
53
54 #if defined(DOXYGEN_PARSING) || defined(CGU_USE_GTK)
55
56 /**
57 * @class FilePrintDialog file_print_manager.h c++-gtk-utils/file_print_manager.h
58 * @brief A print dialog class for FilePrintManager.
59 * @sa FilePrintManager
60 *
61 * This class is not compiled into the library if the library is built
62 * with the \--without-gtk configuration option.
63 */
64
65 class FilePrintDialog: public WinBase {
66 protected:
67 /**
68 * Closes the dialog, cleans up and emits the rejected Emitter object.
69 * It will not throw, even if a method connected to the rejected
70 * Emitter object throws (the exception is caught and reported in
71 * order to prevent it trying to propagate through the GTK+ event
72 * system).
73 */
74 virtual void on_delete_event();
75 public:
76 #ifndef DOXYGEN_PARSING
77 // this helper class avoids exposing GObject callbacks with C
78 // linkage to the global namespace
79 class CB;
80 friend class CB;
81 #endif
82
83 /**
84 * The accepted Emitter object emits if the user choses OK in the
85 * print dialog. Emission of accepted by this class will not throw,
86 * even if a method connected to the accepted Emitter object throws
87 * (the exception is caught and reported in order to prevent it trying
88 * to propagate through the GTK+ event system).
89 */
90 Emitter accepted;
91
92 /**
93 * The rejected Emitter object emits if the user choses Cancel in the
94 * print dialog. Emission of rejected by this class will not throw,
95 * even if a method connected to the rejected Emitter object throws
96 * (the exception is caught and reported in order to prevent it trying
97 * to propagate through the GTK+ event system).
98 */
99 Emitter rejected;
100
101 /**
102 * Gets the currently selected printer from the print dialog. It will
103 * not throw. It must be called in the thread in which the main GTK+
104 * event loop runs.
105 * @return The currently selected printer in the print dialog. The
106 * return value is owned by GTK+ - do not unreference it.
107 */
108 GtkPrinter* get_printer() const;
109
110 /**
111 * Gets the print settings from the print dialog. It will not throw.
112 * It must be called in the thread in which the main GTK+ event loop
113 * runs.
114 * @return The currently selected printer in the print dialog.
115 * Ownership is taken of the return value, by GobjHandle.
116 */
117 GobjHandle<GtkPrintSettings> get_settings() const;
118
119 /**
120 * Gets the printer page set-up from the print dialog. It will not
121 * throw. It must be called in the thread in which the main GTK+
122 * event loop runs.
123 * @return The printer page set-up in the print dialog. The return
124 * value is owned by GTK+ - do not unreference it.
125 */
126 GtkPageSetup* get_page_setup() const;
127
128 /**
129 * The constructor will not throw. A FIlePrintDialog object must be
130 * created in the thread in which the main GTK+ event loop runs.
131 * @param parent The parent of the print dialog (NULL may be passed).
132 * @param print_settings The print settings from a previous print job
133 * (if any, NULL may be passed if none).
134 * @param caption Window caption (optional, NULL may be passed).
135 * @param window_icon A pixbuf which will comprise the window icon
136 * (optional, NULL may be passed).
137 */
138 FilePrintDialog(GtkWindow* parent, GtkPrintSettings* print_settings = 0,
139 const char* caption = 0, GdkPixbuf* window_icon = 0);
140
141 /* we inherit glib memory slice functions from WinBase */
142 };
143
144
145 /**
146 * @class FilePrintManager file_print_manager.h c++-gtk-utils/file_print_manager.h
147 * @brief A class to print a file using the GTK+ print system.
148 *
149 * The FilePrintManager class prints a file printable by the print
150 * system (eg lpr or CUPS) using the GTK+ printer interface. All
151 * print systems on Unix-like systems will print Postscript (PS)
152 * files. Some may also print PDF files. To obtain a
153 * FilePrintManager object, call FilePrintManager::create_manager().
154 * FilePrintManager::set_filename() passes the name of the file to be
155 * printed. To print the file, call FilePrintManager::print(). If
156 * FilePrintManager::print() returns true, the FilePrintManager class
157 * will unlink() (ie delete) the file to be printed when it has been
158 * finished with if true is passed as the second argument of
159 * FilePrintManager::set_filename(), even if printing failed.
160 *
161 * Once FilePrintManager::print() has been called, the
162 * FilePrintManager class owns a reference to itself and so manages
163 * its own lifetime - so once that method has been called it doesn't
164 * matter if the IntrusivePtr object returned by
165 * FilePrintManager::create_manager() goes out of scope (however, once
166 * FilePrintManager::print() has been called, the FilePrintManager
167 * object will not be deleted until both printing has completed or
168 * failed AND the IntrusivePtr object returned by
169 * FilePrintManager::create_manager() has gone out of scope or has
170 * been reset()).
171 *
172 * If the print dialog which is displayed on calling
173 * FilePrintManager::print() is to display a window icon, then pass
174 * FilePrintManager::create_manager() a GobjHandle<GdkPixbuf> icon as
175 * the second argument.
176 *
177 * Normally, a user would probably only want to use any one
178 * FilePrintManager object to print a single print job (it has been
179 * designed with that in mind). Nevertheless, if a reference to the
180 * object is kept alive via an active IntrusivePtr object, it can be
181 * used to print more than one print job. However, if that is done it
182 * is not possible to call FilePrintManager::print() or
183 * FilePrintManager::set_filename() until the previous print job (if
184 * any) has been dispatched to the GTK+ print system (or cancelled).
185 * If the FilePrintManager object is not ready because it is in the
186 * middle of handling an earlier print job, then the call to
187 * FilePrintManager::print() or FilePrintManager::set_filename() will
188 * return false; if however the new print job was successfully started
189 * or file name successfully set, they will return true. It is not
190 * necessary to check the return value of these methods for the first
191 * print job despatched by any one FilePrintManager object.
192 *
193 * For printing plain text (say, from a GtkTextBuffer class, or from a
194 * plain text file), see the TextPrintManager class.
195 *
196 * This class is not compiled into the library if the library is built
197 * with the \--without-gtk configuration option.
198 */
199
200 class FilePrintManager: public IntrusiveLockCounter {
201 Thread::Mutex mutex;
202 GtkWindow* parent_p;
203 std::string caption;
204 GobjHandle<GdkPixbuf> window_icon_h;
205 bool manage;
206 std::string filename;
207 FilePrintDialog* dialog_p;
208 Notifier print_notifier;
209 bool ready;
210
211 static GobjHandle<GtkPrintSettings> print_settings_h;
212
213 void show_dialog();
214 void print_file();
215 void print_cancel();
216 void clean_up();
217 // private constructor
218 FilePrintManager() {}
219 public:
220 #ifndef DOXYGEN_PARSING
221 // this helper class avoids exposing GObject callbacks with C
222 // linkage to the global namespace
223 class CB;
224 friend class CB;
225 #endif
226 /**
227 * This class cannot be copied: it is intended to be held by
228 * IntrusivePtr. The copy constructor is deleted.
229 */
230 FilePrintManager(const FilePrintManager&) = delete;
231
232 /**
233 * This class cannot be copied: it is intended to be held by
234 * IntrusivePtr. The assignment operator is deleted.
235 */
236 FilePrintManager& operator=(const FilePrintManager&) = delete;
237
238 /**
239 * Creates a new FilePrintManager object. No GTK+/GDK functions are
240 * called by this method, and it is thread safe provided that, if it
241 * is called in a thread other than the one in which the GTK+ event
242 * loop runs, Cgu::Notifier::init() has previously been called in the
243 * GTK+ event loop thread.
244 * @param parent The parent of the print dialog which will be created
245 * by the FilePrintManager object (optional, NULL may be passed).
246 * @param caption Window caption of the print dialog which will be
247 * created by the FilePrintManager object (optional, an empty string
248 * may be passed).
249 * @param window_icon A pixbuf which will comprise the window icon of
250 * the print dialog which will be created by the FilePrintManager
251 * object (optional, an empty GobjHandle object may be passed).
252 * @exception std::bad_alloc This method might throw std::bad_alloc if
253 * memory is exhausted and the system throws in that case.
254 * @exception Cgu::Thread::MutexError This method might throw
255 * Cgu::Thread::MutexError if initialisation of the contained mutex
256 * fails. (It is often not worth checking for this, as it means
257 * either memory is exhausted or pthread has run out of other
258 * resources to create new mutexes.)
259 * @exception Cgu::PipeError This method might throw Cgu::PipeError if
260 * the contained Notifier object is the first Notifier object in the
261 * program to be constructed and Cgu::Notifier::init() has not
262 * previously been called.
263 */
264 static Cgu::IntrusivePtr<Cgu::FilePrintManager> create_manager(GtkWindow* parent = 0,
265 const std::string& caption = "",
266 const GobjHandle<GdkPixbuf>& window_icon = GobjHandle<GdkPixbuf>(0));
267
268 /**
269 * Sets the filename of the file to be printed. This method is
270 * thread-safe and may be called in any thread. No GTK+/GDK functions
271 * are called.
272 * @param filename The filename of the file to be printed.
273 * @param manage_file If this argument is set to true, then if print()
274 * returns true, after printing succeeds or fails the file being
275 * printed will be deleted.
276 * @return Returns true, unless the same FilePrintManager object is
277 * being used to print more than one print job and when this method is
278 * called it is already printing another print job (in which case it
279 * returns false).
280 * @exception std::bad_alloc This method might throw std::bad_alloc if
281 * memory is exhausted and the system throws in that case.
282 */
283 bool set_filename(const char* filename, bool manage_file = false);
284
285 /**
286 * Prints the file set with set_filename(). This method is
287 * thread-safe and may be called in any thread (it hands off its work
288 * to the main program thread via a Cgu::Notifier object), unless the
289 * program by which it is called calls GTK+ directly in more than one
290 * thread and thus employs gdk_threads_enter()/gdk_threads_leave()
291 * (rather than, say, Cgu::Notifier or Cgu::Callback::post()), in
292 * which case it must be called in the main GUI thread only and
293 * surrounded by gdk_threads_enter()/gdk_threads_leave() if called
294 * otherwise than in a GTK+ signal handler. (The best approach
295 * however is for a program only to address GTK+/GDK in the main
296 * program thread, for which purpose this library provides various
297 * functions and classes for inter-thread communication, such as
298 * Cgu::Notifier and Cgu::Callback::post().)
299 * @return Returns true, unless the same FilePrintManager object is
300 * being used to print more than one print job and when this method is
301 * called it is already printing another print job (in which case it
302 * returns false).
303 * @exception std::bad_alloc This method might throw std::bad_alloc if
304 * memory is exhausted and the system throws in that case, but only if
305 * it is called in the main program thread. Otherwise it will not
306 * throw.
307 */
308 bool print();
309
310 /**
311 * The destructor will not throw. It is thread safe (the
312 * FilePrintManager object may be destroyed in any thread), and does
313 * not call any GTK+/GDK functions.
314 */
315 ~FilePrintManager();
316
317 #ifdef CGU_USE_GLIB_MEMORY_SLICES_NO_COMPAT
318 CGU_GLIB_MEMORY_SLICES_FUNCS
319 #endif
320 };
321
322 #endif // CGU_USE_GTK
323
324 } // namespace Cgu
325
326 #endif // CGU_FILE_PRINTMANAGER_H