kdeprint Library API Documentation
Overview Class Hierarchy Classes Classes (annotated) Members Namespaces Source Files

KPrinter Class Reference

This class is the main interface to access the KDE print framework. The central interface class to access the KDE print system. More...

#include <kprinter.h>

Inheritance diagram for KPrinter:

Inheritance graph
[legend]
Collaboration diagram for KPrinter:

Collaboration graph
[legend]
List of all members.

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 Member Functions

 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 KDE_DEPRECATED
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
void setMargins (uint top, uint left, uint bottom, uint right)
QValueList< int > pageList () const
void setPreviewOnly (bool on)
bool previewOnly () const
void setResolution (int dpi)
int resolution () const
void setUsePrinterResolution (bool on)
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

Static Public Member Functions

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

Protected Member Functions

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)
void setRealPageSize (DrPageSize *p)
void setOption (const QString &key, const QString &value, bool broadcast)

Protected Attributes

KPrinterPrivate * d

Friends

class KPrinterWrapper
class KPrinterImpl

Detailed Description

This class is the main interface to access the KDE print framework. The central interface class to access the KDE print system.

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 occurrence 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 <kprinter.h>
 #include <qpainter.h>

 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 );
     <do something>
     // 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().

When compiling an application that uses KPrinter, you must link to -lkdeprint, which when using the standard KDE build framework can be done by adding to _LDADD.

Author:
Michael Goffioul
See also:
QPrinter, KPrintDialogPage

Definition at line 87 of file kprinter.h.

Member Enumeration Documentation

enum KPrinter::StandardPageType
 

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()

Definition at line 101 of file kprinter.h.

enum KPrinter::PageSelectionType
 

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()

Definition at line 115 of file kprinter.h.

Referenced by pageSelection().

enum KPrinter::ApplicationType
 

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).

Definition at line 125 of file kprinter.h.

Referenced by applicationType().

enum KPrinter::PageSetType
 

Defines the page set to print:

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

See also:
pageSet()

Definition at line 136 of file kprinter.h.

Referenced by pageSet().

enum KPrinter::CollateType
 

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()

Definition at line 144 of file kprinter.h.

Referenced by collate().

enum KPrinter::ColorMode
 

Defines the color mode of the printer.

See also:
QPrinter::ColorMode

Definition at line 151 of file kprinter.h.

Referenced by colorMode().

enum KPrinter::Orientation
 

Defines the orientation of the paper.

See also:
QPrinter::Orientation

Definition at line 156 of file kprinter.h.

Referenced by orientation().

enum KPrinter::PageOrder
 

Defines the page order of the print job.

See also:
QPrinter::PageOrder

Definition at line 161 of file kprinter.h.

Referenced by pageOrder().

enum KPrinter::PageSize
 

Defines the paper size to use.

See also:
QPrinter::PageSize

Definition at line 166 of file kprinter.h.

Referenced by pageSize().

Constructor & Destructor Documentation

KPrinter::KPrinter (  bool  restore = true,
QPrinter::PrinterMode  m = QPrinter::ScreenResolution
) 
 

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 independent/clean KPrinter object.

Parameters:
restore if true, options will be restored/saved between successive KPrinter objects
m the mode to establish the KPrinter in (see QPrinter::PrinterMode)

Definition at line 123 of file kprinter.cpp.

KPrinter::~KPrinter (   ) 
 

Destructor.

This also saves the current KPrinter state for future printing.

Definition at line 129 of file kprinter.cpp.

Member Function Documentation

bool KPrinter::newPage (   ) 
 

See QPrinter::newPage().

Definition at line 900 of file kprinter.cpp.

bool KPrinter::abort (   ) 
 

See QPrinter::abort().

Definition at line 926 of file kprinter.cpp.

bool KPrinter::aborted (   )  const
 

See QPrinter::aborted(.).

Definition at line 929 of file kprinter.cpp.

bool KPrinter::outputToFile (   )  const
 

See QPrinter::outputToFile().

Definition at line 913 of file kprinter.cpp.

References QString::isEmpty(), and option().

void KPrinter::setOutputToFile (  bool   ) 
 

See QPrinter::setOutputToFile().

Definition at line 916 of file kprinter.cpp.

References setOption().

Referenced by setOutputFileName(), and setPrintProgram().

QString KPrinter::outputFileName (   )  const
 

See QPrinter::outputFileName().

Definition at line 907 of file kprinter.cpp.

References option().

void KPrinter::setOutputFileName (  const QString &   ) 
 

See QPrinter::setOutputFileName().

Definition at line 910 of file kprinter.cpp.

References QString::isEmpty(), setOption(), and setOutputToFile().

QString KPrinter::docName (   )  const
 

See QPrinter::docName().

Definition at line 785 of file kprinter.cpp.

References option().

Referenced by translateQtOptions().

void KPrinter::setDocName (  const QString &   ) 
 

See QPrinter::setDocName().

