• Skip to content
  • Skip to link menu
KDE 4.1 API Reference
  • KDE API Reference
  • API Reference
  • Sitemap
  • Contact Us
 

KDEPrint

KPrinter Class Reference

#include <kprinter.h>

Inheritance diagram for KPrinter:

Inheritance graph
[legend]

List of all members.

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

The central interface class to access the KDE print system.

Author:
Michael Goffioul
See also:
QPrinter, KPrintDialogPage

Definition at line 86 of file kprinter.h.


Public Types

enum  ApplicationType { Dialog = 0x00, StandAlone = 0x01, StandAlonePersistent = 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  PageSelectionType { ApplicationSide = 0x01, SystemSide = 0x02 }
enum  PageSetType { AllPages = 0x00, OddPages = 0x01, EvenPages = 0x02 }
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, CustomSize = QPrinter::Custom
}
enum  StandardPageType { CopiesPage = 0x01, FilesPage = 0x02, CustomPage = 0x10 }

Public Member Functions

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

Static Public Member Functions

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

Protected Member Functions

virtual int devType () const
bool doPreview (const QString &file)
void finishPrinting ()
void init (bool restore=true, QPrinter::PrinterMode m=QPrinter::ScreenResolution)
void loadSettings ()
virtual int metric (PaintDeviceMetric metric) const
virtual QPaintEngine * paintEngine () const
void preparePrinting ()
void reload ()
void saveSettings ()
void setOption (const QString &key, const QString &value, bool broadcast)
void setRealPageSize (DrPageSize *p)
void translateQtOptions ()

Member Enumeration Documentation

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)
Enumerator:
Dialog 
StandAlone 
StandAlonePersistent 

Definition at line 122 of file kprinter.h.

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()
Enumerator:
Collate 
Uncollate 

Definition at line 141 of file kprinter.h.

enum KPrinter::ColorMode

Defines the color mode of the printer.

See also:
QPrinter::ColorMode
Enumerator:
GrayScale 
Color 

Definition at line 148 of file kprinter.h.

enum KPrinter::Orientation

Defines the orientation of the paper.

See also:
QPrinter::Orientation
Enumerator:
Portrait 
Landscape 

Definition at line 153 of file kprinter.h.

enum KPrinter::PageOrder

Defines the page order of the print job.

See also:
QPrinter::PageOrder
Enumerator:
FirstPageFirst 
LastPageFirst 

Definition at line 158 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()
Enumerator:
ApplicationSide 
SystemSide 

Definition at line 112 of file kprinter.h.

enum KPrinter::PageSetType

Defines the page set to print:.

  • AllPages: all pages
  • OddPages: only odd pages
  • EvenPages: only even pages
See also:
pageSet()
Enumerator:
AllPages 
OddPages 
EvenPages 

Definition at line 133 of file kprinter.h.

enum KPrinter::PageSize

Defines the paper size to use.

See also:
QPrinter::PageSize
Enumerator:
A4 
B5 
Letter 
Legal 
Executive 
A0 
A1 
A2 
A3 
A5 
A6 
A7 
A8 
A9 
B0 
B1 
B10 
B2 
B3 
B4 
B6 
B7 
B8 
B9 
C5E 
Comm10E 
DLE 
Folio 
Ledger 
Tabloid 
NPageSize 
CustomSize 

Definition at line 163 of file kprinter.h.

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()
Enumerator:
CopiesPage 
FilesPage 
CustomPage 

Definition at line 98 of file kprinter.h.

Constructor & Destructor Documentation

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

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 276 of file kprinter.cpp.

KPrinter::~KPrinter (  )  [virtual]

Destructor.

This also saves the current KPrinter state for future printing.

Definition at line 282 of file kprinter.cpp.

Member Function Documentation

bool KPrinter::abort (  ) 

See QPrinter::abort().

Definition at line 1125 of file kprinter.cpp.

bool KPrinter::aborted (  )  const

See QPrinter::aborted().

Definition at line 1130 of file kprinter.cpp.

