|
|
/* * This file is part of the KDE libraries * Copyright (c) 2001 Michael Goffioul <goffioul@imec.be> * * $Id: kprinter.h,v 1.13 2001/07/27 18:15:11 porten Exp $ * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License version 2 as published by the Free Software Foundation. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; see the file COPYING.LIB. If not, write to * the Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. **/ #ifndef KPRINTER_H #define KPRINTER_H #include <qpaintdevice.h> #include <qprinter.h> #include <qmap.h> #include <qstring.h> #include <qstringlist.h> #include <qvaluelist.h> #include <kdeprint/kpreloadobject.h> class KPrinter; //************************************************************************************** // KPrinterWrapper class //************************************************************************************** /** * A @ref QPrinter wrapper to access protected functions from @ref KPrinter. For internal use only. * Do not use. * * @short A @ref QPrinter wrapper to access protected functions from @ref KPrinter */ class KPrinterWrapper : public QPrinter { friend class KPrinter; public: KPrinterWrapper(KPrinter*); ~KPrinterWrapper(); protected: virtual bool cmd(int, QPainter*, QPDevCmdParam*); virtual int metric(int) const; int qprinterMetric(int) const; private: KPrinter *m_printer; }; //************************************************************************************** class KPrinterImpl; class KPrintDialogPage; class KPrinterPrivate; /** * 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 @ref QPrinter. So that the porting of an existing application should be as easy as * replacing any occurence of @ref QPrinter by KPrinter. However applications that explicitely * used the @ref 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 @ref QPainter. In a standard application, the use of the KPrinter class will * look like this: * <pre> * #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(); * } * } * </pre> * * 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 * @ref KPrintDialogPage and adding the page using @ref addDialogPage(). * * @short The central interface class to access the KDE print system. * @author Michael Goffioul * @see QPrinter, KPrintDialogPage */ class KPrinter : public QPaintDevice, public KPReloadObject { friend class KPrinterWrapper; friend class KPrinterImpl; public: // Print global settings (set via static functions) /** * Defines the standard pages available for the print dialog: * @li @p CopiesPage: page and copies selection (included by default) * @li @p Custom: unused * * @see addStandardPage(), removeStandardPage() */ enum StandardPageType { CopiesPage = 0x01, Custom = 0x10 }; /** * Defines wether 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: * @li @p ApplicationSide: the application will do page selection * @li @p SystemSide: page selection will be left to the print system, if available (default) * * @see setPageSelection(), pageSelection() */ enum PageSelectionType { ApplicationSide = 0x01, SystemSide = 0x02 }; /** * Defines the type of the application, this affects the GUI of the print dialog: * @li @p Dialog: print dialog used in an application (default) * @li @p StandAlone: print dialog used as a standalone widget * * @internal * @see setApplicationType(), applicationType() */ enum ApplicationType { Dialog = 0x00, StandAlone = 0x01 }; // QPrinter extension /** * Defines the page set to print: * @li @p AllPages: all pages * @li @p OddPages: only odd pages * @li @p EvenPages: only even pages * * @see pageSet() */ enum PageSetType { AllPages = 0x00, OddPages = 0x01, EvenPages = 0x02 }; /** * Defines the collate property of the printer (if supported by the print system): * @li @p Collate: copies collated (1-2-3-..., 1-2-3-...) * @li @p Uncollate: copies uncollated (1-1-..., 2-2-..., 3-3-...) * * @see setCollate(), collate() */ enum CollateType { Collate = 0x00, Uncollate = 0x01 }; // from QPrinter class /** * Defines the color mode of the printer * @see QPrinter::ColorMode */ enum ColorMode { GrayScale = QPrinter::GrayScale, Color = QPrinter::Color }; /** * Defines the orientation of the paper * @see QPrinter::Orientation */ enum Orientation { Portrait = QPrinter::Portrait, Landscape = QPrinter::Landscape }; /** * Defines the page order of the print job * @see QPrinter::PageOrder */ enum PageOrder { FirstPageFirst = QPrinter::FirstPageFirst, LastPageFirst = QPrinter::LastPageFirst }; /** * Defines the paper size to use * @see QPrinter::PageSize */ 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 }; // constructors / destructor /** * Contructor. This also restores/saves the state from a previous KPrinter object created within * the same application run. */ KPrinter(); /** * Contructor. This also restores/saves the state from a previous KPrinter object created within * the same application run, if @p restore is true. Setting @p restore to false may * be useful if you want an independant/clean KPrinter object. * @param restore if true, options will be restored/saved between successive KPrinter objects */ KPrinter(bool restore); // BIC: merge with previous contructor /** * Destructor. This also saves the current KPrinter state for future printing */ ~KPrinter(); // QPrinter interface (+ some extensions) /** * See @ref QPrinter::newPage() */ bool newPage(); /** * See @ref QPrinter::abort() */ bool abort(); /** * See @ref QPrinter::aborted() */ bool aborted() const; /** * See @ref QPrinter::outputToFile() */ bool outputToFile() const; /** * See @ref QPrinter::setOutputToFile() */ void setOutputToFile(bool); /** * See @ref QPrinter::outputFileName() */ QString outputFileName() const; /** * See @ref QPrinter::setOutputFileName() */ void setOutputFileName(const QString&); /** * See @ref QPrinter::docName() */ QString docName() const; /** * See @ref QPrinter::setDocName() */ void setDocName(const QString&); /** * See @ref QPrinter::creator() */ QString creator() const; /** * See @ref QPrinter::setCreator() */ void setCreator(const QString&); /** * See @ref QPrinter::fullPage() */ bool fullPage() const; /** * See @ref QPrinter::setFullPage() */ void setFullPage(bool); /** * See @ref QPrinter::colorMode() */ ColorMode colorMode() const; /** * See @ref QPrinter::setColorMode() */ void setColorMode(ColorMode); /** * See @ref QPrinter::numCopies() */ int numCopies() const; /** * See @ref QPrinter::setNumCopies() */ void setNumCopies(int n); /** * See @ref QPrinter::orientation() */ Orientation orientation() const; /** * See @ref QPrinter::setOrientation() */ void setOrientation(Orientation); /** * See @ref QPrinter::pageOrder() */ PageOrder pageOrder() const; /** * See @ref QPrinter::setPageOrder() */ void setPageOrder(PageOrder); /** * Get the collate status of the current KPrinter * @returns the collate status */ CollateType collate() const; /** * Set the collate status for the current KPrinter * @param _type the collate type */ void setCollate(CollateType); /** * See @ref QPrinter::minPage() */ int minPage() const; /** * See @ref QPrinter::maxPage() */ int maxPage() const; /** * See @ref QPrinter::setMinMax() */ void setMinMax(int, int); /** * Get the first page to be printed. This function is deprecated and applications * should use @ref pageList() instead, which takes into account all options: collate, * page order, ranges, page set, ... * * @see pageList() */ int fromPage() const; /** * Get the last page to be printed. This function is deprecated and applications * should use @ref pageList() instead, which takes into account all options: collate, * page order, ranges, page set, ... * * @see pageList() */ int toPage() const; /** * Set the first and last page to be printed. See @ref QPrinter::setFromTo() */ void setFromTo(int, int); /** * See @ref QPrinter::pageSize() */ PageSize pageSize() const; /** * See @ref QPrinter::setPageSize() */ void setPageSize(PageSize); /** * See @ref QPrinter::printerName() */ QString printerName() const; /** * See @ref QPrinter::setPrinterName() */ void setPrinterName(const QString&); /** * See @ref QPrinter::printProgram(). Unused */ QString printProgram() const; /** * See @ref QPrinter::SetPrintProgram(). Unused */ void setPrintProgram(const QString&); /** * See @ref QPrinter::printerSelectionOption(). Unused. */ QString printerSelectionOption() const; /** * See @ref QPrinter::setPrinterSelectionOption(). Unused */ void setPrinterSelectionOption(const QString&); /** * Get the current page number. * @see setCurrentPage() */ int currentPage() const; /** * Set 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 @ref setCurrentPage() before opening the print dialog: * <pre> * 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 * ... * } * } * </pre> * @param p the current page number (starting from 1) */ void setCurrentPage(int p = 0); /** * Get the page set of the current KPrinter object. * @returns the page set */ PageSetType pageSet() const; /** * Setup the KPrinter object using the print dialog, returns true if the user clicked OK. * @param parent the parent widget to use for the print dialog * @returns boolean value corresponding to the button clicked by the user */ bool setup(QWidget *parent = 0); /** * See @ref QPrinter::margins() */ QSize margins() const; /** * Not used yet. */ void setMargins(QSize m); /** * Get 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. * @returns the page size * @see setRealPageSize */ QSize realPageSize() const; /** * Set the real page size. For internal use only. * @param p the page size * @see realPageSize() */ void setRealPageSize(QSize p); /** * Get 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. * @returns the page list to be printed * @see setCurrentPage() */ QValueList<int> pageList() const; /** * Set the KPrinter object to preview mode if @p 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: * <pre> * 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 ); * } * </pre> * @param on the preview-only state * @see previewOnly() */ void setPreviewOnly(bool on); /** * Get the preview-only state for this KPrinter object. * @returns the preview-only state * @see setPreviewOnly() */ bool previewOnly() const; /** * For internal use only. */ KPrinterImpl* implementation() const; /** * Print 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 * @ref QPainter::end() for a painter object constructed on KPrinter. In normal use, you don't need * this use this fucntion explicitely. */ bool printFiles(const QStringList& files, bool removeafter = false); /** * Add 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 @ref setup(). If you correctly * reimplemented @ref KPrintDialogPage::setOptions(), the settings will be restored from call * to call, you don't have to worry about state saving/restoration. * @param _page the page to add * @see KPrintDialogPage::setOptions() */ static void addDialogPage(KPrintDialogPage*); /** * Set the page selection mode of the application. If needed, call this method somewhere at * the beginning of your code. The default value is @p SystemSide. * @param _mode the mode for the application * @see pageSelection() */ static void setPageSelection(PageSelectionType); /** * Get the page selection mode of the current application. * @returns the page selection mode * @see setPageSelection() */ static PageSelectionType pageSelection(); /** * Set the application type concerning the print dialog. You probably don't want to use it. * For internal use only. * @param _type the type for this application * @see applicationType() */ static void setApplicationType(ApplicationType); /** * Get the application type concerning the print dialog. For internal uase only. * @returns the type for the current application * @see setApplicationType() */ static ApplicationType applicationType(); /** * Add a standard page to the print dialog. This is not useful yet as there's only one * standard page defines @p CopiesPage. * @param p the page identifier * @see StandardPageType */ static void addStandardPage(int p); /** * Remove 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 @p CopiesPage page. * @param p the page identifier * @see StandardPageType */ static void removeStandardPage(int p); /** * Start the add printer wizard. This utility function allows any application for * adding a printer using the KDEPrint powerful wizard. * @param parent the parent widget for the wizard * @returns 1: success, 0: cancel, -1: error */ //static int addPrinterWizard(QWidget *parent = 0); /** * The KPrinter object stores all its settings in an internal @ref QMap structure on @ref * 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". * <pre> * 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; * ... * } * } * </pre> * @param key the option name (key) * @returns the option value correponding to the key, or QString::null * @see KPrintDialogPage, setOption, options(), setOptions() */ const QString& option(const QString& key) const; /** * Add or modify 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 @ref * KPrintDialogPage::getOptions(). * @param key the option name * @param value the option value * @see option(), KPrintDialogPage */ void setOption(const QString& key, const QString& value); /** * Get the complete set of print options from the KPrinter object. For internale use. * @returns the option set as a QMap object */ const QMap<QString,QString>& options() const; /** * Set 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. * @param opts the option set to be merged in the KPrinter object */ void setOptions(const QMap<QString,QString>& opts); /** * For internal use only. Does a similar job as @ref setOption(), except that all possible * internal printers are initialized with the option if it has the form "kde-...". * @param opts the option set * @see setOptions() */ void initOptions(const QMap<QString,QString>& opts); /** * Get 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 setSearchName */ QString searchName() const; /** * Set the search name of the KPrinter object. For internal use. * @param the unique printer search name * @see searchName() */ void setSearchName(const QString& n); /** * Retrieve the last error messgae issued by the print system. Unimplemented yet. * @returns the last error message */ QString errorMessage() const; /** * Set the last error message. For internal use. * @param msg the error message */ void setErrorMessage(const QString& msg); protected: 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); protected: KPrinterPrivate *d; // BIC: move other options to private class KPrinterWrapper *m_wrapper; QMap<QString,QString> m_options; QString m_tmpbuffer; QString m_printername; QString m_searchname; QSize m_margins; QSize m_pagesize; QString m_errormsg; bool m_ready; }; //************************************************************************************** // Utility functions KPrinter::PageSize pageNameToPageSize(const QString& name); const char* pageSizeToPageName(KPrinter::PageSize s); QSize rangeToSize(const QString& s); #endif
Generated by: root@daffy.perf.redhat.com on Mon Jul 14 13:28:29 2003, using kdoc 2.0a53. |