A class to print a file using the GTK+ print system. More...
#include <c++-gtk-utils/file_print_manager.h>
Public Member Functions | |
| bool | set_filename (const char *filename, bool manage_file=false) |
| bool | print () |
| ~FilePrintManager () | |
 Public Member Functions inherited from Cgu::IntrusiveLockCounter | |
| void | ref () |
| void | unref () |
| IntrusiveLockCounter () | |
| virtual | ~IntrusiveLockCounter () |
Static Public Member Functions | |
| static Cgu::IntrusivePtr< Cgu::FilePrintManager > | create_manager (GtkWindow *parent=0, const std::string &caption="", GobjHandle< GdkPixbuf > window_icon=GobjHandle< GdkPixbuf >(0)) |
Detailed Description
A class to print a file using the GTK+ print system.
The FilePrintManager class prints a file printable by the print system (eg lpr or CUPS) using the GTK+ printer interface. All print systems on Unix-like systems will print Postscript (PS) files. Some may also print PDF files. To obtain a FilePrintManager object, call FilePrintManager::create_manager(). FilePrintManager::set_filename() passes the name of the file to be printed. To print the file, call FilePrintManager::print(). If FilePrintManager::print() returns true, the FilePrintManager class will unlink() (ie delete) the file to be printed when it has been finished with if true is passed as the second argument of FilePrintManager::set_filename(), even if printing failed.
Once FilePrintManager::print() has been called, the FilePrintManager class owns a reference to itself and so manages its own lifetime - so once that method has been called it doesn't matter if the IntrusivePtr object returned by FilePrintManager::create_manager() goes out of scope (however, once FilePrintManager::print() has been called, the FilePrintManager object will not be deleted until both printing has completed or failed AND the IntrusivePtr object returned by FilePrintManager::create_manager() has gone out of scope or has been reset()).
If the print dialog which is displayed on calling FilePrintManager::print() is to display a window icon, then pass FilePrintManager::create_manager() a GobjHandle<GdkPixbuf> icon as the second argument.
Normally, a user would probably only want to use any one FilePrintManager object to print a single print job (it has been designed with that in mind). Nevertheless, if a reference to the object is kept alive via an active IntrusivePtr object, it can be used to print more than one print job. However, if that is done it is not possible to call FilePrintManager::print() or FilePrintManager::set_filename() until the previous print job (if any) has been dispatched to the GTK+ print system (or cancelled). If the FilePrintManager object is not ready because it is in the middle of handling an earlier print job, then the call to FilePrintManager::print() or FilePrintManager::set_filename() will return false; if however the new print job was successfully started or file name successfully set, they will return true. It is not necessary to check the return value of these methods for the first print job despatched by any one FilePrintManager object.
For printing plain text (say, from a GtkTextBuffer class, or from a plain text file), see the TextPrintManager class.
This class is not compiled into the library if the library is built with the --without-gtk configuration option.
Constructor & Destructor Documentation
◆ ~FilePrintManager()
| Cgu::FilePrintManager::~FilePrintManager | ( | ) |
The destructor will not throw. It is thread safe (the FilePrintManager object may be destroyed in any thread), and does not call any GTK+/GDK functions.
Member Function Documentation
◆ create_manager()
|
static |
Creates a new FilePrintManager object. No GTK+/GDK functions are called by this method, and it is thread safe provided that, if it is called in a thread other than the one in which the GTK+ event loop runs, Cgu::Notifier::init() has previously been called in the GTK+ event loop thread.
- Parameters
-
parent The parent of the print dialog which will be created by the FilePrintManager object (optional, NULL may be passed). caption Window caption of the print dialog which will be created by the FilePrintManager object (optional, an empty string may be passed). window_icon A pixbuf which will comprise the window icon of the print dialog which will be created by the FilePrintManager object (optional, an empty GobjHandle object may be passed).
- Exceptions
-
std::bad_alloc This method might throw std::bad_alloc if memory is exhausted and the system throws in that case. Cgu::Thread::MutexError This method might throw Cgu::Thread::MutexError if initialisation of the contained mutex fails. (It is often not worth checking for this, as it means either memory is exhausted or pthread has run out of other resources to create new mutexes.) Cgu::PipeError This method might throw Cgu::PipeError if the contained Notifier object is the first Notifier object in the program to be constructed and Cgu::Notifier::init() has not previously been called.
◆ print()
| bool Cgu::FilePrintManager::print | ( | ) |
Prints the file set with set_filename(). This method is thread-safe and may be called in any thread (it hands off its work to the main program thread via a Cgu::Notifier object), unless the program by which it is called calls GTK+ directly in more than one thread and thus employs gdk_threads_enter()/gdk_threads_leave() (rather than, say, Cgu::Notifier or Cgu::Callback::post()), in which case it must be called in the main GUI thread only and surrounded by gdk_threads_enter()/gdk_threads_leave() if called otherwise than in a GTK+ signal handler. (The best approach however is for a program only to address GTK+/GDK in the main program thread, for which purpose this library provides various functions and classes for inter-thread communication, such as Cgu::Notifier and Cgu::Callback::post().)
- Returns
- Returns true, unless the same FilePrintManager object is being used to print more than one print job and when this method is called it is already printing another print job (in which case it returns false).
- Exceptions
-
std::bad_alloc This method might throw std::bad_alloc if memory is exhausted and the system throws in that case, but only if it is called in the main program thread. Otherwise it will not throw.
◆ set_filename()
| bool Cgu::FilePrintManager::set_filename | ( | const char * | filename, |
| bool | manage_file = false |
||
| ) |
Sets the filename of the file to be printed. This method is thread-safe and may be called in any thread. No GTK+/GDK functions are called.
- Parameters
-
filename The filename of the file to be printed. manage_file If this argument is set to true, then if print() returns true, after printing succeeds or fails the file being printed will be deleted.
- Returns
- Returns true, unless the same FilePrintManager object is being used to print more than one print job and when this method is called it is already printing another print job (in which case it returns false).
- Exceptions
-
std::bad_alloc This method might throw std::bad_alloc if memory is exhausted and the system throws in that case.
The documentation for this class was generated from the following file:
