class KPrinter

Public Types

• enum StandardPageType { CopiesPage = 0x01, FilesPage = 0x02, Custom = 0x10 }
• enum PageSelectionType { ApplicationSide = 0x01, SystemSide = 0x02 }
• enum ApplicationType { Dialog = 0x00, StandAlone = 0x01, StandAlonePersistent = 0x02 }
• enum PageSetType { AllPages = 0x00, OddPages = 0x01, EvenPages = 0x02 }
• enum CollateType { Collate = 0x00, Uncollate = 0x01 }
• enum ColorMode { GrayScale = QPrinter::GrayScale, Color = QPrinter::Color }
• enum Orientation { Portrait = QPrinter::Portrait, Landscape = QPrinter::Landscape }
• enum PageOrder { FirstPageFirst = QPrinter::FirstPageFirst, LastPageFirst = QPrinter::LastPageFirst }
• enum PageSize { A4 = QPrinter::A4, B5 = QPrinter::B5, Letter = QPrinter::Letter, Legal = QPrinter::Legal, Executive = QPrinter::Executive, A0 = QPrinter::A0, A1 = QPrinter::A1, A2 = QPrinter::A2, A3 = QPrinter::A3, A5 = QPrinter::A5, A6 = QPrinter::A6, A7 = QPrinter::A7, A8 = QPrinter::A8, A9 = QPrinter::A9, B0 = QPrinter::B0, B1 = QPrinter::B1, B10 = QPrinter::B10, B2 = QPrinter::B2, B3 = QPrinter::B3, B4 = QPrinter::B4, B6 = QPrinter::B6, B7 = QPrinter::B7, B8 = QPrinter::B8, B9 = QPrinter::B9, C5E = QPrinter::C5E, Comm10E = QPrinter::Comm10E, DLE = QPrinter::DLE, Folio = QPrinter::Folio, Ledger = QPrinter::Ledger, Tabloid = QPrinter::Tabloid, NPageSize = QPrinter::NPageSize }

Public Methods

•  KPrinter (bool restore = true, QPrinter::PrinterMode m = QPrinter::ScreenResolution )
•  ~KPrinter ()
• bool  newPage ()
• bool  abort ()
• bool  aborted () const
• bool  outputToFile () const
• void  setOutputToFile (bool)
• QString  outputFileName () const
• void  setOutputFileName (const QString&)
• QString  docName () const
• void  setDocName (const QString&)
• QString  creator () const
• void  setCreator (const QString&)
• bool  fullPage () const
• void  setFullPage (bool)
• ColorMode  colorMode () const
• void  setColorMode (ColorMode)
• int  numCopies () const
• void  setNumCopies (int n)
• Orientation  orientation () const
• void  setOrientation (Orientation)
• PageOrder  pageOrder () const
• void  setPageOrder (PageOrder)
• CollateType  collate () const
• void  setCollate (CollateType type)
• int  minPage () const
• int  maxPage () const
• void  setMinMax (int, int)
• int  fromPage () const
• int  toPage () const
• void  setFromTo (int, int)
• PageSize  pageSize () const
• void  setPageSize (PageSize)
• QString  printerName () const
• void  setPrinterName (const QString&)
• QString  printProgram () const
• void  setPrintProgram (const QString& cmd)
• QString  printerSelectionOption () const
• void  setPrinterSelectionOption (const QString&)
• int  currentPage () const
• void  setCurrentPage (int p = 0)
• PageSetType  pageSet () const
• bool  setup (QWidget *parent = 0, const QString& caption = QString::null, bool forceExpand = false)
• QSize  margins () const
• void  setMargins (QSize m)
• QSize  realPageSize () const
• void  setRealPageSize (QSize p)
• void  setRealDrawableArea ( const QRect& r )
• QRect  realDrawableArea () const
• void  margins ( uint *top, uint *left, uint *bottom, uint *right ) const
• QValueList  pageList () const
• void  setPreviewOnly (bool on)
• bool  previewOnly () const
• void  setResolution (int dpi)
• int  resolution () const
• KPrinterImpl*  implementation () const
• bool  printFiles (const QStringList& files, bool removeafter = false, bool startviewer = true)
• const QString&  option (const QString& key) const
• void  setOption (const QString& key, const QString& value)
• const QMap<QString,QString>&  options () const
• void  setOptions (const QMap<QString,QString>& opts)
• void  initOptions (const QMap<QString,QString>& opts)
• QString  searchName () const
• void  setSearchName (const QString& n)
• QString  errorMessage () const
• void  setErrorMessage (const QString& msg)
• bool  autoConfigure (const QString& prname = QString::null, QWidget *parent = 0)
• void  setDocFileName (const QString& filename)
• QString  docFileName () const
• void  setDocDirectory ( const QString& dir )
• QString  docDirectory () const

