Add Fl_PostScript_File_Device::close_command(Fl_PostScript_Close_Command cmd)

Also expand Doxygen doc of class Fl_Printer for the X11 platform.

FL/Fl_PostScript.H

@@ -25,7 +25,10 @@
 #include <FL/fl_draw.H>
 #include <stdarg.h>
 
-/** Signature of Fl_PostScript::close_command() functions passed as parameters. */
+/** Signature of functions FLTK may use to close FILE variables after PostScript/EPS output.
+ A non-null return value indicates output error.
+ \see Fl_PostScript_File_Device::close_command() and Fl_EPS_File_Surface::Fl_EPS_File_Surface().
+ */
 extern "C" {
   typedef int (*Fl_PostScript_Close_Command)(FILE *);
 }
@@ -44,6 +47,11 @@ class Fl_PostScript_Graphics_Driver;
  FLTK standard fonts are output using the corresponding PostScript standard fonts.
  The latin alphabet means all unicode characters between U+0020 and U+017F, or, in other words,
  the ASCII, Latin-1 Supplement and Latin Extended-A charts.
+ <br><b>Processing of transparent Fl_RGB_Image objects</b>: Under the X11 + pango platform,
+ these objects are output with their exact transparency. With other platforms, these objects
+ are drawn blended to white color. Class Fl_EPS_File_Surface 's constructor allows to set another
+ background color for blending.
+ <center>Extra characters supported by standard PostScript fonts</center>
  <table>
  <tr> <th>Char</th><th>Codepoint</th><th>Name</th>  <th>Char</th><th>Codepoint</th><th>Name</th> <th>Char</th><th>Codepoint</th><th>Name</th></tr>
  <tr><td>ƒ</td><td>U+0192</td><td>florin</td><td>‚</td><td>U+201A</td><td>quotesinglbase</td><td>™</td><td>U+2122</td><td>trademark</td></tr>
@@ -121,14 +129,16 @@ public:
   void translate(int x, int y);
   void untranslate(void);
   int end_page (void);
-  /** Finishes all PostScript output.
+  /** Completes all PostScript output.
-   This also closes the underlying \p fclose(file()) unless close_command() was used to set another function.
+   This also closes with \p fclose() the underlying file() unless close_command() was used to set another function.
    */
   void end_job(void);
   /** Label of the PostScript file chooser window */
   static const char *file_chooser_title;
   /** Returns the underlying FILE* receiving all PostScript data */
   FILE *file();
+  /** Sets the function end_job() calls to close the file() */
+  void close_command(Fl_PostScript_Close_Command cmd);
 };
 
 /** Encapsulated PostScript drawing surface.

FL/Fl_Printer.H

@@ -59,15 +59,19 @@
  \endcode
  <b>Platform specifics</b>
  <ul>
- <li>Unix/Linux platforms:
+ <li>X11 platforms:
  <ul><li>FLTK expresses all graphics data using (Level 2) PostScript and sends that to the selected printer.
- See class Fl_PostScript_File_Device for a description of how text appears in print.
+ See class Fl_PostScript_File_Device for a description of how text and transparent images appear in print.
+ <li>If the GTK library is available at run-time, class Fl_Print runs GTK's printer dialog which allows to set
+ printer, paper size and orientation.
+ <li>If that library is not avaialble, or if Fl::option(Fl::OPTION_PRINTER_USES_GTK) has been turned off,
+ class Fl_Print runs FLTK's print dialog.
+ <ul>
  <li>Unless it has been previously changed, the default paper size is A4.
  To change that, press the "Properties" button of the "Print" dialog window
  opened by an Fl_Printer::begin_job() call. This opens a "Printer Properties" window where it's
  possible to select the adequate paper size. Finally press the "Save" button therein to assign
  the chosen paper size to the chosen printer for this and all further print operations.
- <li>Class Fl_RGB_Image prints but loses its transparency if it has one.
  <li>Use the static public attributes of this class to set the print dialog to other languages
  than English. For example, the "Printer:" dialog item Fl_Printer::dialog_printer can be set to French with:
  \code
@@ -77,6 +81,7 @@
  <li>Use Fl_PostScript_File_Device::file_chooser_title to customize the title of the file chooser dialog that opens
  when using the "Print To File" option of the print dialog.
  </ul>
+ </ul>
  <li>Windows platform: Transparent Fl_RGB_Image 's don't print with exact transparency on most printers
  (a workaround is to use print_window_part() ).
  Fl_RGB_Image 's don't rotate() well.

src/Fl_Printer.cxx

@@ -81,6 +81,7 @@ void Fl_PostScript_File_Device::untranslate(void) {}
 int Fl_PostScript_File_Device::end_page (void) {return 1;}
 void Fl_PostScript_File_Device::end_job(void) {}
 FILE* Fl_PostScript_File_Device::file() {return NULL;}
+void Fl_PostScript_File_Device::close_command(Fl_PostScript_Close_Command cmd) {}
 Fl_PostScript_File_Device::~Fl_PostScript_File_Device(void) {}
 
 Fl_EPS_File_Surface::Fl_EPS_File_Surface(int width, int height, FILE *eps_output,

src/drivers/PostScript/Fl_PostScript.cxx

@@ -2111,6 +2111,10 @@ void Fl_PostScript_File_Device::end_job (void)
     }
 }
 
+void Fl_PostScript_File_Device::close_command(Fl_PostScript_Close_Command cmd) {
+  driver()->close_command(cmd);
+}
+
 Fl_EPS_File_Surface::Fl_EPS_File_Surface(int width, int height, FILE *eps, Fl_Color background, Fl_PostScript_Close_Command closef) :
         Fl_Widget_Surface(new Fl_PostScript_Graphics_Driver()) {
   Fl_PostScript_Graphics_Driver *ps = driver();