Rename Fl_Paged_Device::start_job() to begin_job() and Fl_Paged_Device::start_page() to begin_page().

The new function names begin_job() and begin_page() better match end_job() and end_page() with which
they must be used by pair.
The old names start_job() and start_page() are maintained for API compatibility with FLTK 1.3.x

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

FL/Fl_Device.H

@@ -41,7 +41,7 @@ class Fl_Widget;
  A drawing surface other than the computer's display, is typically used as follows:
  <ol><li> Create \c surface, an object from a particular Fl_Surface_Device derived class (e.g., Fl_Copy_Surface, Fl_Printer).
  <li> Call \c Fl_Surface_Device::push_current(surface); 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()).
+ current drawing surface (not necessary with class Fl_Printer because it is done by Fl_Printer::begin_job()).
  <li> At this point all 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()).

FL/Fl_Paged_Device.H

@@ -105,8 +105,14 @@ public:
   static const page_format page_formats[NO_PAGE_FORMATS];  
   /** \brief The destructor */
   virtual ~Fl_Paged_Device() {};
-  virtual int start_job(int pagecount, int *frompage = NULL, int *topage = NULL);
-  virtual int start_page(void);
+  virtual int begin_job(int pagecount, int *frompage = NULL, int *topage = NULL);
+  /** Synonym of begin_job(int pagecount, int *frompage, int *topage).
+   For API compatibility with FLTK 1.3.x */
+  int start_job(int pagecount, int *frompage = NULL, int *topage = NULL) {return begin_job(pagecount, frompage, topage);}
+  virtual int begin_page(void);
+  /** Synonym of begin_page().
+   For API compatibility with FLTK 1.3.x */
+  int start_page() {return begin_page();}
   virtual void margins(int *left, int *top, int *right, int *bottom);
   virtual void scale(float scale_x, float scale_y = 0.);
   virtual void rotate(float angle);

FL/Fl_PostScript.H