Public Static Methods

• static void  addDialogPage (KPrintDialogPage*)
• static void  setPageSelection (PageSelectionType)
• static PageSelectionType  pageSelection ()
• static void  setApplicationType (ApplicationType type)
• static ApplicationType  applicationType ()
• static void  addStandardPage (int p)
• static void  removeStandardPage (int p)

Protected Methods

• virtual bool  cmd (int, QPainter*, QPDevCmdParam*)
• virtual int  metric (int) const
• void  translateQtOptions ()
• void  loadSettings ()
• void  saveSettings ()
• void  preparePrinting ()
• void  finishPrinting ()
• void  reload ()
• void  init (bool restore = true, QPrinter::PrinterMode m = QPrinter::ScreenResolution)
• bool  doPreview (const QString& file)

Protected Members

• KPrinterPrivate *d

Detailed Description

This class is the main interface to access the KDE print framework. It allows KDE applications to easily access the print system, through an interface that is compatible with QPrinter. So that the porting of an existing application should be as easy as replacing any occurence of QPrinter by KPrinter. However applications that explicitly used the QPrintDialog class must be changed to the standard KPrinter way of accessing the print dialog.

Basically, a KDE application will use the KPrinter object as a paint device, and will draw on it using QPainter. In a standard application, the use of the KPrinter class will look like this:

 #include 
 #include 

 void MyClass::doPrint()
 {
   KPrinter printer;

   // do some printer initialization
   printer.setFullPage( true );

   // initialize the printer using the print dialog
   if ( printer.setup( this ) )
   {
     // create a painter to paint on the printer object
     QPainter painter;

     // start painting
     painter.begin( &printer );
     
     // stop painting, this will automatically send the print data to the printer
     painter.end();
   }
 }

The KPrinter interface also allows some more advanced possibilities, like the customization of the print dialog to integrate application specific print options. This is done by subclassing KPrintDialogPage and adding the page using addDialogPage().

See also: QPrinter, KPrintDialogPage

Defines the standard pages available for the print dialog:

• CopiesPage: page and copies selection (included by default)
• FilesPage: file selection (only used by kprinter utility)
• Custom: unused

See also: addStandardPage(), removeStandardPage()

Defines whether the application can perform page selection itself or not. Some print systems (like CUPS) can do page selection, in this case the page selection will be enabled in the print dialog, otherwise it will be disabled. However some applications (word processor) can do page selection themselves, then it will be enabled in the print dialog, whatever the print system used. But such an application has to tell kdeprint about its feature:

• ApplicationSide: the application will do page selection
• SystemSide: page selection will be left to the print system, if available (default)

See also: setPageSelection(), pageSelection()

Defines the type of the application, this affects the GUI of the print dialog:

• Dialog: print dialog used in an application (default)
• StandAlone: print dialog used as a standalone widget
• StandAlonePersistent: print dialog used as standalone widget, but persistent (do not use)

See also: setApplicationType(), applicationType()

Defines the page set to print:

• AllPages: all pages
• OddPages: only odd pages
• EvenPages: only even pages

See also: pageSet()

Defines the collate property of the printer (if supported by the print system):

• Collate: copies collated (1-2-3-..., 1-2-3-...)
• Uncollate: copies uncollated (1-1-..., 2-2-..., 3-3-...)

See also: setCollate(), collate()

Defines the color mode of the printer

See also: QPrinter::ColorMode

Defines the orientation of the paper

See also: QPrinter::Orientation

Defines the page order of the print job

See also: QPrinter::PageOrder

Defines the paper size to use

See also: QPrinter::PageSize

Constructor. This also restores/saves the state from a previous KPrinter object created within the same application run, if restore is true. Setting restore to false may be useful if you want an independant/clean KPrinter object.

Parameters:

restore

if true, options will be restored/saved between successive KPrinter objects

Destructor. This also saves the current KPrinter state for future printing.

See QPrinter::newPage().

See QPrinter::abort().

[const]

See QPrinter::aborted(.)

[const]

See QPrinter::outputToFile().

See QPrinter::setOutputToFile().

[const]

See QPrinter::outputFileName().

See QPrinter::setOutputFileName().

[const]

See QPrinter::docName().

See QPrinter::setDocName().

[const]

See QPrinter::creator().

See QPrinter::setCreator().

[const]

See QPrinter::fullPage().

See QPrinter::setFullPage().

[const]

See QPrinter::colorMode().

See QPrinter::setColorMode().

[const]

See QPrinter::numCopies().

See QPrinter::setNumCopies().

[const]

See QPrinter::orientation().

See QPrinter::setOrientation().

[const]

See QPrinter::pageOrder().

See QPrinter::setPageOrder().

[const]

Returns the collate status of the current KPrinter.

Sets the collate status for the current KPrinter to type.

[const]

See QPrinter::minPage().

[const]

See QPrinter::maxPage().

See QPrinter::setMinMax().

[const]

Returns the first page to be printed. should use pageList() instead, which takes into account all options: collate, page order, ranges, page set, ...

See also: pageList()

[const]

Returns the last page to be printed. should use pageList() instead, which takes into account all options: collate, page order, ranges, page set, ...

See also: pageList()

Sets the first and last page to be printed. See QPrinter::setFromTo().

[const]

See QPrinter::pageSize().

See QPrinter::setPageSize().

[const]

See QPrinter::printerName().

See QPrinter::setPrinterName().

[const]

Returns the print program as set by setPrintProgram() or by the print dialog if a special printer has been selected.

Returns: the print command line

See also: setPrintProgram()

Sets the command line to use when printing. This function is useful when using a KPrinter object without the print dialog, to control what to print and how to do it. The command line may contain the following tags:

• %in : the input file to the print program. It is required and automatically appended at the end of the command line if not present.
• %out : the output file. Use this tag in conjunction with setOutputToFile() and setOutputFileName()
• %psl : the page size in lower case. This may be useful with some programs like gs.

 void createPNGOutputFile(const QString& filename)
 {
   // use a clean KPrinter object
   KPrinter prt(false);

   prt.setOutputToFile( true );
   prt.setOutputFileName( filename );
   prt.setPrintProgram( "gs -sDEVICE=png256 -sPAPERSIZE=%psl -sOutputFile=%out %in" );

   QPainter painter( &prt );
   doPaint( &painter );
 }

Parameters:

cmd	the print command line (containing at least the @p %in tag)

See also: printProgram()

[const]

See QPrinter::printerSelectionOption(). Unused.

See QPrinter::setPrinterSelectionOption(). Unused

[const]

Returns the current page number.

See also: setCurrentPage()

