c++-gtk-utils
file_print_manager.h
Go to the documentation of this file.
1 /* Copyright (C) 2006 to 2019 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 
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>
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  * This function is only used where the library is compiled against
75  * GTK-4. Where this library is compiled against GTK-2 or GTK-3, the
76  * on_delete_event() function is used instead.
77  *
78  * Since 2.2.16
79  */
80 #if defined(DOXYGEN_PARSING) || GTK_CHECK_VERSION(3,94,0)
81  virtual void on_close_request();
82 #endif
83 
84 /**
85  * Closes the dialog, cleans up and emits the rejected Emitter object.
86  * It will not throw, even if a method connected to the rejected
87  * Emitter object throws (the exception is caught and reported in
88  * order to prevent it trying to propagate through the GTK event
89  * system).
90  *
91  * This function is only used where the library is compiled against
92  * GTK-2 and GTK-3. Where this library is compiled against GTK-4, the
93  * on_close_request() function is used instead.
94  */
95 #if defined(DOXYGEN_PARSING) || !GTK_CHECK_VERSION(3,94,0)
96  virtual void on_delete_event();
97 #endif
98 
99 public:
100 #ifndef DOXYGEN_PARSING
101  // this helper class avoids exposing GObject callbacks with C
102  // linkage to the global namespace
103  class CB;
104  friend class CB;
105 #endif
106 
107 /**
108  * The accepted Emitter object emits if the user choses OK in the
109  * print dialog. Emission of accepted by this class will not throw,
110  * even if a method connected to the accepted Emitter object throws
111  * (the exception is caught and reported in order to prevent it trying
112  * to propagate through the GTK event system).
113  */
115 
116 /**
117  * The rejected Emitter object emits if the user choses Cancel in the
118  * print dialog. Emission of rejected by this class will not throw,
119  * even if a method connected to the rejected Emitter object throws
120  * (the exception is caught and reported in order to prevent it trying
121  * to propagate through the GTK event system).
122  */
124 
125 /**
126  * Gets the currently selected printer from the print dialog. It will
127  * not throw. It must be called in the thread in which the main GTK
128  * event loop runs.
129  * @return The currently selected printer in the print dialog. The
130  * return value is owned by GTK - do not unreference it.
131  */
132  GtkPrinter* get_printer() const;
133 
134 /**
135  * Gets the print settings from the print dialog. It will not throw.
136  * It must be called in the thread in which the main GTK event loop
137  * runs.
138  * @return The currently selected printer in the print dialog.
139  * Ownership is taken of the return value, by GobjHandle.
140  */
142 
143 /**
144  * Gets the printer page set-up from the print dialog. It will not
145  * throw. It must be called in the thread in which the main GTK
146  * event loop runs.
147  * @return The printer page set-up in the print dialog. The return
148  * value is owned by GTK - do not unreference it.
149  */
150  GtkPageSetup* get_page_setup() const;
151 
152 /**
153  * The constructor will not throw. A FIlePrintDialog object must be
154  * created in the thread in which the main GTK event loop runs.
155  * @param parent The parent of the print dialog (NULL may be passed).
156  * @param print_settings The print settings from a previous print job
157  * (if any, NULL may be passed if none).
158  * @param caption Window caption (optional, NULL may be passed).
159  * @param window_icon An icon which will comprise the window icon
160  * (optional \- NULL or nullptr may be passed). For GTK-2 and GTK-3
161  * this is of type GdkPixbuf*. For GTK-4 this is of type const char*,
162  * representing an icon theme name rather than the icon itself.
163  */
164 #ifdef DOXYGEN_PARSING
165  FilePrintDialog(GtkWindow* parent, GtkPrintSettings* print_settings = 0,
166  const char* caption = 0, GdkPixbuf*/const char* window_icon = 0);
167 #elif GTK_CHECK_VERSION(3,96,0)
168  FilePrintDialog(GtkWindow* parent, GtkPrintSettings* print_settings = 0,
169  const char* caption = 0, const char* window_icon = 0);
170 #else
171  FilePrintDialog(GtkWindow* parent, GtkPrintSettings* print_settings = 0,
172  const char* caption = 0, GdkPixbuf* window_icon = 0);
173 #endif
174 
175  /* we inherit glib memory slice functions from WinBase */
176 };
177 
178 
179 /**
180  * @class FilePrintManager file_print_manager.h c++-gtk-utils/file_print_manager.h
181  * @brief A class to print a file using the GTK print system.
182  *
183  * The FilePrintManager class prints a file printable by the print
184  * system (eg lpr or CUPS) using the GTK printer interface. All
185  * print systems on Unix-like systems will print Postscript (PS)
186  * files. Some may also print PDF files. To obtain a
187  * FilePrintManager object, call FilePrintManager::create_manager().
188  * FilePrintManager::set_filename() passes the name of the file to be
189  * printed. To print the file, call FilePrintManager::print(). If
190  * FilePrintManager::print() returns true, the FilePrintManager class
191  * will unlink() (ie delete) the file to be printed when it has been
192  * finished with if true is passed as the second argument of
193  * FilePrintManager::set_filename(), even if printing failed.
194  *
195  * Once FilePrintManager::print() has been called, the
196  * FilePrintManager class owns a reference to itself and so manages
197  * its own lifetime - so once that method has been called it doesn't
198  * matter if the IntrusivePtr object returned by
199  * FilePrintManager::create_manager() goes out of scope (however, once
200  * FilePrintManager::print() has been called, the FilePrintManager
201  * object will not be deleted until both printing has completed or
202  * failed AND the IntrusivePtr object returned by
203  * FilePrintManager::create_manager() has gone out of scope or has
204  * been reset()).
205  *
206  * If the print dialog which is displayed on calling
207  * FilePrintManager::print() is to display a window icon, then pass
208  * FilePrintManager::create_manager() a GobjHandle<GdkPixbuf> icon as
209  * the second argument.
210  *
211  * Normally, a user would probably only want to use any one
212  * FilePrintManager object to print a single print job (it has been
213  * designed with that in mind). Nevertheless, if a reference to the
214  * object is kept alive via an active IntrusivePtr object, it can be
215  * used to print more than one print job. However, if that is done it
216  * is not possible to call FilePrintManager::print() or
217  * FilePrintManager::set_filename() until the previous print job (if
218  * any) has been dispatched to the GTK print system (or cancelled).
219  * If the FilePrintManager object is not ready because it is in the
220  * middle of handling an earlier print job, then the call to
221  * FilePrintManager::print() or FilePrintManager::set_filename() will
222  * return false; if however the new print job was successfully started
223  * or file name successfully set, they will return true. It is not
224  * necessary to check the return value of these methods for the first
225  * print job despatched by any one FilePrintManager object.
226  *
227  * For printing plain text (say, from a GtkTextBuffer class, or from a
228  * plain text file), see the TextPrintManager class.
229  *
230  * This class is not compiled into the library if the library is built
231  * with the \--without-gtk configuration option.
232  */
233 
235  Thread::Mutex mutex;
236  GtkWindow* parent_p;
237  std::string caption;
238 #if GTK_CHECK_VERSION(3,96,0)
239  std::string window_icon;
240 #else
241  GobjHandle<GdkPixbuf> window_icon;
242 #endif
243  bool manage;
244  std::string filename;
245  FilePrintDialog* dialog_p;
246  Notifier print_notifier;
247  bool ready;
248 
249  static GobjHandle<GtkPrintSettings> print_settings_h;
250 
251  void show_dialog();
252  void print_file();
253  void print_cancel();
254  void clean_up();
255  // private constructor
256  FilePrintManager() {}
257 public:
258 #ifndef DOXYGEN_PARSING
259  // this helper class avoids exposing GObject callbacks with C
260  // linkage to the global namespace
261  class CB;
262  friend class CB;
263 #endif
264 /**
265  * This class cannot be copied: it is intended to be held by
266  * IntrusivePtr. The copy constructor is deleted.
267  */
269 
270 /**
271  * This class cannot be copied: it is intended to be held by
272  * IntrusivePtr. The assignment operator is deleted.
273  */
275 
276 /**
277  * Creates a new FilePrintManager object. No GTK/GDK functions are
278  * called by this method, and it is thread safe provided that, if it
279  * is called in a thread other than the one in which the GTK event
280  * loop runs, Cgu::Notifier::init() has previously been called in the
281  * GTK event loop thread.
282  * @param parent The parent of the print dialog which will be created
283  * by the FilePrintManager object (optional, NULL may be passed).
284  * @param caption Window caption of the print dialog which will be
285  * created by the FilePrintManager object (optional, an empty string
286  * may be passed).
287  * @param window_icon An icon which will comprise the window icon of
288  * the print dialog which will be created by the FilePrintManager
289  * object (optional, an empty GobjHandle object or empty string may be
290  * passed). For GTK-2 and GTK-3 this is of type
291  * GobjHandle<GdkPixbuf>. For GTK-4 this is of type std::string,
292  * representing an icon theme name rather than the icon itself.
293  * @exception std::bad_alloc This method might throw std::bad_alloc if
294  * memory is exhausted and the system throws in that case.
295  * @exception Cgu::Thread::MutexError This method might throw
296  * Cgu::Thread::MutexError if initialisation of the contained mutex
297  * fails. (It is often not worth checking for this, as it means
298  * either memory is exhausted or pthread has run out of other
299  * resources to create new mutexes.)
300  * @exception Cgu::PipeError This method might throw Cgu::PipeError if
301  * the contained Notifier object is the first Notifier object in the
302  * program to be constructed and Cgu::Notifier::init() has not
303  * previously been called.
304  */
305 #ifdef DOXYGEN_PARSING
307  const std::string& caption = "",
308  const GobjHandle<GdkPixbuf>&/const std::string& window_icon = GobjHandle<GdkPixbuf>(0)/"");
309 #elif GTK_CHECK_VERSION(3,96,0)
310  static Cgu::IntrusivePtr<Cgu::FilePrintManager> create_manager(GtkWindow* parent = 0,
311  const std::string& caption = "",
312  const std::string& window_icon = "");
313 #else
314  static Cgu::IntrusivePtr<Cgu::FilePrintManager> create_manager(GtkWindow* parent = 0,
315  const std::string& caption = "",
316  const GobjHandle<GdkPixbuf>& window_icon = GobjHandle<GdkPixbuf>(0));
317 #endif
318 
319 /**
320  * Sets the filename of the file to be printed. This method is
321  * thread-safe and may be called in any thread. No GTK/GDK functions
322  * are called.
323  * @param filename The filename of the file to be printed.
324  * @param manage_file If this argument is set to true, then if print()
325  * returns true, after printing succeeds or fails the file being
326  * printed will be deleted.
327  * @return Returns true, unless the same FilePrintManager object is
328  * being used to print more than one print job and when this method is
329  * called it is already printing another print job (in which case it
330  * returns false).
331  * @exception std::bad_alloc This method might throw std::bad_alloc if
332  * memory is exhausted and the system throws in that case.
333  */
334  bool set_filename(const char* filename, bool manage_file = false);
335 
336 /**
337  * Prints the file set with set_filename(). This method is
338  * thread-safe and may be called in any thread (it hands off its work
339  * to the main program thread via a Cgu::Notifier object), unless the
340  * program by which it is called calls GTK directly in more than one
341  * thread and thus employs gdk_threads_enter()/gdk_threads_leave()
342  * (rather than, say, Cgu::Notifier or Cgu::Callback::post()), in
343  * which case it must be called in the main GUI thread only and
344  * surrounded by gdk_threads_enter()/gdk_threads_leave() if called
345  * otherwise than in a GTK signal handler. (The best approach
346  * however is for a program only to address GTK/GDK in the main
347  * program thread, for which purpose this library provides various
348  * functions and classes for inter-thread communication, such as
349  * Cgu::Notifier and Cgu::Callback::post().)
350  * @return Returns true, unless the same FilePrintManager object is
351  * being used to print more than one print job and when this method is
352  * called it is already printing another print job (in which case it
353  * returns false).
354  * @exception std::bad_alloc This method might throw std::bad_alloc if
355  * memory is exhausted and the system throws in that case, but only if
356  * it is called in the main program thread. Otherwise it will not
357  * throw.
358  */
359  bool print();
360 
361 /**
362  * The destructor will not throw. It is thread safe (the
363  * FilePrintManager object may be destroyed in any thread), and does
364  * not call any GTK/GDK functions.
365  */
367 
368 #ifdef CGU_USE_GLIB_MEMORY_SLICES_NO_COMPAT
370 #endif
371 };
372 
373 #endif // CGU_USE_GTK
374 
375 } // namespace Cgu
376 
377 #endif // CGU_FILE_PRINTMANAGER_H
Cgu::FilePrintDialog::accepted
Emitter accepted
Definition: file_print_manager.h:114
Cgu::FilePrintDialog::on_close_request
virtual void on_close_request()
Cgu::WinBase
This is a class for managing the lifetime of top level widgets.
Definition: window.h:230
Cgu
Definition: application.h:44
Cgu::GobjHandle< GtkPrintSettings >
Cgu::IntrusivePtr
This is a smart pointer for managing objects allocated on freestore which maintain their own referenc...
Definition: intrusive_ptr.h:98
Cgu::FilePrintManager
A class to print a file using the GTK print system.
Definition: file_print_manager.h:234
Cgu::FilePrintDialog::FilePrintDialog
FilePrintDialog(GtkWindow *parent, GtkPrintSettings *print_settings=0, const char *caption=0, GdkPixbuf */const char *window_icon=0)
intrusive_ptr.h
Cgu::Notifier
Provides thread-safe signalling between a worker thread and the main program thread.
Definition: notifier.h:214
gobj_handle.h
Cgu::FilePrintDialog
A print dialog class for FilePrintManager.
Definition: file_print_manager.h:65
Cgu::FilePrintManager::print
bool print()
Cgu::FilePrintDialog::get_settings
GobjHandle< GtkPrintSettings > get_settings() const
notifier.h
This file provides a Notifier class to provide thread-safe signalling between a worker thread and the...
CGU_GLIB_MEMORY_SLICES_FUNCS
#define CGU_GLIB_MEMORY_SLICES_FUNCS
Definition: cgu_config.h:84
Cgu::IntrusiveLockCounter
This is a counter class providing the ref() and unref() functions required by IntrusivePtr,...
Definition: intrusive_ptr.h:349
Cgu::FilePrintDialog::rejected
Emitter rejected
Definition: file_print_manager.h:123
Cgu::FilePrintManager::set_filename
bool set_filename(const char *filename, bool manage_file=false)
mutex.h
Provides wrapper classes for pthread mutexes and condition variables, and scoped locking classes for ...
Cgu::FilePrintManager::FilePrintManager
FilePrintManager(const FilePrintManager &)=delete
window.h
Cgu::EmitterArg
A class to execute callbacks connected to it, with provision for automatic disconnection.
Definition: emitter.h:496
Cgu::FilePrintDialog::get_printer
GtkPrinter * get_printer() const
Cgu::FilePrintDialog::get_page_setup
GtkPageSetup * get_page_setup() const
Cgu::FilePrintManager::create_manager
static Cgu::IntrusivePtr< Cgu::FilePrintManager > create_manager(GtkWindow *parent=0, const std::string &caption="", const GobjHandle< GdkPixbuf > &/const std::string &window_icon=GobjHandle< GdkPixbuf >(0)/"")
emitter.h
This file provides a thread-safe signal/slot mechanism, with automatic disconnection.
Cgu::Thread::Mutex
A wrapper class for pthread mutexes.
Definition: mutex.h:117
Cgu::FilePrintManager::~FilePrintManager
~FilePrintManager()
cgu_config.h
Cgu::FilePrintDialog::on_delete_event
virtual void on_delete_event()
Cgu::FilePrintManager::operator=
FilePrintManager & operator=(const FilePrintManager &)=delete