include/pwlib/pcanvas.h

   1 /*
   2  * pcanvas.h
   3  *
   4  * Printer canvas.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.17  2001/05/22 12:49:33  robertj
  31  * Did some seriously wierd rewrite of platform headers to eliminate the
  32  *   stupid GNU compiler warning about braces not matching.
  33  *
  34  * Revision 1.16  1999/03/10 03:49:52  robertj
  35  * More documentation adjustments.
  36  *
  37  * Revision 1.15  1999/03/09 08:01:49  robertj
  38  * Changed comments for doc++ support (more to come).
  39  *
  40  * Revision 1.14  1999/02/16 08:08:46  robertj
  41  * MSVC 6.0 compatibility changes.
  42  *
  43  * Revision 1.13  1998/09/23 06:24:38  robertj
  44  * Added open source copyright license.
  45  *
  46  * Revision 1.12  1998/03/20 03:14:40  robertj
  47  * Added function to get physical bounds of canvas. Allows to scale drawing.
  48  *
  49  * Revision 1.11  1995/06/17 11:12:51  robertj
  50  * Documentation update.
  51  *
  52  * Revision 1.10  1995/03/14 12:41:59  robertj
  53  * Updated documentation to use HTML codes.
  54  *
  55  * Revision 1.9  1994/12/21  11:53:20  robertj
  56  * Documentation and variable normalisation.
  57  *
  58  * Revision 1.8  1994/08/23  11:32:52  robertj
  59  * Oops
  60  *
  61  * Revision 1.7  1994/08/22  00:46:48  robertj
  62  * Added pragma fro GNU C++ compiler.
  63  *
  64  * Revision 1.6  1994/06/25  11:55:15  robertj
  65  * Unix version synchronisation.
  66  *
  67  * Revision 1.5  1994/03/07  07:38:19  robertj
  68  * Major enhancementsacross the board.
  69  *
  70  * Revision 1.4  1994/01/03  04:42:23  robertj
  71  * Mass changes to common container classes and interactors etc etc etc.
  72  *
  73  * Revision 1.3  1993/08/21  01:50:33  robertj
  74  * Made Clone() function optional, default will assert if called.
  75  *
  76  * Revision 1.2  1993/07/14  12:49:16  robertj
  77  * Fixed RCS keywords.
  78  *
  79  */
  80
  81
  82 #define _PPRINTCANVAS
  83
  84 #ifdef __GNUC__
  85 #pragma interface
  86 #endif
  87
  88
  89 /**A canvas that will go to a printer. Outputing to a printer consists of
  90    drawing to an area that represents a printed page. The application then
  91    completes each page and creates a new blank page to be drawn to.
  92
  93   *********************************** NOTE ***********************************
  94   On Some platforms, canvases are a limited resource. Do NOT create and leave
  95   them around for long periods. As soon as it is not required till the next
  96   user event, destroy it!
  97   ****************************************************************************
  98  */
  99 class PPrintCanvas : public PCanvas
 100 {
 101   PCLASSINFO(PPrintCanvas, PCanvas);
 102
 103   public:
 104    /**Create a canvas that will go to the default printer device using its
 105        default printer setup.
 106      */
 107     PPrintCanvas(
 108       const PString & job
 109      /**Arbitrary name to identify to print job on some platforms, eg an
 110          identifier in the print queue for MS-Windows.
 111        */
 112     );
 113
 114    /**Create a canvas that will go to the specified printer device using its
 115        default printer setup.
 116      */
 117     PPrintCanvas(
 118       const PString & job,
 119      /**Arbitrary name to identify to print job on some platforms, eg an
 120          identifier in the print queue for MS-Windows.
 121        */
 122       const PString & printer,
 123      /**Printer type name for printing to, eg "Postscript". The possible
 124          values for this parameter are platform dependent and would rarely be
 125          set explicitly by the application.
 126        */
 127       const PString & device
 128      /**Output device or queue for printer, eg "LPT1" for MS-Windows or
 129          "PS_LASER" for Unix. The possible values for this parameter are
 130          platform dependent and would rarely be set explicitly by the
 131          application.
 132        */
 133     );
 134
 135    /**Create a canvas that will go to the specified printer device using the
 136        specified printer setup.
 137      */
 138     PPrintCanvas(
 139       const PString & job,
 140      /**Arbitrary name to identify to print job on some platforms, eg an
 141          identifier in the print queue for MS-Windows.
 142        */
 143       const PPrintInfo & info
 144      /**Printer specification describing all optional information on the
 145          selected printer. This would typically be obtained via the
 146          \Ref{PPrintJobDialog} class.
 147        */
 148     );
 149
 150     /** Destroy the printer canvas, freing all resource used. */
 151     virtual ~PPrintCanvas();
 152
 153
 154   /**@name New functions for class */
 155    /**Begin output to a new page. This will close and queue the current page
 156        and provide a clean new page for further drawing operations.
 157
 158        @return
 159        TRUE if previous page was successfully queued and the new page is ready
 160        to be drawn to.
 161      */
 162     BOOL NewPage();
 163
 164    /**Set the drawable area of the printer page. This can limit the amount of
 165        the page specified in the printer setup that is actually used for the
 166        printing. This can be usefull for output code that scales to the
 167        \Ref{GetDrawingBounds()} function, but it is not desired that it scale
 168        to the full page size.
 169      */
 170     void SetDrawingBounds(
 171       const PRect & bounds    /// New bounds for canvas.
 172     );
 173
 174    /**Get the current printer setup information for the print canvas.
 175
 176        @return
 177        reference to the current print info.
 178      */
 179     const PPrintInfo & GetPrintInfo() const;
 180
 181    /**This allows the print parameters to be changed in mid job. Note that
 182        this can only occur between pages, so there is an implicit
 183        \Ref{NewPage()} call in this function.
 184
 185        Not all items in the PPrintInfo can be changed in the middle of the
 186        print job, eg changing the printer type from "Postscript" to "HPPCL".
 187        These changes are ignored by the ChangePrintInfo() function.
 188      */
 189     void ChangePrintInfo(
 190       const PPrintInfo & info   /// New print information.
 191     );
 192
 193
 194   protected:
 195     // New functions for class
 196     void Construct();
 197       // Internal function for common constructor code.
 198
 199
 200     /**@name Member fields */
 201    /**Arbitrary name to identify to print job on some platforms, eg an
 202        identifier in the print queue for MS-Windows.
 203      */
 204     PString jobName;
 205
 206    /**Printer specification describing all optional information on the
 207        selected printer. This would typically be obtained via the
 208        \Ref{PPrintJobDialog} class.
 209      */
 210     PPrintInfo printInfo;
 211
 212
 213 // Include platform dependent part of class
 214 #include <pwlib/pcanvas.h>
 215 };
 216
 217
 218 // End Of File ///////////////////////////////////////////////////////////////