Sets the current page number. This page number will be used if the user selected "current page" in the print dialog. This option will only be enabled if the application does page selection itself and the application has called setCurrentPage() before opening the print dialog:

 MyClass::MyClass()
 {
   // declares my application able to do page selection
   KPrinter::setPageSelection( KPrinter::ApplicationSide );
 }

 void MyClass::doPrint()
 {
   KPrinter printer;

   printer.setCurrentPage( mycurrentpage );
   if ( printer.setup( this ) )
   {
     QValueList pages = printer.pageList();
     // print the pages
     ...
   }
 }

Parameters:

p	the current page number (starting from 1)

[const]

Returns the page set of the current KPrinter object.

Sets up the KPrinter object using the print dialog, returns true if the user clicked OK.

Parameters:

parent	the parent widget to use for the print dialog
caption	the caption to use in the print dialog
forceExpand	force the expansion of the dialog (the show/hide button will be hidden)

Returns: boolean value corresponding to the button clicked by the user

[const]

See QPrinter::margins().

Not used yet.

[const]

Returns the real page size in points. Some print system (like CUPS) allows to customize the page size through printer description files (PPD). The size returned corresponds to this size.

See also: setRealPageSize

Sets the real page size. For internal use only.

Parameters:

p	the page size

See also: realPageSize()

[const]

[const]

[const]

Returns the page list to be printed, correpsonding to the options selected by the user. This takes into account collate, page order, page set, ranges, ... This is useful when the application does page selection itself.

See also: setCurrentPage()

Sets the KPrinter object to preview mode if on is true. In this mode, nothing will be printed but only a preview dialog will be popped up with the single "Close" action. Using this mode, any application can easily implement a preview action:

 void MyClass:doPreview()
 {
   // use a "clean" KPrinter object (independant from previous print jobs),
   // this is not necessary, it depends on the application
   KPrinter prt( false );
   prt.setPreviewOnly( true );

   QPainter painter( &prt );
   doPrint( &painter );
 }

Parameters:

on	the preview-only state

See also: previewOnly()

[const]

Returns the preview-only state for this KPrinter object.

See also: setPreviewOnly()

Set the resolution of the current KPrinter object. The resolution is given in DPI. This resolution mainly affects the accuracy for object positionning on the paint device, and does not influence the real resolution that will be used by the printer (this should be set in the driver settings). The resolution is usually defined in the constructor.

Parameters:

dpi	the resolution in DPI

See also: KPrinter(), resolution()

[const]

Resturns the resolution of the current KPrinter object. The resolution is given in DPI.

Returns: resolution in DPI

See also: setResolution(), KPrinter()

[const]

For internal use only.

Prints the files given in argument. This will first filter the files accorsing to the filtering options selected by the user in the print dialog, then send the filtered files to the printer with the print options selected. This function is called automatically when calling QPainter::end() for a painter object constructed on KPrinter. In normal use, you don't need this use this function explicitely.

[static]

Adds a customized page to the print dialog. The pages will appear in a tab widget in the bottom half of the dialog, along with the standard "Copies" page. The page must be created and added each time you want open a print dialog with setup(). If you correctly reimplemented KPrintDialogPage::setOptions(), the settings will be restored from call to call, you don't have to worry about state saving/restoration.

Parameters:

_page

the page to add

See also: KPrintDialogPage::setOptions()

[static]

Sets the page selection mode of the application. If needed, call this method somewhere at the beginning of your code. The default value is SystemSide.

Parameters:

_mode

the mode for the application

See also: pageSelection()

[static]

Returns the page selection mode of the current application.

Returns: the page selection mode

See also: setPageSelection()

[static]

Sets the application type concerning the print dialog. You probably don't want to use it. For internal use only.

Parameters:

type	the type for this application

See also: applicationType()

[static]

Returns the application type concerning the print dialog. For internal use only.

Returns: the type for the current application

See also: setApplicationType()

[static]

Adds a standard page to the print dialog. This is not useful yet as there's only one standard page defines CopiesPage.

Parameters:

p	the page identifier

See also: StandardPageType

[static]