Definition at line 788 of file kprinter.cpp.

References setOption().

QString KPrinter::creator (   )  const
 

See QPrinter::creator().

Definition at line 791 of file kprinter.cpp.

References option().

Referenced by translateQtOptions().

void KPrinter::setCreator (  const QString &   ) 
 

See QPrinter::setCreator().

Definition at line 794 of file kprinter.cpp.

References setOption().

bool KPrinter::fullPage (   )  const
 

See QPrinter::fullPage().

Definition at line 797 of file kprinter.cpp.

References option().

Referenced by translateQtOptions().

void KPrinter::setFullPage (  bool   ) 
 

See QPrinter::setFullPage().

Definition at line 800 of file kprinter.cpp.

References setOption().

KPrinter::ColorMode KPrinter::colorMode (   )  const
 

See QPrinter::colorMode().

Definition at line 803 of file kprinter.cpp.

References ColorMode, and option().

Referenced by translateQtOptions().

void KPrinter::setColorMode (  ColorMode   ) 
 

See QPrinter::setColorMode().

Definition at line 806 of file kprinter.cpp.

References setOption().

int KPrinter::numCopies (   )  const
 

See QPrinter::numCopies().

Definition at line 537 of file kprinter.cpp.

References option(), and QString::toInt().

Referenced by translateQtOptions().

void KPrinter::setNumCopies (  int  n  ) 
 

See QPrinter::setNumCopies().

Definition at line 809 of file kprinter.cpp.

References setOption().

KPrinter::Orientation KPrinter::orientation (   )  const
 

See QPrinter::orientation().

Definition at line 812 of file kprinter.cpp.

References option(), and Orientation.

Referenced by translateQtOptions().

void KPrinter::setOrientation (  Orientation   ) 
 

See QPrinter::setOrientation().

Definition at line 594 of file kprinter.cpp.

References setOption().

KPrinter::PageOrder KPrinter::pageOrder (   )  const
 

See QPrinter::pageOrder().

Definition at line 815 of file kprinter.cpp.

References option(), and PageOrder.

Referenced by pageList().

void KPrinter::setPageOrder (  PageOrder   ) 
 

See QPrinter::setPageOrder().

Definition at line 818 of file kprinter.cpp.

References setOption().

KPrinter::CollateType KPrinter::collate (   )  const
 

Returns the collate status of the current KPrinter.

Definition at line 821 of file kprinter.cpp.

References CollateType, and option().

void KPrinter::setCollate (  CollateType  type  ) 
 

Sets the collate status for the current KPrinter to type.

Definition at line 824 of file kprinter.cpp.

References setOption().

int KPrinter::minPage (   )  const
 

See QPrinter::minPage().

Definition at line 827 of file kprinter.cpp.

References QString::isEmpty(), option(), and QString::toInt().

Referenced by pageList().

int KPrinter::maxPage (   )  const
 

See QPrinter::maxPage().

Definition at line 830 of file kprinter.cpp.

References QString::isEmpty(), option(), and QString::toInt().

Referenced by pageList().

void KPrinter::setMinMax (  int  ,
int 
) 
 

See QPrinter::setMinMax().

Definition at line 833 of file kprinter.cpp.

References setOption().

int KPrinter::fromPage (   )  const
 

Returns the first page to be printed.

Deprecated:
Applications should use pageList() instead, which takes into account all options: collate, page order, ranges, page set, ...
See also:
pageList()

Definition at line 836 of file kprinter.cpp.

References QString::isEmpty(), option(), and QString::toInt().

int KPrinter::toPage (   )  const
 

Returns the last page to be printed.

Deprecated:
Applications should use pageList() instead, which takes into account all options: collate, page order, ranges, page set, ...
See also:
pageList()

Definition at line 839 of file kprinter.cpp.

References QString::isEmpty(), option(), and QString::toInt().

void KPrinter::setFromTo (  int  ,
int 
) 
 

Sets the first and last page to be printed.

See QPrinter::setFromTo().

Definition at line 842 of file kprinter.cpp.

References setOption().

KPrinter::PageSize KPrinter::pageSize (   )  const
 

See QPrinter::pageSize().

Definition at line 846 of file kprinter.cpp.

References QString::isEmpty(), option(), PageSize, and QString::toInt().

Referenced by translateQtOptions().

void KPrinter::setPageSize (  PageSize   ) 
 

See QPrinter::setPageSize().

Definition at line 609 of file kprinter.cpp.

References setOption().

QString KPrinter::printerName (   )  const
 

See QPrinter::printerName().

Definition at line 858 of file kprinter.cpp.

Referenced by printFiles().

void KPrinter::setPrinterName (  const QString &   ) 
 

See QPrinter::setPrinterName().

Definition at line 861 of file kprinter.cpp.

QString KPrinter::printProgram (   )  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()

Definition at line 864 of file kprinter.cpp.

References option().