@@ -227,7 +227,7 @@ class Clip {
 
 /**
  To send graphical output to a PostScript file.
- This class is used exactly as the Fl_Printer class except for the start_job() call,
+ This class is used exactly as the Fl_Printer class except for the begin_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 {
@@ -246,7 +246,7 @@ public:
    */
   ~Fl_PostScript_File_Device();
   /** Don't use with this class. */
-  int start_job(int pagecount, int* from, int* to);
+  int begin_job(int pagecount, int* from, int* to);
   /**
    @brief Begins the session where all graphics requests will go to a local PostScript file.
    *
@@ -256,8 +256,14 @@ public:
    @param layout Desired page layout.
    @return 0 if OK, 1 if user cancelled the file dialog, 2 if fopen failed on user-selected output file.
    */
-  int start_job(int pagecount, enum Fl_Paged_Device::Page_Format format = Fl_Paged_Device::A4,
+  int begin_job(int pagecount, enum Fl_Paged_Device::Page_Format format = Fl_Paged_Device::A4,
 		enum Fl_Paged_Device::Page_Layout layout = Fl_Paged_Device::PORTRAIT);
+  /** Synonym of begin_job().
+   For API compatibility with FLTK 1.3.x */
+  int start_job(int pagecount, enum Fl_Paged_Device::Page_Format format = Fl_Paged_Device::A4,
+                enum Fl_Paged_Device::Page_Layout layout = Fl_Paged_Device::PORTRAIT) {
+    return begin_job(pagecount, format, layout);
+  }
   /**
    @brief Begins the session where all graphics requests will go to FILE pointer.
    *
@@ -268,9 +274,16 @@ public:
    @param layout Desired page layout.
    @return always 0.
    */
-  int start_job(FILE *ps_output, int pagecount, enum Fl_Paged_Device::Page_Format format = Fl_Paged_Device::A4,
+  int begin_job(FILE *ps_output, int pagecount, enum Fl_Paged_Device::Page_Format format = Fl_Paged_Device::A4,
 		enum Fl_Paged_Device::Page_Layout layout = Fl_Paged_Device::PORTRAIT);
-  int start_page (void);
+  /** Synonym of begin_job().
+   For API compatibility with FLTK 1.3.x */
+  int start_job(FILE *ps_output, int pagecount, enum Fl_Paged_Device::Page_Format format = Fl_Paged_Device::A4,
+                enum Fl_Paged_Device::Page_Layout layout = Fl_Paged_Device::PORTRAIT) {
+    return begin_job(ps_output, pagecount, format, layout);
+  }
+
+  int begin_page (void);
   int printable_rect(int *w, int *h);
   void margins(int *left, int *top, int *right, int *bottom);
   void origin(int *x, int *y);

FL/Fl_Printer.H

@@ -36,7 +36,7 @@
  <li>Use a series of FLTK graphics commands (e.g., font, text, lines, colors, clip, image) to
  compose a page appropriately shaped for printing. 
  </ul>
- In both cases, begin by start_job(), start_page(), printable_rect() and origin() calls
+ In both cases, begin by begin_job(), begin_page(), printable_rect() and origin() calls
  and finish by end_page() and end_job() calls.
  <p>Example of use: print a widget centered in a page
  \code
@@ -45,8 +45,8 @@
  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();
+ if (printer->begin_job(1) == 0) {
+  printer->begin_page();
   printer->printable_rect(&width, &height);
   fl_color(FL_BLACK);
   fl_line_style(FL_SOLID, 2);
@@ -65,7 +65,7 @@
  <li>Unix/Linux platforms:
  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::start_job() call. This opens a "Printer Properties" window where it's
+ 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.
  <br>Class Fl_RGB_Image prints but loses its transparency if it has one.
@@ -90,8 +90,8 @@ private:
 public:
   /** The constructor */
   Fl_Printer(void);
-  int start_job(int pagecount, int *frompage = NULL, int *topage = NULL);
-  int start_page(void);
+  int begin_job(int pagecount, int *frompage = NULL, int *topage = NULL);
+  int begin_page(void);
   int printable_rect(int *w, int *h);
   void margins(int *left, int *top, int *right, int *bottom);
   void origin(int *x, int *y);

src/Fl_Paged_Device.cxx

@@ -26,23 +26,23 @@
 
 
 /**
- @brief Starts a print job.
+ @brief Begins a print 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
  */
-int Fl_Paged_Device::start_job(int pagecount, int *frompage, int *topage) {return 1;}
+int Fl_Paged_Device::begin_job(int pagecount, int *frompage, int *topage) {return 1;}
 
 /**
- @brief Starts a new printed page
+ @brief Begins a new printed page
 
  The page coordinates are initially in points, i.e., 1/72 inch, 
  and with origin at the top left of the printable page area.
  @return 0 if OK, non-zero if any error
  */
-int Fl_Paged_Device::start_page (void) {return 1;}
+int Fl_Paged_Device::begin_page (void) {return 1;}
 
 /**
  @brief Computes the dimensions of margins that lie between the printable page area and

src/Fl_Printer.cxx

@@ -31,8 +31,8 @@
 Fl_Printer::Fl_Printer(void) {
   printer = NULL;
 }
-int Fl_Printer::start_job(int pagecount, int *frompage, int *topage) {return 1;}
-int Fl_Printer::start_page(void) {return 1;}
+int Fl_Printer::begin_job(int pagecount, int *frompage, int *topage) {return 1;}
+int Fl_Printer::begin_page(void) {return 1;}
 int Fl_Printer::printable_rect(int *w, int *h) {return 1;}
 void Fl_Printer::margins(int *left, int *top, int *right, int *bottom) {}
 void Fl_Printer::origin(int *x, int *y) {}
@@ -68,12 +68,12 @@ const char *Fl_Printer::property_save = NULL;
 const char *Fl_Printer::property_cancel = NULL;
 
 Fl_PostScript_File_Device::Fl_PostScript_File_Device(void) {}
-int Fl_PostScript_File_Device::start_job(int pagecount, int* from, int* to) {return 1;}
-int Fl_PostScript_File_Device::start_job(int pagecount, enum Fl_Paged_Device::Page_Format format,
+int Fl_PostScript_File_Device::begin_job(int pagecount, int* from, int* to) {return 1;}
+int Fl_PostScript_File_Device::begin_job(int pagecount, enum Fl_Paged_Device::Page_Format format,
                                           enum Fl_Paged_Device::Page_Layout layout) {return 1;}
-int Fl_PostScript_File_Device::start_job(FILE *ps_output, int pagecount, enum Fl_Paged_Device::Page_Format format,
+int Fl_PostScript_File_Device::begin_job(FILE *ps_output, int pagecount, enum Fl_Paged_Device::Page_Format format,
               enum Fl_Paged_Device::Page_Layout layout) {return 1;}
-int Fl_PostScript_File_Device::start_page (void) {return 1;}
+int Fl_PostScript_File_Device::begin_page (void) {return 1;}
 int Fl_PostScript_File_Device::printable_rect(int *w, int *h) {return 1;}
 void Fl_PostScript_File_Device::margins(int *left, int *top, int *right, int *bottom) {}
 void Fl_PostScript_File_Device::origin(int *x, int *y) {}
@@ -135,7 +135,7 @@ Fl_Printer::Fl_Printer(void) {
 }
 
 /**
- Starts a print job.
+ Begins a print job.
  Opens a platform-specific dialog window allowing the user to set several options including
  the desired printer and the page orientation. Optionally, the user can also select a range of pages to  be
  printed. This range is returned to the caller that is in charge of sending only these pages 
@@ -146,14 +146,14 @@ Fl_Printer::Fl_Printer(void) {
  @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 occurred or if the user cancelled the print request.
  */
-int Fl_Printer::start_job(int pagecount, int *frompage, int *topage)
+int Fl_Printer::begin_job(int pagecount, int *frompage, int *topage)
 {
-  return printer->start_job(pagecount, frompage, topage);
+  return printer->begin_job(pagecount, frompage, topage);
 }
 
-int Fl_Printer::start_page(void)
+int Fl_Printer::begin_page(void)
 {
-  return printer->start_page();
+  return printer->begin_page();
 }
 
 int Fl_Printer::printable_rect(int *w, int *h)

src/Fl_cocoa.mm

@@ -3809,8 +3809,8 @@ int Fl_Cocoa_Window_Driver::set_cursor(const Fl_RGB_Image *image, int hotx, int
   Fl_Window *win = Fl::first_window();
   if(!win) return;
   if (win->parent()) win = win->top_window();
-  if( printer.start_job(1) ) return;
-  if( printer.start_page() ) return;
+  if( printer.begin_job(1) ) return;
+  if( printer.begin_page() ) return;
   fl_lock_function();
   // scale the printer device so that the window fits on the page
   float scale = 1;

src/Fl_win32.cxx

@@ -2729,11 +2729,11 @@ void printFront(Fl_Widget *o, void *data) {
   if (!win)
     return;
   int w, h;
-  if (printer.start_job(1)) {
+  if (printer.begin_job(1)) {
     o->window()->show();
     return;
   }
-  if (printer.start_page()) {
+  if (printer.begin_page()) {
     o->window()->show();
     return;
   }

src/Fl_x.cxx

@@ -2960,8 +2960,8 @@ void printFront(Fl_Widget *o, void *data)
   Fl_Window *win = Fl::first_window();
   if(!win) return;
   int w, h;
-  if( printer.start_job(1) ) { o->window()->show(); return; }
-  if( printer.start_page() ) { o->window()->show(); return; }
+  if( printer.begin_job(1) ) { o->window()->show(); return; }
+  if( printer.begin_page() ) { o->window()->show(); return; }
   printer.printable_rect(&w,&h);
   // scale the printer device so that the window fits on the page
   float scale = 1;

src/drivers/Cocoa/Fl_Cocoa_Printer_Driver.mm

@@ -16,7 +16,7 @@
 //     http://www.fltk.org/str.php
 //
 
-#include <FL/Fl_Printer.H>
+#include <FL/Fl_Paged_Device.H>
 #include <FL/Fl_Window_Driver.H>
 #include <FL/Fl_Screen_Driver.H>
 #include "../Quartz/Fl_Quartz_Graphics_Driver.H"
@@ -56,8 +56,8 @@ private:
   PMPageFormat    pageFormat;
   PMPrintSettings printSettings;
   Fl_Cocoa_Printer_Driver(void);
-  int start_job(int pagecount, int *frompage = NULL, int *topage = NULL);
-  int start_page (void);
+  int begin_job(int pagecount, int *frompage = NULL, int *topage = NULL);
+  int begin_page (void);
   int printable_rect(int *w, int *h);
   void margins(int *left, int *top, int *right, int *bottom);
   void origin(int *x, int *y);
@@ -91,7 +91,7 @@ Fl_Cocoa_Printer_Driver::~Fl_Cocoa_Printer_Driver(void) {
 }
 
 
-int Fl_Cocoa_Printer_Driver::start_job (int pagecount, int *frompage, int *topage)
+int Fl_Cocoa_Printer_Driver::begin_job (int pagecount, int *frompage, int *topage)
 //printing using a Quartz graphics context
 //returns 0 iff OK
 {
@@ -277,7 +277,7 @@ void Fl_Cocoa_Printer_Driver::untranslate(void)
   CGContextRestoreGState(gc);
 }
 
-int Fl_Cocoa_Printer_Driver::start_page (void)
+int Fl_Cocoa_Printer_Driver::begin_page (void)
 {	
   OSStatus status = PMSessionBeginPageNoDialog(printSession, pageFormat, NULL);
   CGContextRef gc;

src/drivers/Darwin/Fl_Darwin_System_Driver.cxx

@@ -92,7 +92,7 @@ int Fl_Darwin_System_Driver::clocale_printf(FILE *output, const char *format, va
 /* Returns the address of a Carbon function after dynamically loading the Carbon library if needed.
  Supports old Mac OS X versions that may use a couple of Carbon calls:
  GetKeys used by OS X 10.3 or before (in Fl::get_key())
- PMSessionPageSetupDialog and PMSessionPrintDialog used by 10.4 or before (in Fl_Printer::start_job())
+ PMSessionPageSetupDialog and PMSessionPrintDialog used by 10.4 or before (in Fl_Printer::begin_job())
  */
 void *Fl_Darwin_System_Driver::get_carbon_function(const char *function_name) {
   static void *carbon = ::dlopen("/System/Library/Frameworks/Carbon.framework/Carbon", RTLD_LAZY);

src/drivers/Posix/Fl_Posix_Printer_Driver.cxx

@@ -28,7 +28,7 @@
 
 /** Support for printing on the Unix/Linux platform */
 class Fl_Posix_Printer_Driver : public Fl_PostScript_File_Device {
-  virtual int start_job(int pagecount, int *frompage = NULL, int *topage = NULL);
+  virtual int begin_job(int pagecount, int *frompage = NULL, int *topage = NULL);
 };
 
 Fl_Paged_Device* Fl_Paged_Device::newPrinterDriver(void)
@@ -36,8 +36,8 @@ Fl_Paged_Device* Fl_Paged_Device::newPrinterDriver(void)
   return new Fl_Posix_Printer_Driver();
 }
 
-/** Starts a print job. */
-int Fl_Posix_Printer_Driver::start_job(int pages, int *firstpage, int *lastpage) {
+/*    Begins a print job. */
+int Fl_Posix_Printer_Driver::begin_job(int pages, int *firstpage, int *lastpage) {
   enum Fl_Paged_Device::Page_Format format;
   enum Fl_Paged_Device::Page_Layout layout;
   
@@ -112,7 +112,7 @@ int Fl_Posix_Printer_Driver::start_job(int pages, int *firstpage, int *lastpage)
   if (!print_pipe) printer = "<File>";
   
   if (!print_pipe) // fall back to file printing
-    return Fl_PostScript_File_Device::start_job (pages, format, layout);
+    return Fl_PostScript_File_Device::begin_job (pages, format, layout);
   
   // Print: pipe the output into the lp command...
   

src/drivers/PostScript/Fl_PostScript.cxx

@@ -59,7 +59,7 @@ Fl_PostScript_Graphics_Driver *Fl_PostScript_File_Device::driver()
 }
 
 
-int Fl_PostScript_File_Device::start_job (int pagecount, enum Fl_Paged_Device::Page_Format format, 
+int Fl_PostScript_File_Device::begin_job (int pagecount, enum Fl_Paged_Device::Page_Format format,
 					  enum Fl_Paged_Device::Page_Layout layout)
 {
   Fl_Native_File_Chooser fnfc;
@@ -85,7 +85,7 @@ extern "C" {
   }
 }
 
-int Fl_PostScript_File_Device::start_job (FILE *ps_output, int pagecount,
+int Fl_PostScript_File_Device::begin_job (FILE *ps_output, int pagecount,
     enum Fl_Paged_Device::Page_Format format, enum Fl_Paged_Device::Page_Layout layout)
 {
   Fl_PostScript_Graphics_Driver *ps = driver();
@@ -97,7 +97,7 @@ int Fl_PostScript_File_Device::start_job (FILE *ps_output, int pagecount,
   return 0;
 }
 
-int Fl_PostScript_File_Device::start_job(int pagecount, int* from, int* to)
+int Fl_PostScript_File_Device::begin_job(int pagecount, int* from, int* to)
 {
   return 1;
 }
@@ -1429,7 +1429,7 @@ void Fl_PostScript_File_Device::untranslate(void)
   fprintf(driver()->output, "GR GR\n");
 }
 
-int Fl_PostScript_File_Device::start_page (void)
+int Fl_PostScript_File_Device::begin_page (void)
 {
   Fl_PostScript_Graphics_Driver *ps = driver();
   ps->page(ps->page_format_);

src/drivers/WinAPI/Fl_WinAPI_Printer_Driver.cxx

@@ -37,8 +37,8 @@ private:
   int top_margin;
   void absolute_printable_rect(int *x, int *y, int *w, int *h);
   Fl_WinAPI_Printer_Driver(void);
-  int start_job(int pagecount, int *frompage = NULL, int *topage = NULL);
-  int start_page (void);
+  int begin_job(int pagecount, int *frompage = NULL, int *topage = NULL);
+  int begin_page (void);
   int printable_rect(int *w, int *h);
   void margins(int *left, int *top, int *right, int *bottom);
   void origin(int *x, int *y);
@@ -84,7 +84,7 @@ static void WIN_SetupPrinterDeviceContext(HDC prHDC)
 }
 
 
-int Fl_WinAPI_Printer_Driver::start_job (int pagecount, int *frompage, int *topage)
+int Fl_WinAPI_Printer_Driver::begin_job (int pagecount, int *frompage, int *topage)
 // returns 0 iff OK
 {
   if (pagecount == 0) pagecount = 10000;
@@ -214,7 +214,7 @@ int Fl_WinAPI_Printer_Driver::printable_rect(int *w, int *h)
   return 0;
 }
 
-int Fl_WinAPI_Printer_Driver::start_page (void)
+int Fl_WinAPI_Printer_Driver::begin_page (void)
 {
   int  rsult, w, h;