Removes a standard page from the print dialog. If your application doesn't want a standard page in the dialog, simply call this method with the correct identifier. By default, the print dialog includes the CopiesPage page.

Parameters:

p	the page identifier

See also: StandardPageType

[const]

The KPrinter object stores all its settings in an internal QMap structure on QString. This allows to store any property. This method allows an application to access any print option from the KPrinter object, using the option name. For example if your application add a customized page to the print dialog, this page will saves its settings into the KPrinter object using this QMap structure. After showing the print dialog, your application can then access these options using this method. The custom option name should follow the form "kde-appname-optionname".

 void MyClass::doPrint()
 {
   KPrinter prt;

   // add my custom page
   prt.addDialogPage( new MyDialogPage() );

   // open print dialog
   if ( prt.setup( this ) )
   {
      QString fntname = prt.option( "kde-myapp-fontname" );
      ...
      do_something;
      ...
   }
 }

Parameters:

key	the option name (key)

Returns: the option value correponding to the key, or QString::null

See also: KPrintDialogPage, setOption, options(), setOptions()

Adds or modifies an option in the KPrinter object. You probably don't need to use this function explicitely. This will be done implicitely for example when reimplementing KPrintDialogPage::getOptions().

Parameters:

key	the option name
value	the option value

See also: KPrintDialogPage, KPrintDialogPage

[const]

Returns the complete set of print options from the KPrinter object. For internal use.

Returns: the option set as a QMap object

Sets the option set in one operation. This method has some side effects like merging the internal map with the one given in argument, but only for option in the form "kde-...". For internal use only.

Parameters:

opts	the option set to be merged in the KPrinter object

For internal use only. Does a similar job as setOption(), except that all possible internal printers are initialized with the option if it has the form "kde-...".

Parameters:

opts	the option set

See also: setOptions()

[const]

Returns the search name of the printer selected by the user. Each printer is identified by a unique name. This method is mainly used for state restoration. For internal use.

Returns: the unique printer search name

See also: setSearchName

Sets the search name of the KPrinter object. For internal use.

Parameters:

the	unique printer search name

See also: searchName()

[const]

Returns the last error message issued by the print system. Unimplemented yet.

Returns: the last error message

Sets the last error message. For internal use.

Parameters:

msg	the error message

Configure the KPrinter object to be used with the printer named prname. After the call, the KPrinter object can be used without the need to call the print dialog. If prname is empty, then the KPrinter object is configured for the default printer. If prname corresponds to a pseudo-printer which needs an output file, a file dialog will be used. In that case, providing a parent widget for that dialog in parent may be useful.

Parameters:

prname	the name of the printer for which the KPrinter object has to be configured
parent	a parent widget, used a parent for a file dialog

Returns: boolean flag: if false, the KPrinter has not been correctly set up, and the application shouldn't use it to print. This may happen if the printer named prname has not been found or if the user clicked "Cancel" in the file dialog.

See also: setup()

Set the default document filename. This filename will be used as the default basename for the output file, instead of the default "print". For exmaple, by using setDocFileName("my_document"), the default output file will be $HOME/my_document.ps.

Parameters:

filename

the default document basename to use

See also: docFileName()

[const]

Get the default document filename, that is the default basename used for the output file.

Returns: the default document basename

See also: setDocFileName()

Set the default document directory. This directory will be used as the default location for any output file. If not set, $HOME directory is used instead.

Parameters:

dir	the new default output directory

See also: docDirectory()

[const]

Get the default document directory, that is the directory used for any output file. By default, it is the $HOME directory.

Returns: the default output directory

See also: setDocDirectory

[protected virtual]

Reimplemented from QPaintDevice.

[protected const virtual]

[protected]

[protected]

[protected]

[protected]

[protected]

[protected]

Reimplemented from KPReloadObject.

[protected]

[protected]

[protected]

• Author: Michael Goffioul
• Generated: caleb on tcdevel on Tue Jan 28 12:54:25 2003, using kdoc $.