void KPrinter::setPrintProgram (  const QString &  cmd  ) 
 

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 in tag)
    See also:
    printProgram()

Definition at line 867 of file kprinter.cpp.

References QString::append(), QString::find(), QString::isNull(), setOption(), and setOutputToFile().

QString KPrinter::printerSelectionOption (   )  const
 

See QPrinter::printerSelectionOption().

Unused.

Definition at line 885 of file kprinter.cpp.

References QString::fromLatin1().

void KPrinter::setPrinterSelectionOption (  const QString &   ) 
 

See QPrinter::setPrinterSelectionOption().

Unused

Definition at line 888 of file kprinter.cpp.

int KPrinter::currentPage (   )  const
 

Returns the current page number.

See also:
setCurrentPage()

Definition at line 852 of file kprinter.cpp.

References QString::isEmpty(), option(), and QString::toInt().

Referenced by pageList().

void KPrinter::setCurrentPage (  int  p = 0  ) 
 

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<int> pages = printer.pageList();
     // print the pages
     ...
   }
 }
Parameters:
p the current page number (starting from 1)

Definition at line 855 of file kprinter.cpp.

References setOption().

KPrinter::PageSetType KPrinter::pageSet (   )  const
 

Returns the page set of the current KPrinter object.

Definition at line 849 of file kprinter.cpp.

References QString::isEmpty(), option(), PageSetType, and QString::toInt().

Referenced by pageList().

bool KPrinter::setup (  QWidget *  parent = 0,
const QString &  caption = QString::null,
bool  forceExpand = false
) 
 

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

Definition at line 219 of file kprinter.cpp.

References autoConfigure(), and QWidget::winId().

QSize KPrinter::margins (   )  const
 

See QPrinter::margins().

Definition at line 544 of file kprinter.cpp.

void KPrinter::setMargins (  QSize  m  ) 
 

Not used yet.

Definition at line 932 of file kprinter.cpp.

References QSize::height(), and QSize::width().

QSize KPrinter::realPageSize (   )  const
 

Returns the page size in dot unit ( 1 dot = 1/72th in ).

This method is intended for internal use, if you want to access actual page size, use a QPaintDeviceMetrics object instead. Note that the size returned by this method does not take resolution into account, and that it can returns invalid size if no page metric was found in the printer driver. DO NOT USE, WILL BE REMOVED.

See also:
setRealPageSize
Deprecated:

Definition at line 947 of file kprinter.cpp.

void KPrinter::setRealPageSize (  QSize  p  ) 
 

DO NOT USE, WILL BE REMOVED.

Deprecated:

Definition at line 980 of file kprinter.cpp.

void KPrinter::setRealDrawableArea (  const QRect &  r  ) 
 

DO NOT USE, WILL BE REMOVED.

Deprecated:

Definition at line 986 of file kprinter.cpp.

QRect KPrinter::realDrawableArea (   )  const
 

DO NOT USE, WILL BE REMOVED.

Deprecated:

Definition at line 992 of file kprinter.cpp.

QValueList< int > KPrinter::pageList (   )  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()

Definition at line 457 of file kprinter.cpp.

References QValueList::append(), QValueList::begin(), QMap::begin(), QValueList::count(), currentPage(), QValueList::end(), QMap::end(), QString::isEmpty(), maxPage(), minPage(), option(), pageOrder(), pageSet(), QValueList::remove(), and QStringList::split().

void KPrinter::setPreviewOnly (  bool  on  ) 
 

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 (independent 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()

Definition at line 1011 of file kprinter.cpp.

bool KPrinter::previewOnly (   )  const
 

Returns the preview-only state for this KPrinter object.

See also:
setPreviewOnly()

Definition at line 1014 of file kprinter.cpp.

void KPrinter::setResolution (  int  dpi  ) 
 

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()

Definition at line 1029 of file kprinter.cpp.

int 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()

Definition at line 1035 of file kprinter.cpp.

Referenced by translateQtOptions().

void KPrinter::setUsePrinterResolution (  bool  on  ) 
 

Define the KPrinter object to use the actual printer resolution.

Under some print systems (CUPS, Foomatic, PostScript printers), it is possible to know the actual resolution that is used by the printer, as selected by the user in the driver settings. If on is true, this KPrinter object will use the actual printer resolution if it is able to extract it. If nothing can be found, the default resolution will be the one defined by the PrinterMode argument used in the KPrinter constructor, or set explicitly by setResolution().

Parameters:
on true if the KPrinter object should use the actual printer resolution
See also:
resolution(), setResolution()

Definition at line 1038 of file kprinter.cpp.

KPrinterImpl * KPrinter::implementation (   )  const
 

For internal use only.

Definition at line 776 of file kprinter.cpp.

bool KPrinter::printFiles (  const QStringList &  files,
bool  removeafter = false,
bool  startviewer = true
) 
 

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 explicitly.

Definition at line 345 of file kprinter.cpp.

References option(), printerName(), and QFile::remove().