c++-gtk-utils
Public Member Functions | Static Public Member Functions | List of all members
Cgu::FilePrintManager Class Reference

A class to print a file using the GTK print system. More...

#include <c++-gtk-utils/file_print_manager.h>

Inheritance diagram for Cgu::FilePrintManager:
Cgu::IntrusiveLockCounter

Public Member Functions

 FilePrintManager (const FilePrintManager &)=delete
 
FilePrintManageroperator= (const FilePrintManager &)=delete
 
bool set_filename (const char *filename, bool manage_file=false)
 
bool print ()
 
 ~FilePrintManager ()
 
- Public Member Functions inherited from Cgu::IntrusiveLockCounter
 IntrusiveLockCounter (const IntrusiveLockCounter &)=delete
 
IntrusiveLockCounteroperator= (const IntrusiveLockCounter &)=delete
 
void ref () noexcept
 
void unref ()
 
 IntrusiveLockCounter ()
 
virtual ~IntrusiveLockCounter ()
 

Static Public Member Functions

static Cgu::IntrusivePtr< Cgu::FilePrintManagercreate_manager (GtkWindow *parent=0, const std::string &caption="", const GobjHandle< GdkPixbuf > &/const std::string &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 ( const FilePrintManager )
delete

This class cannot be copied: it is intended to be held by IntrusivePtr. The copy constructor is deleted.

◆ ~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 Cgu::IntrusivePtr<Cgu::FilePrintManager> Cgu::FilePrintManager::create_manager ( GtkWindow *  parent = 0,
const std::string &  caption = "",
const GobjHandle< GdkPixbuf > &/const std::string &  window_icon = GobjHandle< GdkPixbuf >(0)/"" 
)
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
parentThe parent of the print dialog which will be created by the FilePrintManager object (optional, NULL may be passed).
captionWindow caption of the print dialog which will be created by the FilePrintManager object (optional, an empty string may be passed).
window_iconAn icon which will comprise the window icon of the print dialog which will be created by the FilePrintManager object (optional, an empty GobjHandle object or empty string may be passed). For GTK-2 and GTK-3 this is of type GobjHandle<GdkPixbuf>. For GTK-4 this is of type std::string, representing an icon theme name rather than the icon itself.
Exceptions
std::bad_allocThis method might throw std::bad_alloc if memory is exhausted and the system throws in that case.
Cgu::Thread::MutexErrorThis 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::PipeErrorThis 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.

◆ operator=()

FilePrintManager& Cgu::FilePrintManager::operator= ( const FilePrintManager )
delete

This class cannot be copied: it is intended to be held by IntrusivePtr. The assignment operator is deleted.

◆ 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_allocThis 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
filenameThe filename of the file to be printed.
manage_fileIf 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_allocThis 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: