X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2233e5b82c14c529f97b3fd0cba99908de2d5d0c..af49404386397a3582cdb0070aab315bd5d83d91:/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}}
