1) More detailed Doxygen documentation for classes Fl_Printer, Fl_Surface_Device, Fl_Display_Device

and Fl_Graphics_Driver.
2) Support call of Fl_Printer::start_job(pagecount) with pagecount=0 when the number of pages is unavailable.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@10592 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

FL/Fl_Device.H

@@ -63,7 +63,8 @@ typedef short COORD_T;
 #endif
 
 /**
- \brief All graphical output devices and all graphics systems.
+ All graphical output devices and all graphics systems.
+ This class supports a rudimentary system of run-time type information.
  */
 class FL_EXPORT Fl_Device {
 public:
@@ -94,11 +95,15 @@ public:
 #define FL_MATRIX_STACK_SIZE 32
 /**
  \brief A virtual class subclassed for each graphics driver FLTK uses.
- *
- The virtual methods of this class are those that a graphics driver should implement to
- support all of FLTK drawing functions.
- <br> The public API for drawing operations is functionally presented in \ref drawing and as function lists
- in the \ref fl_drawings and \ref fl_attributes modules. 
+ Typically, FLTK applications do not use directly objects from this class. Rather, they perform
+ drawing operations (e.g., fl_rectf()) that operate on the current drawing surface (see Fl_Surface_Device).
+ Drawing operations are functionally presented in \ref drawing and as function lists
+ in the \ref fl_drawings and \ref fl_attributes modules.
+ 
+ \p The Fl_Graphics_Driver class is of interest if one wants to perform new kinds of drawing operations.
+ An example would be to draw to a PDF file. This would involve creating a new Fl_Graphics_Driver derived class,
+ say, my_PDF_Graphics_Driver. This new class should implement all virtual methods of the Fl_Graphics_Driver class
+ to support all FLTK drawing functions.
   */
 class FL_EXPORT Fl_Graphics_Driver : public Fl_Device {
 public:
@@ -518,7 +523,20 @@ public:
 #endif
 
 /**
- \brief A surface that's susceptible to receive graphical output.
+ \brief A drawing surface that's susceptible to receive graphical output.
+ A drawing surface is typically used as follows:
+ \li Create \c surface, an object from a particular Fl_Surface_Device derived class (e.g., Fl_Copy_Surface, Fl_Printer).
+ \li Memorize what is the current drawing surface with <tt> Fl_Surface_Device *old_current = Fl_Surface_Device::surface();</tt>
+ \li Call \c surface->set_current(); to redirect all graphics requests to \c surface which becomes the new 
+ current drawing surface (not necessary with class Fl_Printer because it is done by Fl_Printer::start_job()).
+ \li At this point any of the \ref fl_drawings (e.g., fl_rect()) or the \ref fl_attributes or \ref drawing_images functions 
+ (e.g., fl_draw_image(), Fl_Image::draw()) operate on the new current drawing surface. 
+ Certain drawing surfaces allow additional ways to draw to them (e.g., Fl_Printer::print_widget(), Fl_Image_Surface::draw()).
+ \li After all drawing requests have been performed, redirect graphics requests back to their previous destination 
+ with \c old_current->set_current();.
+ \li Delete \c surface.
+ 
+ The current drawing surface is initially the computer's display, an instance of the Fl_Display_Device class.
  */
 class FL_EXPORT Fl_Surface_Device : public Fl_Device {
   /** \brief The graphics driver in use by this surface. */
@@ -542,7 +560,9 @@ public:
 };
 
 /**
- \brief A display to which the computer can draw.
+ A display to which the computer can draw.
+ When the program begins running, an Fl_Display_Device instance has been created and made the current drawing surface.
+ There is no need to create any other object of this class.
  */
 class FL_EXPORT Fl_Display_Device : public Fl_Surface_Device {
   static Fl_Display_Device *_display; // the platform display device

FL/Fl_PostScript.H

@@ -210,7 +210,9 @@ class Clip {
 };
 
 /**
- \brief To send graphical output to a PostScript file.
+ To send graphical output to a PostScript file.
+ This class is used exactly as the Fl_Printer class except for the start_job() call,
+ two variants of which are usable and allow to specify what page format and layout are desired.
  */
 class FL_EXPORT Fl_PostScript_File_Device : public Fl_Paged_Device {
 #ifdef __APPLE__

FL/Fl_Printer.H

@@ -117,7 +117,7 @@ public:
 /**
  * \brief OS-independent print support.
  *
- Fl_Printer allows to use all FLTK drawing, color, text, and clip functions, and to have them operate
+ Fl_Printer allows to use all drawing, color, text, image, and clip FLTK functions, and to have them operate
  on printed page(s). There are two main, non exclusive, ways to use it.
  <ul><li>Print any widget (standard, custom, Fl_Window, Fl_Gl_Window) as it appears 
  on screen, with optional translation, scaling and rotation. This is done by calling print_widget(), 
@@ -127,7 +127,29 @@ public:
  </ul>
  In both cases, begin by start_job(), start_page(), printable_rect() and origin() calls
  and finish by end_page() and end_job() calls.
- <p><b>Platform specifics</b>
+ <p>Example of use: print a widget centered in a page
+ \code
+ #include <FL/Fl_Printer.H>
+ #include <FL/fl_draw.H>
+ int width, height;
+ Fl_Widget *widget = ...  // a widget we want printed
+ Fl_Printer *printer = new Fl_Printer();
+ if (printer->start_job(1) == 0) {
+  printer->start_page();
+  printer->printable_rect(&width, &height);
+  fl_color(FL_BLACK);
+  fl_line_style(FL_SOLID, 2);
+  fl_rect(0, 0, width, height);
+  fl_font(FL_COURIER, 12);
+  time_t now; time(&now); fl_draw(ctime(&now), 0, fl_height());
+  printer->origin(width/2, height/2);
+  printer->print_widget(widget, -widget->w()/2, -widget->h()/2);
+  printer->end_page();
+  printer->end_job();
+ }
+ delete printer;
+ \endcode
+ <b>Platform specifics</b>
  <ul>
  <li>Unix/Linux platforms:
  Unless it has been previously changed, the default paper size is A4.

src/Fl_GDI_Printer.cxx

@@ -55,6 +55,7 @@ static void WIN_SetupPrinterDeviceContext(HDC prHDC)
 int Fl_System_Printer::start_job (int pagecount, int *frompage, int *topage)
 // returns 0 iff OK
 {
+  if (pagecount == 0) pagecount = 10000;
   DWORD       commdlgerr;
   DOCINFO     di;
   char        docName [256];

src/Fl_Paged_Device.cxx

@@ -146,7 +146,7 @@ void Fl_Paged_Device::print_window_part(Fl_Window *win, int x, int y, int w, int
 /**
  @brief Starts a print job.
 
- @param[in] pagecount the total number of pages of the job
+ @param[in] pagecount the total number of pages of the job (or 0 if you don't know the number of pages)
  @param[out] frompage if non-null, *frompage is set to the first page the user wants printed
  @param[out] topage if non-null, *topage is set to the last page the user wants printed
  @return 0 if OK, non-zero if any error

src/Fl_PostScript.cxx

@@ -1547,7 +1547,10 @@ void Fl_PostScript_File_Device::end_job (void)
   Fl_Display_Device::display_device()->set_current();
 }
 
+#endif // FL_DOXYGEN
+
 #if ! (defined(__APPLE__) || defined(WIN32) )
+/** Starts a print job. */
 int Fl_PostScript_Printer::start_job(int pages, int *firstpage, int *lastpage) {
   enum Fl_Paged_Device::Page_Format format;
   enum Fl_Paged_Device::Page_Layout layout;
@@ -1645,7 +1648,6 @@ int Fl_PostScript_Printer::start_job(int pages, int *firstpage, int *lastpage) {
 
 #endif // ! (defined(__APPLE__) || defined(WIN32) )
 
-#endif // FL_DOXYGEN
 
 //
 // End of "$Id$".

src/Fl_Quartz_Printer.mm

@@ -80,8 +80,10 @@ int Fl_System_Printer::start_job (int pagecount, int *frompage, int *topage)
     PMGetFirstPage(printSettings, &from32); 
     if (frompage) *frompage = (int)from32;
     PMGetLastPage(printSettings, &to32); 
-    if (topage) *topage = (int)to32;
-    if(topage && *topage > pagecount) *topage = pagecount;
+    if (topage) {
+      *topage = (int)to32;
+      if (*topage > pagecount && pagecount > 0) *topage = pagecount;
+    }
     status = PMSessionBeginCGDocumentNoDialog(printSession, printSettings, pageFormat);//from 10.4
   }
   else