X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2233e5b82c14c529f97b3fd0cba99908de2d5d0c..520200fd10b80c1d759311ed345789f5fe048ca5:/docs/latex/wx/print.tex diff --git a/docs/latex/wx/print.tex b/docs/latex/wx/print.tex index 96af356c34..c35a1f935f 100644 --- a/docs/latex/wx/print.tex +++ b/docs/latex/wx/print.tex @@ -16,12 +16,12 @@ between the print dialogs and the application. \wxheading{See also} -\helpref{wxPrintDialog}{wxprintdialog}, -\helpref{wxPageSetupDialog}{wxpagesetupdialog}, -\helpref{wxPrintDialogData}{wxprintdialogdata}, -\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}, -\helpref{wxPrintDialog Overview}{wxprintdialogoverview}, -\helpref{wxPrinterDC}{wxprinterdc}, +\helpref{wxPrintDialog}{wxprintdialog}, +\helpref{wxPageSetupDialog}{wxpagesetupdialog}, +\helpref{wxPrintDialogData}{wxprintdialogdata}, +\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}, +\helpref{wxPrintDialog Overview}{wxprintdialogoverview}, +\helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPostScriptDC}{wxpostscriptdc} \wxheading{Remarks} @@ -78,13 +78,13 @@ Destructor. \constfunc{bool}{GetCollate}{\void} -Returns TRUE if collation is on. +Returns true if collation is on. \membersection{wxPrintData::GetColour}\label{wxprintdatagetcolour} \constfunc{bool}{GetColour}{\void} -Returns TRUE if colour printing is on. +Returns true if colour printing is on. \membersection{wxPrintData::GetDuplex}\label{wxprintdatagetduplex} @@ -119,21 +119,29 @@ printer should be used. \membersection{wxPrintData::GetQuality}\label{wxprintdatagetquality} -\constfunc{wxPaperQuality}{GetQuality}{\void} +\constfunc{wxPrintQuality}{GetQuality}{\void} Returns the current print quality. This can be a positive integer, denoting the number of dots per inch, or one of the following identifiers: \begin{verbatim} -wxPRINT\_QUALITY\_HIGH -wxPRINT\_QUALITY\_MEDIUM -wxPRINT\_QUALITY\_LOW -wxPRINT\_QUALITY\_DRAFT +wxPRINT_QUALITY_HIGH +wxPRINT_QUALITY_MEDIUM +wxPRINT_QUALITY_LOW +wxPRINT_QUALITY_DRAFT \end{verbatim} On input you should pass one of these identifiers, but on return you may get back a positive integer indicating the current resolution setting. +\membersection{wxPrintData::Ok}\label{wxprintdataok} + +\constfunc{bool}{Ok}{\void} + +Returns true if the print data is valid for using in print dialogs. +This can return false on Windows if the current printer is not set, for example. +On all other platforms, it returns true. + \membersection{wxPrintData::SetCollate}\label{wxprintdatasetcollate} \func{void}{SetCollate}{\param{bool }{flag}} @@ -256,16 +264,16 @@ printer should be used. \membersection{wxPrintData::SetQuality}\label{wxprintdatasetquality} -\func{void}{SetQuality}{\param{wxPaperQuality}{ quality}} +\func{void}{SetQuality}{\param{wxPrintQuality}{ quality}} Sets the desired print quality. This can be a positive integer, denoting the number of dots per inch, or one of the following identifiers: \begin{verbatim} -wxPRINT\_QUALITY\_HIGH -wxPRINT\_QUALITY\_MEDIUM -wxPRINT\_QUALITY\_LOW -wxPRINT\_QUALITY\_DRAFT +wxPRINT_QUALITY_HIGH +wxPRINT_QUALITY_MEDIUM +wxPRINT_QUALITY_LOW +wxPRINT_QUALITY_DRAFT \end{verbatim} On input you should pass one of these identifiers, but on return you may get back a positive integer @@ -338,6 +346,14 @@ When this function has been called, the ownership of the device context is transferred to the application, so it must then be deleted explicitly. +\membersection{wxPrintDialog::Ok}\label{wxprintdialogok} + +\constfunc{bool}{Ok}{\void} + +Returns true if the print data associated with the dialog is valid. +This can return false on Windows if the current printer is not set, for example. +On all other platforms, it returns true. + \membersection{wxPrintDialog::ShowModal}\label{wxprintdialogshowmodal} \func{int}{ShowModal}{\void} @@ -413,13 +429,13 @@ Enables or disables the `Selection' radio button. \constfunc{bool}{GetAllPages}{\void} -Returns TRUE if the user requested that all pages be printed. +Returns true if the user requested that all pages be printed. \membersection{wxPrintDialogData::GetCollate}\label{wxprintdialogdatagetcollate} \constfunc{bool}{GetCollate}{\void} -Returns TRUE if the user requested that the document(s) be collated. +Returns true if the user requested that the document(s) be collated. \membersection{wxPrintDialogData::GetFromPage}\label{wxprintdialogdatagetfrompage} @@ -455,7 +471,14 @@ Returns a reference to the internal wxPrintData object. \constfunc{bool}{GetPrintToFile}{\void} -Returns TRUE if the user has selected printing to a file. +Returns true if the user has selected printing to a file. + +\membersection{wxPrintDialogData::GetSelection}\label{wxprintdialogdatagetselection} + +\constfunc{bool}{GetSelection}{\void} + +Returns true if the user requested that the selection be printed (where 'selection' is +a concept specific to the application). \membersection{wxPrintDialogData::GetToPage}\label{wxprintdialogdatagettopage} @@ -463,11 +486,19 @@ Returns TRUE if the user has selected printing to a file. Returns the {\it to} page number, as entered by the user. +\membersection{wxPrintDialogData::Ok}\label{wxprintdialogdataok} + +\constfunc{bool}{Ok}{\void} + +Returns true if the print data is valid for using in print dialogs. +This can return false on Windows if the current printer is not set, for example. +On all other platforms, it returns true. + \membersection{wxPrintDialogData::SetCollate}\label{wxprintdialogdatasetcollate} \func{void}{SetCollate}{\param{bool }{flag}} -Sets the 'Collate' checkbox to TRUE or FALSE. +Sets the 'Collate' checkbox to true or false. \membersection{wxPrintDialogData::SetFromPage}\label{wxprintdialogdatasetfrompage} @@ -503,14 +534,21 @@ Sets the internal wxPrintData. \func{void}{SetPrintToFile}{\param{bool }{flag}} -Sets the 'Print to file' checkbox to TRUE or FALSE. +Sets the 'Print to file' checkbox to true or false. + +\membersection{wxPrintDialogData::SetSelection}\label{wxprintdialogdatasetselection} + +\func{void}{SetSelection}{\param{bool}{ flag}} + +Selects the 'Selection' radio button. The effect of printing the selection depends on how the application +implements this command, if at all. \membersection{wxPrintDialogData::SetSetupDialog}\label{wxprintdialogdatasetsetupdialog} \func{void}{SetSetupDialog}{\param{bool }{flag}} Determines whether the dialog to be shown will be the Print dialog -(pass FALSE) or Print Setup dialog (pass TRUE). +(pass false) or Print Setup dialog (pass true). Note that the setup dialog is (according to Microsoft) obsolete from Windows 95, though retained for backward compatibility. @@ -576,7 +614,7 @@ Destructor. \func{bool}{Abort}{\void} -Returns TRUE if the user has aborted the print job. +Returns true if the user has aborted the print job. \membersection{wxPrinter::CreateAbortWindow}\label{wxprintercreateabortwindow} @@ -584,6 +622,26 @@ Returns TRUE if the user has aborted the print job. Creates the default printing abort window, with a cancel button. + +\membersection{wxPrinter::GetLastError}\label{wxprintergetlasterror} + +\func{static wxPrinterError}{GetLastError}{\void} + +Return last error. Valid after calling \helpref{Print}{wxprinterprint}, +\helpref{PrintDialog}{wxprinterprintdialog} or +\helpref{wxPrintPreview::Print}{wxprintpreviewprint}. These functions +set last error to {\bf wxPRINTER\_NO\_ERROR} if no error happened. + +Returned value is one of the following: + +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxPRINTER\_NO\_ERROR}}{No error happened.} +\twocolitem{{\bf wxPRINTER\_CANCELLED}}{The user cancelled printing.} +\twocolitem{{\bf wxPRINTER\_ERROR}}{There was an error during printing.} +\end{twocollist} + + \membersection{wxPrinter::GetPrintDialogData}\label{wxprintergetprintdialogdata} \func{wxPrintDialogData\&}{GetPrintDialogData}{\void} @@ -592,13 +650,15 @@ Returns the \helpref{print data}{wxprintdata} associated with the printer object \membersection{wxPrinter::Print}\label{wxprinterprint} -\func{bool}{Print}{\param{wxWindow *}{parent}, \param{wxPrintout *}{printout}, \param{bool }{prompt=TRUE}} +\func{bool}{Print}{\param{wxWindow *}{parent}, \param{wxPrintout *}{printout}, \param{bool }{prompt=true}} Starts the printing process. Provide a parent window, a user-defined wxPrintout object which controls the printing of a document, and whether the print dialog should be invoked first. -Print could return FALSE if there was a problem initializing the printer device context -(current printer not set, for example). +Print could return false if there was a problem initializing the printer device context +(current printer not set, for example) or the user cancelled printing. Call +\helpref{wxPrinter::GetLastError}{wxprintergetlasterror} to get detailed +information about the kind of the error. \membersection{wxPrinter::PrintDialog}\label{wxprinterprintdialog} @@ -606,7 +666,9 @@ Print could return FALSE if there was a problem initializing the printer device Invokes the print dialog. If successful (the user did not press Cancel and no error occurred), a suitable device context will be returned -(otherwise NULL is returned). +(otherwise NULL is returned -- call +\helpref{wxPrinter::GetLastError}{wxprintergetlasterror} to get detailed +information about the kind of the error). The application must delete this device context to avoid a memory leak. @@ -654,13 +716,13 @@ necessary for setting up a suitable printer device context. This is the recommended way to construct a wxPrinterDC. \func{}{wxPrinterDC}{\param{const wxString\& }{driver}, \param{const wxString\& }{device}, \param{const wxString\& }{output}, - \param{const bool }{interactive = TRUE}, \param{int }{orientation = wxPORTRAIT}} + \param{const bool }{interactive = true}, \param{int }{orientation = wxPORTRAIT}} Constructor. With empty strings for the first three arguments, the default printer dialog is displayed. {\it device} indicates the type of printer and {\it output} is an optional file for printing to. The {\it driver} parameter is currently unused. Use the {\it Ok} member to test whether the -constructor was successful in creating a useable device context. +constructor was successful in creating a usable device context. This constructor is deprecated and retained only for backward compatibility. @@ -691,7 +753,8 @@ wxPrintPreview object to initiate printing or previewing. \func{}{wxPrintout}{\param{const wxString\& }{title = "Printout"}} -Constructor. Pass an optional title argument (currently unused). +Constructor. Pass an optional title argument - the current filename would be a good idea. This will appear in the printing list +(at least in MSW) \membersection{wxPrintout::\destruct{wxPrintout}} @@ -722,6 +785,10 @@ it should be designed to take no parameters (other than the self reference) and to return a tuple of four integers. } +\perlnote{When this method is overridden in a derived class, +it must not take any parameters, an return a 4-element list. +} + \membersection{wxPrintout::GetPageSizeMM}\label{wxprintoutgetpagesizemm} \func{void}{GetPageSizeMM}{\param{int *}{w}, \param{int *}{h}} @@ -730,6 +797,9 @@ Returns the size of the printer page in millimetres. \pythonnote{This method returns the output-only parameters as a tuple.} +\perlnote{In wxPerl this method takes no arguments and returns a +2-element list {\tt ( w, h )}} + \membersection{wxPrintout::GetPageSizePixels}\label{wxprintoutgetpagesizepixels} \func{void}{GetPageSizePixels}{\param{int *}{w}, \param{int *}{h}} @@ -743,6 +813,9 @@ previewing is to be supported. \pythonnote{This method returns the output-only parameters as a tuple.} +\perlnote{In wxPerl this method takes no arguments and returns a +2-element list {\tt ( w, h )}} + \membersection{wxPrintout::GetPPIPrinter}\label{wxprintoutgetppiprinter} \func{void}{GetPPIPrinter}{\param{int *}{w}, \param{int *}{h}} @@ -754,6 +827,9 @@ this by a scaling factor to take the preview DC size into account. \pythonnote{This method returns the output-only parameters as a tuple.} +\perlnote{In wxPerl this method takes no arguments and returns a +2-element list {\tt ( w, h )}} + \membersection{wxPrintout::GetPPIScreen}\label{wxprintoutgetppiscreen} \func{void}{GetPPIScreen}{\param{int *}{w}, \param{int *}{h}} @@ -763,36 +839,45 @@ Dividing the printer PPI by the screen PPI can give a suitable scaling factor for drawing text onto the printer. Remember to multiply this by a scaling factor to take the preview DC size into account. +\membersection{wxPrintout::GetTitle}\label{wxprintoutgettitle} + +\func{wxString}{GetTitle}{\void} + +Returns the title of the printout + \pythonnote{This method returns the output-only parameters as a tuple.} +\perlnote{In wxPerl this method takes no arguments and returns a +2-element list {\tt ( w, h )}} + \membersection{wxPrintout::HasPage}\label{wxprintouthaspage} \func{bool}{HasPage}{\param{int}{ pageNum}} -Should be overriden to return TRUE if the document has this page, or FALSE -if not. Returning FALSE signifies the end of the document. By default, +Should be overridden to return true if the document has this page, or false +if not. Returning false signifies the end of the document. By default, HasPage behaves as if the document has only one page. \membersection{wxPrintout::IsPreview}\label{wxprintoutispreview} \func{bool}{IsPreview}{\void} -Returns TRUE if the printout is currently being used for previewing. +Returns true if the printout is currently being used for previewing. \membersection{wxPrintout::OnBeginDocument}\label{wxprintoutonbegindocument} \func{bool}{OnBeginDocument}{\param{int}{ startPage}, \param{int}{ endPage}} -Called by the framework at the start of document printing. Return FALSE from +Called by the framework at the start of document printing. Return false from this function cancels the print job. OnBeginDocument is called once for every copy printed. The base wxPrintout::OnBeginDocument {\it must} be called (and the return value -checked) from within the overriden function, since it calls wxDC::StartDoc. +checked) from within the overridden function, since it calls wxDC::StartDoc. -\pythonnote{If this method is overriden in a Python class then the +\pythonnote{If this method is overridden in a Python class then the base class version can be called by using the method -\tt{base_OnBeginDocument(startPage, endPage)}. } +{\tt base\_OnBeginDocument(startPage, endPage)}. } \membersection{wxPrintout::OnEndDocument}\label{wxprintoutonenddocument} @@ -802,7 +887,7 @@ Called by the framework at the end of document printing. OnEndDocument is called once for every copy printed. The base wxPrintout::OnEndDocument {\it must} be called -from within the overriden function, since it calls wxDC::EndDoc. +from within the overridden function, since it calls wxDC::EndDoc. \membersection{wxPrintout::OnBeginPrinting}\label{wxprintoutonbeginprinting} @@ -830,14 +915,12 @@ number of pages in the document, for example. \func{bool}{OnPrintPage}{\param{int}{ pageNum}} -Called by the framework when a page should be printed. Returning FALSE cancels +Called by the framework when a page should be printed. Returning false cancels the print job. The application can use wxPrintout::GetDC to obtain a device context to draw on. \section{\class{wxPrintPreview}}\label{wxprintpreview} -\overview{Printing framework overview}{printingoverview} - Objects of this class manage the print preview process. The object is passed a wxPrintout object, and the wxPrintPreview object itself is passed to a wxPreviewFrame object. Previewing is started by initializing and showing @@ -879,7 +962,7 @@ called, since they will be deleted in the wxPrintPreview constructor. The same does not apply to the {\it data} argument. Test the Ok member to check whether the wxPrintPreview object was created correctly. -Ok could return FALSE if there was a problem initializing the printer device context +Ok could return false if there was a problem initializing the printer device context (current printer not set, for example). \membersection{wxPrintPreview::\destruct{wxPrintPreview}} @@ -950,7 +1033,7 @@ or NULL if none exists. \func{bool}{Ok}{\void} -Returns TRUE if the wxPrintPreview is valid, FALSE otherwise. It could return FALSE if there was a +Returns true if the wxPrintPreview is valid, false otherwise. It could return false if there was a problem initializing the printer device context (current printer not set, for example). \membersection{wxPrintPreview::PaintPage}\label{wxprintpreviewpaintpage} @@ -972,6 +1055,10 @@ supplied in the wxPrintPreview constructor. Will normally be called by the {\bf Print...} panel item on the preview frame's control bar. +Returns false in case of error -- call +\helpref{wxPrinter::GetLastError}{wxprintergetlasterror} to get detailed +information about the kind of the error. + \membersection{wxPrintPreview::RenderPage}\label{wxprintpreviewrenderpage} \func{bool}{RenderPage}{\param{int }{pageNum}}