ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

home *** CD-ROM | disk | FTP | other *** search

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / PASCAL / TPRINT.ZIP / PRINTER.DOC < prev next >

Wrap

Text File | 1991-05-21 | 48.4 KB | 731 lines

DOCUMENTATION FOR TURBO PASCAL PRINTER UNITS These units are for use in Turbo Pascal Windows Programs. They are shareware. You may use these units in any non-commercial products freely. You may copy the programs and the documentation and distribute them freely. If these units are to be incorporated into a commercial product, or if you wish source on disk, please send $25.00 to OptiCom, Inc, Box 16-1127, Miami, FL 33116. Our phone number is (305) 271-5138, and our CompuServe ID is 71250,71. If you register the product, I will send you irregular updates of these objects as I improve them. These objects, all source code and the contents of this document are copyright (c) 1991 OptiCom, Inc. We would sincerely welcome any comments/criticism/ideas you might have about these objects. The idea for these objects and the information in this document came from several sources. The objects themselves are loosely based on the printer classes contained in the Actor Development Environment, an excellent product of the Whitewater Group. Other material came from Charles Petzold's Programming Windows, the Microsoft SDK, the Turbo Windows Manuals, Compuserve and several friends and associates. Files on this disk: pDevice.pas Formal printer object, tPrnDevice. printer.pas Printer Object, tPrinter. repPrn.pas example of a report printer derived from the printer class. testPrn1.pas example file printer program, using the tPrinter object. testPrn2.pas example file printer program, using the reportPrinter object. test.res resource file prt.res resurce file printer.doc This document GENERAL OVERVIEW These objects are designed to provide an interface between a printer and an application running under Windows. The structure of these objects is such that you should not have to modify them to add functionality or change their behavior. You should create descendants of the objects to add additional features. An example of this is the ReportPrinter object, in the file RepPrn.pas. The reportPrinter object adds several features to the printer unit to handle headings and page size. Having learned the basics of OOP in the Actor environment, I have come to appreciate the advantages of adhering as strictly as possible to the principles of OOP. The Actor environment is pure OOP. That means that everything (and I mean everything!) is an object. The main advantage of OOP programming is the ease of modifying and extending the objects that you create. I hope these objects will prove to be good examples of this type of programming. These objects have been written with the OOP philosophy in mind. There is no access to the instance variables of an object outside that object's scope. All access to instance variables is through the methods of the object. Modifications to be made to the objects are made through descendants, not by modifying the code of the object. This is illustrated by the ReportPrinter object. This document is divided into several sections. The first discusses the relationship between Windows and the printer. It covers, in a general manner, the calls to Windows contained in the objects. I have tried to provide enough information to make clear what I am doing in each object, and so that the objects can be extended to suit your own needs. The other sections discuss the objects themselves and the sample programs. Each object section contains an explanation of the declared types in the unit, the object's instance variables and methods, and a bit about what the object is supposed to do. The sections on the sample programs discuss the nature of the programs, and how they use the objects to print. PRINTING IN WINDOWS It used to be that all you had to do to print something was USE the printer, and let fly. With some well placed WriteLn statements and judicious spacing, you could produce reasonable output. Not any more. Under Windows, printing requires almost as much programming as some small applications! To a Windows application, sending output to a printer is not much different than sending output to a window. The application actually sends its output to Windows, and Windows handles the mechanism of getting it where it is supposed to go. In general, printing under Windows requires the following steps: 1. The application must retrieve information about the current printer from the WIN.INI file. 2. The application must create a device context (a handle) for the printer. 3. Output is sent to the device context. 4. The application communicates with the printer device driver using escape codes. 5. Windows activates the print spooler to manage the print job. In addition to these basic steps, an application can also display a dialog box to allow a user to cancel a print job that is being spooled. This requires the instantiation of an Abort procedure to notify windows about the status of the print job. Windows' management of each print job revolves around the concept of a document. You can think of each, complete print job as a document. This applies no matter how large the output will be. Each time a new print job is started, that print job is one document. Since it is possible that more that one document may be printing at the same time, each individual print job must be kept separate from any other print job to avoid mixing them up during output. The application must notify Windows when a document is going to start. When printing has finished, the application must notify Windows that the document has ended. This notification is done using escape calls. In the following section, some of the concepts introduced above will be discussed in greater detail. ABORT PROCEDURE: An abort procedure is known as a callback function. It is a function in an application that is called by Windows during a print job. The function returns a boolean value indicating whether the user has canceled the print job. During normal processing, messages sent to the abort function are translated and dispatched back to Windows. As long as the print job is not canceled, the function returns a TRUE value to Windows. If the print job is canceled, the function returns FALSE, letting Windows know the job was canceled. In order to implement an abort procedure, it is necessary to provide a dialog box and an abort function. The dialog box generally contains a brief message ('Sending job to spooler...') and a cancel button. Pressing the cancel button should set a variable accessible to the abort function to FALSE. The abort procedure must be declared as a EXPORTed function, and must return a boolean value. This is done in the AbortProc method of the printer object. The abort function may not be a method of an object, since object methods may not be exported. This also means that the print dialog may not be contained in an instance variable of an object, since the Abort procedure would not have access to it. Finally, the variable set by the Cancel method of the print dialog must be global to the unit in which these two items are declared. Again, the process necessary for creating an abort mechanism may be seen in the Printer.pas file. The next step is to notify Windows of the existence of the abort function. This is done by sending the SETABORTPROC escape code to Windows, with a far pointer to the abort function as a parameter. This pointer is obtained through the MakeProcInstance method. MakeProcInstance creates a far pointer that is bound to the data segment of the instance of the application that contains the abort function. This is so that when Windows calls the abort function, it uses data in the current instance. The application instance refers to the instance handle of the current application. A handle is a number that uniquely identifies a program running under Windows. Since multiple instances of a program share code, it is necessary for Windows to keep track of who is doing what. The call to MakeProcInstance returns a tFarPointer which is then used in the SetAbortProc escape call. The SetAbortProc escape call passes the pointer to the abort function to Windows. If an application does not set an abort procedure, it is quite likely that any errors will cause the program to crash. One common error is a lack of disk space for spooling. In the abort procedure, the application can decide whether to wait for some disk space to be freed, or to cancel the print job. If an print job terminates abnormally, or if it is canceled, the GDI automatically cancels the print job. In this case, the application should not attempt to end the print job using escape calls. Both the abort procedure and the print dialog box must be instantiated prior to issuing the STARTDOC escape call to create the document. DEVICE CONTEXT: When an application wants to use a device, it must obtain a handle for that device from Windows. This handle is known as the device context. Through the device context, an application has access to various devices attached to the computer. The device context is actually a data structure maintained by the GDI, containing information about the particular device to which it belongs. For example, when output is sent to the printer, the GDI uses the information contained in this data structure to properly format the output. A device context works very much like a file in a Pascal program. Once you have assigned a file name to a file variable, all access to the file passes through the file variable. In a Windows program, all access to the device must 'pass through' the device context handle. Device Mode: The device mode function is part of the printer device driver. These drivers are supplied by the manufacturer and distributed with Windows. When you call DeviceMode, you are calling a routine in a DLL. The deviceMode call is responsible for displaying the printer dialog box, allowing a user to change the printer parameters. The name of the function in a driver written for Windows 3 is ExtDeviceMode. In drivers for earlier versions of Windows, the function is DeviceMode. There are several differences between these two functions. The most important one is that in the DeviceMode call, any changes to the device parameters are reflected in the WIN.INI file. These changes will affect all current and future sessions of Windows. In the ExtDeviceMode procedure, the programmer has the option to make the changes permanent, or to maintain them for the current session only. ESCAPE CALLS: Escape calls allow an application to communicate with a printer device driver. The escape sequences contain commands and information for the driver. They can also be used to obtain device-specific information. There are quite a number of escape codes that can be used (57, I believe). These are listed in the Turbo Windows Reference guide under Printer Escape Codes. GDI (Graphics Device Interface): The GDI is a programming language that acts as an interface between an application, the printer device driver and the print manager. An application does not have to know anything about the devices with which it will communicate. As long as the application uses the GDI to access the devices, all of the output functions will be handled by Windows. This is known as device- independence. As you will see, close communication is necessary between an application, Windows and the printer driver to print a document. WIN.INI file: The WIN.INI file plays an important part in the printing process. In the method GetPrinterParms, this file is queried to obtain information about the current printer. Information in the WIN.INI file is stored under application name and key name headings. Printer information is contained under the application name '[windows]' and the key name 'device'. The key name is followed by the currently selected printer, the name of it's device driver, and the port to which the printer is connected. For example, a typical device keyword might look like this: Device=IBM Proprinters,PROPRINT,LPT1: This tells us that the currently selected printer is an IBM Proprinter, the driver is PROPRINT.DRV, and the printer is connected to LPT1. The settings in this file can be modified by the DeviceMode call to the printer device driver. It is also possible, using the ClearEnv method, to force a device to read the WIN.INI file to obtain the current printer parameters. =============================================== PRINTER OBJECT REFERENCE tPrnDevice, Contained in file pDevice.Pas INSTANCE VARIABLES hPrintDC Holds the printer device context. This variable is instantiated by the DCcreated method. hWindow Contains the handle to the parent window from which the printer object was created. This variable is instantiated by the Init method, using a value passed from the application. docName The name of the document that is being printed. This variable is instantiated in the BeginDoc method. The document name is used with the STARTDOC escape call to uniquely identify the document being printed. This allows the print manager to manage separate print jobs, without their interfering with one another. When the print manager is active, this name appears on the status line for the selected printer. Device The name of the printer. This is obtained through a call to getPrinterParms, which retrieves the information from the WIN.INI file Driver The name of the device driver associated with the device. This information is also obtained through the getPrinterParms call dMode a tDevMode data structure. Although it is not used extensively in these objects, this structure holds a great deal of information about the printer and device driver. It is used by DeviceCapabilities and by the getExtDeviceMode to hold information about a printer device driver. noSpooler A boolean variable that is set in the GetPrinterParms method, based on the value for spooler in the WIN.INI file. It indicates whether the spooler is active or not. prnPort The port to which the object will print. This information is obtained from the WIN.INI file through a call to getPrinterParms. TYPES devArray An 80 character string used in the unit to hold various values. prnErrors Enumerated type defining the different errors that can occur during the printing process. These are used as parameters when calling the PrnError method. pPrnDevice A pointer to the tPrnDevice Object. tPrnDevice The formal printer object. You should not create an instance of this class. Instantiate tPrinter instead. tGetDevMode This is a template for a windows function call to display the device driver dialog box for drivers not written for windows 3.0. tGetExtDevMode This is a template for a windows function call to display the device driver dialog box for device drivers written for windows 3.0. METHODS AbortPrn Aborts the current print job. BeginDoc Sends the STARTDOC escape call to windows to indicate the start of a document. This is an important call. Included in the Escape call is the name of the document to be printed. This name is used by the GDI to identify a unique print job, and prevents documents longer than one page from being mixed in with other documents. The job name appears in the print manager list of jobs. The STARTDOC call should always be paired with an ENDDOC or ABORTDOC escape call. CallEscape Sends an escape code to the GDI, using passed parameters. The syntax of an Escape call is: Escape(DC: hDC; Escape, Count: Integer; InData, OutData: Pointer): Integer where DC is the selected device context, Escape is the escape code, count is the number of bytes in InData, and outData is the data structure to receive data from the escape call, if requested. The function returns an integer value that is positive if the escape call was successful, zero if escape is not implemented, and negative if an error occurred. This method centralizes the escape calls to allow errors resulting from the calls to be handled from one location. Most errors occur on a NewFrame boundary, which signifies the end of a page. ClearEnv Clears the device's environment. This forces the printer driver to read the current printer settings from the WIN.INI file. DCcreated Creates a device context for the printer by calling the CreateDC method. CreateDC returns a word value greater than 0 if the call was successful. DeleteContext Deletes the device context created for the printer. DeviceName Returns the value of the Device instance variable. DocAbort Sends the ABORTDOC escape code. This code terminates the current job and erases everything the application has written to the device since the last ENDDOC code. This code is normally used to terminate print jobs that have not implemented an abort procedure, or those that have not reached their first NewFrame escape call. If a print job terminates due to cancellation or an error, this call should not be used. The GDI automatically terminates print jobs under these circumstances. If the application has created a cancellation dialog, the ABORTDOC code must be sent before the dialog box is destroyed, and before freeing an abort procedure-instance. Done Destructor method. Calls the parent (tObject) destructor. DoNewFrame Sends the NEWFRAME escape code to Windows. This code lets the printer know that the application has finished writing to a page. It causes a form feed to be issued. The NEWFRAME call restores the default values of the device context. If a font other than the default font has been selected, that font must be reselected after the NEWFRAME Escape. DraftModeOff Turns the printer draft mode off by sending the DRAFTMODE escape code. This method illustrates the use of the InData structure, sending a word value indicating the desired state of the draft mode. The value is passed in the high portion of the word. A value of 0 turns draft mode off, 01 turns it on. The draft mode of the printer can only be changed at page boundaries, such as after a NEWFRAME escape call. DraftModeOn Turns the printer draft mode on by sending the DRAFTMODE escape code. This method illustrates the use of the InData structure, sending a word value indicating the desired state of the draft mode. The value is passed in the high portion of the word. A value of 0 turns draft mode off, 01 turns it on. Since the value is passed in the high portion of the word, the value passed is 1000. In the method draftModeOff, the passed value is zero. The draft mode of the printer can only be changed at page boundaries, such as after a NEWFRAME escape call. DriverName Returns the value of the Driver instance variable. EndDocument Sends the ENDDOC Escape code to Windows. This signals that the current document has completed. If the print job has terminated abnormally, this method should not be called. In cases of abnormal termination, the GDI terminates the operation. If the application displays a print cancel dialog, the ENDDOC code must be sent before the dialog box is destroyed, and before freeing the procedure instance of an abort procedure. The ENDDOC or ABORTDOC escape calls should always be paired with the STARTDOC escape call. EndOfFile Ends the document. Causes a newPage, sends the ESCAPEDOC escape call, and deletes the printer device context. FlushPrn Sends the FLUSHOUTPUT escape code, which flushes the printer's output buffer. GetPrinterParms Retrieves the printer parameters from the WIN.INI file. The syntax for the call to GetProfileString is: GetProfileString(appName,keyName,default,RetunString: pChar; Size: Integer) where appName is the heading name to search for in the WIN.INI file, keyName is the key to search for under the heading, default is the default value if keyName is not found, ReturnString is the buffer in which the value of KeyName will be stored, and Size is the size of the buffer. The appName is usually 'windows', the keyName is usually 'device'. On returning from the call, ReturnString contains the name of the printer, the name of the printer driver and the port to which the printer is connected. These values are separated by commas. The returned values are copied to instance variables, since they are used by other methods in the object. Finally, there is another call to GetProfileString, this time searching for the keyName, 'spooler'. The value at this location is then used to set the boolean variable, noSpooler to true or false. This variable indicates whether the print spooler is active. Init Constructor method. Calls the parent (tObject) constructor. InitAbortProc Sends the SETABORTPROC escape code to initialize the abort procedure. The address for this procedure is passed in the procAddr variable. This illustrates the use of the InData data structure to send information to Windows. See the discussion about abort procedures, above, for more information. okPrint Returns true if the device context is greater than zero. PrinterPort Returns the value of the prnPort instance variable. prnDeviceMode This method displays the printer device driver dialog box, allowing the user to change the printer settings. This method has several variables: dHandle Handle of the load library for the current printer. drvName File name of the driver used to get dHandle. pAddr address of the procedure in the device DLL that will be called. A call to GetPrinterParms initializes the variables device and driver. Using the value in driver, a filename for the device driver is created by concatenating the extension '.drv' to the driver name. This is stored in the local variable, drvName. The call to LoadLibrary loads the device driver into memory, and returns a tHandle value that specifies the library module instance. If the value is less than 32, an error occurred. Note that in this version of the printer object, I am not trapping errors resulting from this call. The first call to GetProcAddress searches the DLL for a function named ExtDeviceMode. If that function is located, a tFarProc value is returned, representing the address of the function in the DLL. This function is present only in device drivers written for windows 3.0. If an address is returned, the ExtDeviceMode function is called, using the tGetExtDevMode function type as a template. The syntax for a call to ExtDeviceMode is: ExtDevMode(hWnd,hDriver,lpDevModeOutput,lpDeviceName, lpPort,lpDevModeInput,lpProfile,wMode) where hWnd is the parent window of the caller, hDriver is the device driver module, lpDevModeOutput is a tDevMode data structure. The driver will write the initialization information supplied in the lpDevModeInput parameter to this structure. lpDeviceName is the name of the printer device, lpPort is the port to which the printer is connected, lpDevModeInput is a tDevMode structure that supplies initialization information to the printer driver, lpProfile contains the name of a file with initialization information. If this parameter is nil, WIN.INI is used. wMode is a mask that determines what types of operations the function will perform. If wMode is 0, the call to the function returns the number of bytes required by the printer device driver structure. Otherwise, this parameter must have one or more of the following values (multiple values should be OR'd together): dm_Copy Writes the printer driver settings to the tDevMode record passed in lpDevModeOutput. dm_Modify Modifies the printer driver settings to the values passed in the lpDevModeInput record. dm_Prompt Displays the device mode dialog box, and changes the printer settings to what the user specified dm_Update Updates the printer environment and the WIN.INI to reflect the changes made by the user to the printer settings. If you do not include dm_update in the call to DevMode, any changes made to the printer settings will be for the current session only, and will not affect other, concurrent sessions. If the value returned from the first call to GetProcAddress is nil, indicating that the driver was not written for Windows 3, a second call is made to GetProcAddress to get the address of the DeviceMode function. The DeviceMode function always updates the WIN.INI file when it's parameters are changed. The syntax for a call to DeviceMode is: DeviceMode() where The call to FreeLibrary releases the loaded library module, and any memory associated with it. PrnError Calls an error routine based on the value of msgNum. Each of the error routines has been coded separately to allow them to be overridden in descendant objects. The error routines are not listed here. Each one calls the messageBox routine, passing the address of the appropriate error string and dialog title. These strings are declared as constants (eMsg) at the start of the implementation section. USING TPRNDEVICE The tPrnDevice object is a formal object; that is, you should never create an instance of it. It's purpose is to manage the lower level interface between Windows, an application, and the device driver. The tPrinter object, discussed next should be instantiated instead. It provides the higher level interface between the application and the tPrnDevice object. THE TPRINTER OBJECT Instance Variables HInst Contains the application instance value passed from the calling application. This variable is used in the NewAbortProc method when the call to MakeProcInstance is made. See the discussion concerning abort procedures at the beginning of this document. LpAbortProc Receives the tFarProc value returned from the MakeProcInstance call in the NewAbortProc method. maxX Holds the maximum line length, in pixels. This variable is initialized in the Start method. maxY Holds the maximum page length, in pixels. This variable is initialized in the Start method. Metrics A tTextMetrics data structure. This structure contains information about the selected font. It include the average dimensions of the characters, the number of characters in the font and the character set on which the font is based. Text metrics are most often used to determine the line spacing of the printed output. In this unit, the height of a line is returned by the height method. The height is the sum of the tmHeight field, which is the height of each character cell, and the tmExternalLeading fields, which is the recommended spacing between the bottom of one character cell and the top of the next. OkToPrint This variable is used as a flag to determine whether various steps in the initialization process were completed successfully. posX Holds the horizontal position of the print head on a line, in pixels. posY Holds the vertical position of the print head on the page, in pixels. TheParent A pWindowsObject that is initialized in the Init method. This variable holds the parent window from which this routine was instantiated. It's value is used in the printDialog method to instantiate the print cancel dialog. TYPES tPrinter The printer object. This is the lowest-level object that should be instantiated to print under Windows. It is a descendant of the tPrnDevice object, which handles the lower level interface with Windows. tPrnDialog A descendant of tDialog. This is the print cancel dialog that appears when a print job is being spooled. Pressing the cancel button sets the unit variable UserAbort to true, causing the print job to be canceled. UNIT VARIABLES PrintDialog A pointer to a tPrnDialog. This variable is not an instance variable, since it must be accessible from the abortProc function. Since the AbortProc method has no 'knowledge' of the printer object, it would not be able to intercept a message from the dialog. UserAbort A global boolean variable that is set when the user presses cancel in the print dialog box. This variable is checked by the AbortProc function to see if the print job has been aborted. See the discussion of the Abort Procedure near the beginning of this document. UNIT METHODS AbortProc This function is a callback function, called by windows during a print job. If the user presses cancel in the Print Dialog box, this function notifies Windows that the print job had been canceled. TPRINTER METHODS CheckNewPage This method compares the value of posY (the vertical position of the print head on the page) with MaxY (the maximum page length). If posY > maxY, the newPage method is called. CheckStart This method is responsible for some of the initialization that takes place within the printer object. It's calls deal mainly with the interface between the application and the printer object. The initialization between the printer object and Windows is handled by the Start method. CheckStart is responsible for instantiating the print dialog and the abort procedure, and disabling mouse and keyboard input to the parent window. If these initializations are performed successfully, CheckStart then calls the beginDoc method, which sends the STARTDOC escape call to the GDI. If any of the Init calls fail, or if the document is not started, checkStart reverses those initializations that were successfully completed. DoNewFrame Calls the ancestor.doNewFrame method to force a form feed. Finish This method is called at the end of a print job. It calls the EndOfFile method and the stopPrinter method, and frees the procedure instance created for the abort procedure. Height Returns the line spacing for the selected font. This is the sum of the metrics.tmHeight and metrics.tmExternalLeading fields. See the discussion under metrics, above, for more information. Init The Init method calls the ancestor.Init method, and initializes several instance variables. LineWidth This method returns the width (line length) of the passed string, based on the currently selected font. This is done through a call to GetTextExtent, which returns a longInt value containing the height of the string in the high word, and the width of the string in the low word. The lineWidth method returns only the width of the string. This value is used in the print method to check if the length of the string currently being printed causes the current line length to exceed the width of the page. If so, the offending text is wrapped to the next line. NewAbortProc This method calls the makeProcInstance function to obtain a far pointer to an abort procedure, bound to the data segment of the current application instance. This value is then passed in the inData parameter of the SetAbortProc escape call. This function returns true if the escape call returns a value greater than zero. It is important to note that all this method does is pass a pointer to a function. It does not guarantee that the pointer is valid, or that the function itself is valid. For example, if the EXPORT statement is left off of the AbortProc declaration, the program will still run, but the cancel dialog box will not work. NewLine NewLine causes a line feed by setting the posX variable to 0, and incrementing the posY variable by the value returned by the height method. NewPage NewPage starts a new page by resetting the values of posX and posY, and calling the doNewFrame method. PageSize This method returns a tPoint type containing the size of the page in pixels. These values are obtained by two calls to the Windows GetDeviceCaps method. GetDeviceCaps allows you to determine the extent of the printer device text writing abilities. There are about 28 different queries that can be made, including the horizontal and vertical resolution (used here), the aspect ratios for line drawing, the number of fonts, and so on. The possible parameters for calls to this method are listed in the Window reference guide, under Device capabilities. Print This method calls the printString method to send a line of text to the printer. Before making this call, Print determines whether the line length has been exceeded, based on the current position of the print head and the width of the string to be printed. If the length has been exceeded, Print forces a new line. Note that the entire string is wrapped to the next line from the beginning. The string is then sent to the printer by a call to the printString method. If the printString call is successful, the value of posX is incremented by the width of the string. Under normal circumstances, print does not issue a line feed. The Print method is similar to the Write procedure in standard pascal, in that it does not advance to the next line. PrintDlg Creates the print dialog box, a modeless dialog present while the print job is in progress. The purpose of the dialog box is to allow the user to cancel a print job. PrintLine PrintLine is similar to the WriteLn procedure in standard Pascal. It prints a line of text, followed by a line feed. It does this by calling the print method, followed by the newLine method. PrintString PrintString sends a null-terminated string of text to the selected device context using the TextOut method. The TextOut method writes the character string using the currently selected font. It is called by the Print method. RemoveDlg Destroys the print dialog box and disposes of the printDialog pointer. ResetPos Sets the posX and posY values to 0, indicating the start of a new page. Start The start method takes care of initializing the printer object and its relation with Windows. It is responsible for obtaining a device context, initializing most of the instance variables, and calling the CheckStart method to complete the initialization. If checkStart is successful, Start returns true. StopPrinter This method re-enables the parent window, removes the print dialog box, and sets the OkToPrint variable to false. TextHeight Returns the value of the metrics.tmHeight field, which is the height of the character cell of the currently selected font. TextWidth Returns the average width of the characters in the currently selected character set. Using the tPrinter object The tPrinter object is the object to use in an application to obtain basic access to the printer. The sample program TestPrn1 illustrates a simple file printing program that uses this object. Tprinter handles the interface between an application and the tPrnDevice object. That object handles the interface between the tPrinter object and the GDI. By maintaining this separation, it becomes much easier to extend the functionality of either the tPrnDevice or the tPrinter. If you find that the two objects meet your basic printing needs, but you need more features than they offer, the correct way to add new features is to create descendant objects. You should avoid, as much as possible, modification of these parent objects. =============================================== SAMPLE PROGRAMS The TestPrn1 sample program This program allows you to print a file or display the device mode dialog for a printer. The application object is tTestApp, the main window object is tPrnWindow. The printer object is instantiated using the tPrnWindow instance variable aPrinter. The two methods that interest us are the setPrinter method and the filePrint method. SETPRINTER METHOD This method displays the device mode dialog. It consists of three lines: aPrinter := new(pPrinter,Init(hInstance,@self)); aPrinter^.prnDeviceMode(hWindow); dispose(aPrinter,Done); The first line instantiates aPrinter as a printer object. The hInstance variable contains the current tTestApp instance. The @Self parameter is the tPrnWindow object. The second line calls the prnDeviceMode method of the printer object. The hWindow parameter contains the device context for the current tPrnWind. The third disposes of the printer object. In the printer object, the device mode call has been set to change the environment only for the current session. THE FILEPRINT METHOD The filePrint method first displays a dialog box to get the name of a file to print. If the file name is invalid, the method does nothing. (After all, this is to demonstrate printing!). Once a valid file name is received, we are ready to print. As in the SetPrinter method, an instance of the tPrinter object is created by the line aPrinter := new(pPrinter, Init(hInstance, @self) here, the hInstance represents the current instance of tTestApp. @self represent the tPrnWindow instantiated by tTestApp. The value of these two parameters will be used in the instantiation of the AbortProc method and the print dialog box. The next line calls the Start method: if aPrinter^.Start('PrnTest',hWindow) then ... here, 'PrnTst' is the document name that will be used to uniquely identify this document, and hWindow is the current device context (tPrnWindow). This function call must return true in order for printing to commence. If it returns false, an error message should display, indicating what problem occurred. Once the document has been started, the application can send continuous output to the printer. This is represented by the WHILE..DO loop, following the call to the Start method. This loop reads in the next line of text from the file, and calls the printLine method, passing a pointer to the string as a parameter. When the end of textFile has been reached, the Finish method is called to end the print job. This call results in the print buffer being flushed, and a NewFrame call to advance the page. Finally, the aPrinter variable is disposed, and the job is done. While the print job is in progress, you should notice several things. First, the parent window to which the print dialog belongs has been disabled. Mouse and keyboard input to that window have been inhibited. It is still possible to access other windows on the screen, but the only active portion of the print process is the cancel dialog box. Another thing to notice is that the printing does not start immediatly. In fact, for smaller files, printing won't start until you have returned to the application. This is because Windows and the print manager spool the output to disk or memory, prior to starting output. Finally, note that any changes you make to the printer parameters affect only the current print session (if the driver was written for Windows 3). THE REPORTPRINTER OBJECT The reportPrinter object descends from the tPrinter object. It does not modify any of tPrinter's methods. Rather, it adds some behaviors to tPrinter to change the physical appearance of a printed document. ReportPrinter adds user defined pagination, based on lines per page, and headings that are printed on the top of each page. In the full implementation of this object in another system, it also printed column headings, and a columnar report with totals. The point of the reportPrinter object is to illustrate how the behavior of an object is modified by a descendant. It is intended as an example, not a full implementation of an application. TREPORTPRINTER INSTANCE VARIABLES Heading1 Holds the first heading line. Heading2 Holds the second heading line. lineCount Tracks how many lines have been printed. This variable is used to determine when to advance to a new page. Note that, in this implementation, if a line is wrapped by the Print method, line count is not affected. maxLines Maximum number of lines per page. This variable is set in the Init method. pageCount Keeps track of the page number. This count is included in heading line 2. rDateTime Holds the run date and time of the report. This value is included in heading line 2. METHODS Init Calls the ancestor(tPrinter) Init method to set the application instance and parent values. Init then initializes several other of the reportPrinter instance variables. SetDefaults SetDefaults initializes the values of the two heading lines. Heading1 is set to the value of the passed parameter, heading2 is set to the run date and time by a call to setHeading2. SetHeading2 Initializes heading2 to the run date and time instance variable and the constant PAGE. SetPageNum Strings the current page count into the local variable pCount, then copies it into the proper position in heading2. printMainHeadings Calls setPageNum, then sends heading1 and heading2 to the printer. StartNewPage Page break. If the page is greater than zero, calls new page, then prints the headings. NewPage causes a form feed. In this version of the object, pageCount is initially set to zero. This routine does not issue a form feed for the first page. (I was running out of paper!) OutText Check lineCount against maxLines to see if it is time for a new page. If so, startNewPage is called. The text passed as a parameter is sent to the printer with the tPrinter.PrintLine method, and pageNum in incremented by 1. SetRunTime A method to get the current date and time, format them, and copy them to the rDateTime instance variable. SAMPLE PROGRAM TESTPRN2 This application is an example of the use of the reportPrinter object. The majority of the code is identical to that in TestPrn1, so I will not repeat that discussion. One difference is that the tPrnWindow instance variable aPrinter is now declared to be of type reportPrinter. The other differences are in the instantiation of aPrinter in the body of the program, and the object methods that are called during execution. In the method filePrint, the init call for aPrinter now includes an addition parameter, that for the lines per page. This value sets the reportPrinter instance variable maxLines, which is checked each time the outText method is called. Next, the reportPrinter method setDefaults is called to initialize the headings. The default heading passes is simply the word heading. If a nil value is passes, an empty string will be printer for heading1. The second heading line will be the run date and time, and the page number. The start method is called to begin the document. As the file is read, text is sent to the reportPrinter method outText, rather that the printLine method as was done in the previous example. This is so reportPrinter can manage the lines per page. The balance of the execution is identical to the testPrn1 program. WINDOWS PRINTING TIPS Keep in mind that tPrinter handles text on a line basis; that is, an application sends ready to print lines to the print or printLine methods. Remember that these are printer objects. Their only purpose is to get information from the application to the printer. If the output must be formatted in a special manner, it should be done before the print or printLine methods are called. That is the technique used in the original implementation of reportPrinter. The reportPrinter object formatted the text in to columns, formatted the subtotals and totals received from other objects, and passed a complete line of text to the tPrinter object. The overriding reason for doing this is that you know for certain that if an error in formatting text occurs, it occurs before the line gets to the printer unit. It makes report creation and debugging infinitely easier. Remember also that object-oriented programming takes the black box concept several steps farther. Any object descended from the printer object should concern itself only with printing. Any tasks not required for formatting a line, or printing it out do not belong in a printer object. ENDIT I sincerely hope that these objects, examples and documentation prove useful to your quest for the perfect Windows application. I have learned a great deal about Windows programming while creating them. I look forward to corresponding with you on the Compuserve forum. Happy Computing! -Bob Galivan