void KPrinter::addDialogPage ( KPrintDialogPage *  _page  )  [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()

Definition at line 408 of file kprinter.cpp.

void KPrinter::addStandardPage ( int  p  )  [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

Definition at line 398 of file kprinter.cpp.

KPrinter::ApplicationType KPrinter::applicationType (  )  [static]

Returns the application type concerning the print dialog.

For internal use only.

Returns:
the type for the current application
See also:
setApplicationType()

Definition at line 428 of file kprinter.cpp.

bool KPrinter::autoConfigure ( const QString &  prname = QString(),
QWidget *  parent = 0 
)

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

Definition at line 794 of file kprinter.cpp.

KPrinter::CollateType KPrinter::collate (  )  const

Returns the collate status of the current KPrinter.

Definition at line 980 of file kprinter.cpp.

KPrinter::ColorMode KPrinter::colorMode (  )  const

See QPrinter::colorMode().

Definition at line 950 of file kprinter.cpp.

QString KPrinter::creator (  )  const

See QPrinter::creator().

Definition at line 930 of file kprinter.cpp.

int KPrinter::currentPage (  )  const

Returns the current page number.

See also:
setCurrentPage()

Definition at line 1031 of file kprinter.cpp.

int KPrinter::devType (  )  const [protected, virtual]

Definition at line 438 of file kprinter.cpp.

QString KPrinter::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

Definition at line 1241 of file kprinter.cpp.

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

Definition at line 1231 of file kprinter.cpp.

QString KPrinter::docName (  )  const

See QPrinter::docName().

Definition at line 920 of file kprinter.cpp.

bool KPrinter::doPreview ( const QString &  file  )  [protected]

Definition at line 558 of file kprinter.cpp.

bool KPrinter::doubleSidedPrinting (  )  const

wrapped method from QPrinter

Definition at line 1303 of file kprinter.cpp.

QString KPrinter::errorMessage (  )  const

Returns the last error message issued by the print system.

Unimplemented yet.

Returns:
the last error message

Definition at line 1202 of file kprinter.cpp.

void KPrinter::finishPrinting (  )  [protected]

Definition at line 594 of file kprinter.cpp.

bool KPrinter::fontEmbeddingEnabled (  )  const

wrapped method from QPrinter

Definition at line 1293 of file kprinter.cpp.

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 1005 of file kprinter.cpp.

bool KPrinter::fullPage (  )  const

See QPrinter::fullPage().

Definition at line 940 of file kprinter.cpp.

KPrinterImpl * KPrinter::implementation (  )  const

For internal use only.

Definition at line 905 of file kprinter.cpp.

void KPrinter::init ( bool  restore = true,
QPrinter::PrinterMode  m = QPrinter::ScreenResolution 
) [protected]

Definition at line 297 of file kprinter.cpp.

void KPrinter::initOptions ( const QMap< QString, QString > &  opts  ) 

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

Definition at line 772 of file kprinter.cpp.

void KPrinter::loadSettings (  )  [protected]

Definition at line 331 of file kprinter.cpp.

void KPrinter::margins ( uint *  top,
uint *  left,
uint *  bottom,
uint *  right 
) const

Definition at line 673 of file kprinter.cpp.

QSize KPrinter::margins (  )  const

See QPrinter::margins().

Definition at line 667 of file kprinter.cpp.

int KPrinter::maxPage (  )  const

See QPrinter::maxPage().

Definition at line 995 of file kprinter.cpp.

int KPrinter::metric ( PaintDeviceMetric  metric  )  const [protected, virtual]

Definition at line 688 of file kprinter.cpp.

int KPrinter::minPage (  )  const

See QPrinter::minPage().

Definition at line 990 of file kprinter.cpp.

bool KPrinter::newPage (  ) 

See QPrinter::newPage().

Definition at line 1094 of file kprinter.cpp.

int KPrinter::numCopies (  )  const

See QPrinter::numCopies().

Definition at line 660 of file kprinter.cpp.

QString KPrinter::option ( const QString &  key  )  const

Starts the add printer wizard.

This utility function allows any application for adding a printer using the KDEPrint powerful wizard.

Parameters:
parent the parent widget for the wizard
Returns:
1: success, 0: cancel, -1: error 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<QString,QString> 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()
See also:
KPrintDialogPage, setOption, options(), setOptions()

Definition at line 910 of file kprinter.cpp.

QMap< QString, QString > KPrinter::options (  )  const

Returns the complete set of print options from the KPrinter object.

For internal use.

Returns:
the option set as a QMap object

Definition at line 1079 of file kprinter.cpp.

KPrinter::Orientation KPrinter::orientation (  )  const

See QPrinter::orientation().

Definition at line 965 of file kprinter.cpp.

QString KPrinter::outputFileName (  )  const

See QPrinter::outputFileName().

Definition at line 1101 of file kprinter.cpp.

QPrinter::OutputFormat KPrinter::outputFormat (  )  const

wrapped method from QPrinter

Definition at line 1268 of file kprinter.cpp.

bool KPrinter::outputToFile (  )  const

See QPrinter::outputToFile().

Definition at line 1111 of file kprinter.cpp.

QList< 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 601 of file kprinter.cpp.

KPrinter::PageOrder KPrinter::pageOrder (  )  const

See QPrinter::pageOrder().

Definition at line 970 of file kprinter.cpp.

QRect KPrinter::pageRect (  )  const

wrapped method from QPrinter

Definition at line 1313 of file kprinter.cpp.

KPrinter::PageSelectionType KPrinter::pageSelection (  )  [static]

Returns the page selection mode of the current application.

Returns:
the page selection mode
See also:
setPageSelection()

Definition at line 418 of file kprinter.cpp.

KPrinter::PageSetType KPrinter::pageSet (  )  const

Returns the page set of the current KPrinter object.

Definition at line 1026 of file kprinter.cpp.

KPrinter::PageSize KPrinter::pageSize (  )  const

See QPrinter::pageSize().

Definition at line 1021 of file kprinter.cpp.