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:

## Public Member Functions

| FilePrintManager (const FilePrintManager &)=delete
FilePrintManager & | operator= (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
IntrusiveLockCounter & | operator= (const IntrusiveLockCounter &)=delete
void | ref () noexcept
void | unref ()
| IntrusiveLockCounter ()
virtual | ~IntrusiveLockCounter ()

## Static Public Member Functions

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)/"")

## 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

  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 | An 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_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.

## 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_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:

- file_print_manager.h