PDDR/2 - Font Test 32-Bit Printing Utility

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation =Font Test 32-Bit Printing Utility= Font Test is a 32-bit Presentation Manager application that is used to browse and print text files on local or remote print queues using many formatting options. Font Test also allows you to view various capabilities of the printer attached to a selected print queue including font and hardcopy (form) information.

Font Test provides a way to invoke OS/2 application program interface (API) calls that query presentation drivers for information such as:

Font Test can be used to test presentation drivers because it follows application printing conventions outlined in "Print Job Submission and Manipulation" in the OS/2 Programming Guide, Volume 3. Font Test also performs error assertion on every PM API call that is handled by the presentation driver.

The application printing conventions that Font Test follows include: Notes:
 * Providing a dialog box that allows the user to enumerate and print to OS/2 Print Objects.
 * Providing a dialog box that allows the user to select the page format.
 * Providing a dialog box that allows the user to select any public System or Device fonts.
 * Providing a dialog box that allows the user to change Job Properties for each print job and view information about the device being used for output.
 * Performing queued PM printing by opening the device context (DC) OD_QUEUED using the standard data format PM_Q_STD.
 * Performing WYSIWYGprinting of text for system fonts.
 * Printing using a separate thread.
 * 1) Font Test is 32-bit code requiring OS/2 2.0 or later to run.
 * 2) WYSIWIG output is achieved when system fonts (of matching resolution) are selected on the Font page of the Program Settings notebook. When device fonts are selected, they will be simulated to the screen using a system Courier font and scaled to the correct point size.
 * 3) Extensive online help is provided with Font Test.

Printing a File
To print a file using Font Test, complete the following steps: Notes
 * 1) Select Open File from the File menu.
 * 2) Use the dialog box that opens to select a file. Font Test will display the selected file in the main window.
 * 3) Select Program Settings from the File menu.
 * 4) Select the Printer notebook tab and select a print queue that is connected to the output device on which you will print.
 * 5) Select the Font notebook tab and select a font for displaying and printing the file.
 * 6) Click on the OK push button to close the Program Settings notebook and save your changes for this printout.
 * 7) Select Print File from the File menu.
 * 8) The Confirm Print Information dialog box will open.
 * 9) Click on the OK push button to print the file.
 * 1) If you do not have any print queues (printer drivers) installed, a message that informs you that none exist will be displayed. Create a print queue under OS/2 and try to print again.
 * 2) If your font appears the wrong size, make sure that the font you chose is a scalable font or a font whose resolution matches your printer's.

Font Test can also be invoked to print a file from the OS/2 command line using queue and print options that were saved from Font Test's interface. The command line syntax is:

Using Font Test
This section describes the menu structure, push buttons, and dialog boxes of Font Test.

Menu Structure
Following is the menu structure of Font Test. Most menu options open dialog boxes. Refer to each menu and dialog box description for detailed information about the functions they perform.
 * File Menu:Open File...
 * Program Settings...
 * Printer
 * Font
 * Colors
 * Page Format
 * Default Settings
 * Print File...


 * Query Menu:DevQueryCaps...
 * DevQueryHardcopyCaps...
 * GpiQueryFontmetrics...
 * GpiQueryWidthTable...
 * GpiQueryKerningPairs...


 * Search Menu:Search for Text...
 * Help Menu:Using Help...
 * Help Index...
 * Extended Help...
 * Special Keys...
 * About Program...

Push Buttons
The following push buttons are used in Font Test.

File Menu
The File menu provides functions that allow you to open a file to browse, choose formatting and printer options, and print.

Open File
Open File allows you to open any file accessible to the workstation so that it can be browsed by Font Test.

To open a file into Font Test: or or
 * 1) Select the drive containing the file you want to open from the Drive list.
 * 2) Select the directory containing the file you want to open from the Directory list.
 * 3) Select the file name of the file you want to open from the File list.
 * 4) Click on the Open push button to open the file.
 * 1) Enter the drive, path, and file name of the file in the Open Filename field.
 * 2) Click on the Open push button to open the file.

To pass a file name into Font Test from the OS/2 command line and automatically load the file into the browse window, type:

Program Settings
Program Settings contains a notebook with pages that represent all changeable program settings and preferences.

Printer
The Printer notebook page provides a list of all available Print Queues on your workstation. By selecting a print queue, you are selecting a printer driver and model represented by that queue. The printer driver and model selected will be used as the destination for printouts from the program.

Printer Notebook Page Options
 * Available Print Queues:This field contains a list of all print queues found on or attached to your workstation (local or network accessible).
 * Print Queues are set up with a printer driver, printer model and an output port (for example, LPT1, COM2, or file). The printer driver (assigned to a print queue) can be queried for the printer model's abilities (for example, forms, fonts, or color) and used to format a program's printouts for that model.
 * Print queues are used as a "holding area" for printouts from any OS/2, DOS, or Windows application running under OS/2. Using OS/2's multitasking, these applications run and can print at the same time. The print queue's holding area ensures that only one printout is sent to the printer port at one time.
 * To select a print queue, scroll through the Available Print Queues list and click on the appropriate printer.
 * When a Print Queue is selected the Attached Printer Driver and Attached Device Name are shown on the page representing the printer driver and model for that queue.


 * Job Properties:Selecting this button opens a dialog box that displays the changeable job options for the printer model. Any changes made to a printer model's job property dialog box or other program settings in the notebook will be saved and applied to any printouts from Font Test.
 * The OS/2 API that causes job properties to be displayed is DevPostDeviceModes.
 * Note: Changing the Job Properties in Font Test has no effect on the Job Properties used for any other program.


 * Other Destination:Some network attached Print Queues available for output are not always listed because some networks may not have notified OS/2 that an attached resource (server) has an output queue.
 * Use the Other Destination push button to select such a queue.


 * Attached Printer Driver:This field shows the name of the printer driver installed in the Print Queue selected from the Available Print Queues list.
 * Attached Device Name:This field shows the name of the printer device support that is selected for the printer driver installed in the Print Queue selected from the Available Print Queues list.
 * Note: The attached device can be one of many output devices.

Font
The Font notebook page provides a list of all available fonts on your workstation (system and display fonts) and any printer fonts available for the currently selected print queue's printer.

Changing the font, attributes, or point size from this panel, causes the Font Sample Text window to update its sample text to reflect how the text will look.

Font Notebook Page Options
 * Available Fonts: This list box lists all fonts available from OS/2 and the intended printer or output device.
 * Selecting one of the fonts displayed will format a text file for output. When a font is selected, its font metrics are displayed and nominal point size, font attributes, and other characteristics are updated.
 * To select a font, scroll through the Available Fonts list and select the appropriate font.
 * Notes:
 * Select fonts with resolutions that match your printer's resolution, or the fonts will be printed in the incorrect size.
 * When a new font is selected, its nominal point size is shown in the point size spin button.
 * If a device font is chosen, 8 point Courier will be used for simulating the font in Font Test's file display window.


 * Select Attributes:You can select any combination of attribute check boxes to apply to the currently selected font.
 * The following attributes are available:
 * Italic
 * Underline
 * Strikeout
 * Bold


 * Designer Font Metrics:This box displays measures and attributes that describe the currently selected font. These font metrics display all values in design units for the selected font.
 * Point Size:This box displays the current point size of the font. The font can be scalable or fixed. The spinbutton value can be changed for scalable fonts, but not for fixed fonts.


 * - style="vertical-align: top;"
 * Scalable Point Size||This title appears when the selected font can be scaled (point size can be changed) between an upper an lower limit determined by the font's designer. This font type is often called an outline font.

The font can be scaled because the system knows every line and curve needed to draw every character of the font. Scalable fonts can be resized easily for different resolution devices so that they appear the same on the display and the printer.
 * - style="vertical-align: top;"
 * style="width: 11%;" |Fixed Point Size||This title appears when the selected font can not be scaled because it is made up of bitmaps of each character in the font and designed for a specific resolution. This font type is often called a bitmap font.

Fixed point fonts are often designed for use with the current display driver at a certain resolution. When printed, these fonts cannot be scaled to match the resolution of the printer and will appear to be the incorrect size (often much smaller).

If a fixed point size (bitmap) font is used, the resolution of the font must match the resolution of the intended output device or the font will appear to come out the incorrect size (display and printer resolution must match).
 * }
 * Font Sample Text:This box displays a preview of what the currently selected font will look like when used to display a text file.

Colors
This notebook page allows you to choose the colors that Font Test will use when printing and displaying text files.

Colors Notebook Page Options
 * Select Item:This list box displays all program items with changeable colors.

These items include:


 * Window Text||Color of browse window's text
 * Window Background||Color of browse window's background
 * Printed Text||Color of printed text output
 * Printed Background||Color to fill background of paper (currently not implemented)
 * Text Border||Color of border that is drawn around each page of text output
 * Trailer Information||Color of filename, page numbers, date and time
 * Title Text||Color of printed page title
 * }
 * Select Item's Color:This color palette allows you to choose a color for the selected item in the Select Item list. The colors in this area represent the 16 predefined OS/2 colors that are used by many applications.
 * Changing an Item's Colors:The following steps explain how to change the colors of the elements in Font Test:
 * Select an item from the Select Item list. The Select Item's Color color palette will show the current color for Window Text.
 * Select the color from the Select Item's Color color palette.
 * Click on the OK push button below the notebook.
 * }
 * Select Item's Color:This color palette allows you to choose a color for the selected item in the Select Item list. The colors in this area represent the 16 predefined OS/2 colors that are used by many applications.
 * Changing an Item's Colors:The following steps explain how to change the colors of the elements in Font Test:
 * Select an item from the Select Item list. The Select Item's Color color palette will show the current color for Window Text.
 * Select the color from the Select Item's Color color palette.
 * Click on the OK push button below the notebook.

Page Format
This notebook page allows you to select text format options that will be applied on a per-page basis to your text file when it is printed.

Page Format Notebook Page Options
 * Text Format Options:The Text Format Options window lists all the text format options that are applied to printouts. Multiple items in the list can be selected. If an entry is highlighted it is considered selected. The following list explains the options that are available in this list box.

Note: Selecting this option causes printing time to increase considerably and should only be used to test new fonts to determine whether their characters will be printed correctly when clipping is applied (clipping text is based on character boxes). Recommendations:
 * - style="vertical-align: top;"
 * style="width: 14%;"|Print Character Boxes||Prints character boxes for each character.
 * Print Current Date||Prints the current system date at the bottom of each page of output.
 * Print Current Time||Causes the current system time to be printed at the bottom of each page of output.
 * - style="vertical-align: top;"
 * 'Print Dual Column||Prints text output in two columns. This is also called 2- up'' printing.
 * - style="vertical-align: top;"
 * 'Print Dual Column||Prints text output in two columns. This is also called 2- up'' printing.
 * 1) Select Landscape paper orientation from the job properties for the printer queue (object) being used.
 * Select 8 pt font (or less) so that 80 column text files will print in dual column mode without truncation.

Note: When Print Dual Column is selected, two logical pages are printed on one piece of paper. Therefore, the file name will be printed on both of the logical pages. Note: When Print Dual Column is selected, two logical pages are printed on one piece of paper. Therefore, a page number will be printed on both of the logical pages. Note:When Print Dual Column is selected, two logical pages are printed on one piece of paper. Therefore, the text border will be printed on both of the logical pages. Note:When Print Dual Columnis selected, two logical pages are printed on one piece of paper. Therefore, a title will be printed on both of the logical pages.
 * - style="vertical-align: top;"
 * Print File Name||Prints the file name at the bottom of each page of output.
 * - style="vertical-align: top;"
 * Page Numbers||Prints the page number at the bottom of each page of output.
 * - style="vertical-align: top;"
 * Text Border||Draws a box around each page of output.
 * Line Number||Creates and prints a line number for each line of printed text output.
 * - style="vertical-align: top;"
 * Title Text||Prints a title at the top of each page.
 * Title Text||Prints a title at the top of each page.
 * }
 * Title Text:When the Title Text option is selected in the Text Format Optionsl ist, you can type a title in this entry field. This title will be printed on the top of each logical page.
 * Title Alignment:Use the Title Alignment buttons to control the placement of the title at the top of each logical page printed.

Default Settings
Use the Default Settings menu item to reset all saved Program Settings to their defaults.
 * Printer:Uses the default print queue that is checked in the Set Default option accessed from the context menu of any OS/2 print queue.
 * Font: Defaults to a scalable, 8 point Courier font (or the closest match).
 * Colors: Defaults the window to black text on a white background and defaults printing to black text on a white background.
 * Format:Defaults all page format options to disabled (off).

Print File
This menu choice opens a dialog box that allows you to review the file you are going to print and the details of the output device on which it will be printed.

This dialog box provides you with a final opportunity to modify job properties, text format, and color options that will be applied to the file when it is printed. If you want to change any of the option, select the Review Settings push button to display the Program Settings dialog box.

Query Menu
The Query menu displays the names of OS/2 API calls that query the currently selected print queue for information about the attached printer. Selecting any of the APIs listed will cause Font Test to execute the API call to the selected output device and display the results in a dialog box.

DevQueryCaps
DevQueryCaps is an OS/2 API call that queries many different capabilities of an output device such as resolution and color capabilities. Select this menu item to query the device connected to the selected output queue for its capabilities.

Following are some examples of the capabilities that can be queried:
 * CAPS_DRIVER_VERSION:Version of device driver
 * CAPS_TECHNOLOGY:Raster, vector, or PostScript device
 * CAPS_COLORS:Number of colors supported by the device

DevQueryHardcopyCaps
DevQueryHardcopyCaps is an OS/2 API call that queries an output device for information on what types of output media are available for hardcopy output. Select this menu item to query the device connected to the selected output queue for its hardcopy capabilities.

A dialog box that lists the forms available on your output device and displays size information about the currently selected form will open.

Examples of hardcopy types include:
 * Paper:Typical output for printer and plotters.
 * Transparencies:Supported on some printers and many plotters.
 * Image File:Supported by some programs whose output device is the screen. Bit maps are an example.
 * Film:Film recorders.
 * Circuit boards:Laser etching machines.

GpiQueryFontmetrics
GpiQueryFontMetrics is an OS/2 API call that is used to query the current printer and display drivers for the font metrics (measurements) that would be used when printing or displaying the current font. Select this menu item to query the currently realized font metrics information of the file.

These font metrics represent any changes made to the font from the Font page of the Program Settings notebook

The Font Metrics displayed in the Font page are really displaying designer units. Designer units are the height and width values for a font if it is realized at its nominal point size. Outline fonts can be realized at any point size between their minimum and maximum point sizes, and their heights and widths are scaled accordingly.

GpiQueryWidthTable
GpiQueryWidthTable is an OS/2 API call that queries the current printer for the widths of all characters that make up the current font. These widths reflect the individual space each character in the font's character set will occupy. These values reflect any changes to the font's point size or font attributes. Select the GpiQueryWidthTable menu item to query the current font's character width table.

GpiQueryKerningPairs
GpiQueryKerningPairs is an OS/2 API call that queries the current printer for any kerning pairs defined for the current font. These kerning pairs reflect adjustments to character widths that are made when certain characters are printed next to each other. Select the GpiQueryKerningPairs menu item to query the current font's kerning pair table. This table shows adjustments made to characters when they appear next to another character when displayed or printed to make the combination more visually appealing.

Search
The Search displays a the Search for Text menu item.

Search for Text
Use Search for Text to display a dialog box in which you can enter a text string to search for in the open file. If the search string is found, the text line it is found on will be advanced to the top line in the window.

The default search is case-insensitive and can be changed to case-sensitive. Check the Case Sensitive check box to perform a case-sensitive search.

Use Ctrl-F to find next occurrence of same search string.

Help
Font Test help can be obtained in three ways:
 * Press the F1key.
 * Select the Help button from any panel where it appears to open the online help for that topic.
 * Select the Help menu for different types of help.

Using Help
Select this menu item to for an explanation of how to obtain help.

Help Index
Select this menu item to view a list of all available help topics.

Extended Help
Select this menu item to view the main help panel for using Font Test.

Keys Help
Select this menu item for an explanation of all keys that have special functions under Font Test.

The following keys/key combinations have special meanings to Font Test.
 * F1:Displays help topic for selected item
 * F3:Ends Font Test
 * CTRL-O:Brings up Open File dialog
 * CTRL-P:Prints currently opened file
 * SHIFT-PrintScreen:Prints currently opened file
 * CTRL-S:Brings up Text Search dialog
 * CTRL-F:Searches for the next occurrance of the search string

About
Select this menu item to view information about Font Test including author, icon, abstract, and copyright.

Driver Details
This section provides specific information about how Font Test handles printing and queues, job properties, and call sequences. It also describes how you can modify the source code of Font Test to add functionality and how to debug your additions.

Printing and Queues
The use of print objects (queues) offers the most flexibility to users printing Presentation Manager applications under OS/2.

For example, although a user may have only one printer and one port, two print objects can be created under OS/2, each with a separate set of job and printer properties. One queue could be created for portrait printing and the other for landscape printing. The user can name the queues "My Printer Portrait" and "My Printer Landscape". From an application, the user will see both queues as possible output destinations. Simple dynamic switching between portrait or landscape printing can be achieved by selecting the queue that will produce the desired orientation.

Because of print queues, the user need not change job properties or change hardware switches on the printer to change printing orientation.

The Font Test function FillQueNameListBox, located in FT32HELP.C, shows one method of enumerating and displaying all local and network OS/2 print objects (queues).

Note: The queue description displayed under each print object can be changed by the user. The update will not be reflected in pszComment field of the PRQINFO structure, but the actual queue name (pszName) in the structure will always remain the same. Therefore, from invocation to invocation, applications should store and reference the real name instead of the comment name.

When a queue is selected, an application must retrieve information about the target printer driver prior to printing or querying device capabilities.

The Font Test function shows how this data is retrieved as soon as a print object name has been selected by a user. If the user has not selected a specific queue or if a print object is not found, the queue data for the system default print object is retrieved in the function.

Note: Only one system default print object (queue) exists.

Handling Job Properties
Job properties are unique settings that tell an OS/2 printer driver how to format a print job. The job properties are not directly manipulated by an application because the format of job property data varies among print drivers (and devices within drivers).

Managing job properties from an application should begin with the print object. Knowing what print object a user intends to use for printing allows a developer to retrieve the job properties that have already been selected by the user for that print object (queue). Using these job properties as a starting point, the application can call the DevPostdeviceModes; to cause the printer driver to display its unique job property panels. The queues' job property data can be passed into this call so that the panels resemble what would be seen from the queue.

Assuming that the user probably wants to use these settings whenever the application prints, the application can be written in such a way as to store these job properties in an INI file upon returning from the call to DevPostdeviceModes;.

The Font Test functions and ; show how these job property manipulations are handled.

Notes:
 * 1) Job property data is significant both for printing to and querying information from an OS/2 printer driver. Therefore, the job property data that will be used for printing should be passed in even on queries to an OS /2 driver. This information can help the printer driver provide the most accurate answers to an application's query.
 * 2) Applications should never call DevPostDeviceModes to display or alter Printer Properties because the changes affected by such a call are system wide and could alter another applications behavior. Only Print object should call DevPostDeviceModes.

Call Sequences
The function provides an example of all the OS/2 APIs that must be called to correctly open a device context (DC) for an OS/2 presentation driver.

This function can be reused whenever an application must query device capabilities, query a device for fonts, query a device for form information, query or display job properties, and print.

The following Font Test functions call AccessDevice:

Adding New Tests
The function ; provides a generic way of opening a printer DC. As soon as this printer DC is opened, drawing and querying to that printer is possible through Gpi and Dev API calls.

Currently, Font Test uses AccessDevice to print text files and to query forms, fonts, and capabilities by passing in "ACCESS_" flags and executing different sets of code.

For example, AccessDevice can be called with the flag "ACTION_PRINT_FILE". Within AccessDevice, the flag "ACTION_PRINT_FILE" causes the function PrintTextFile to be called. PrintTextFile uses Gpi commands to draw to the printer DC.

Additional printing routines and queries within the AccessDevice code can be added in a similar way. For example, you can add a test that allows the user to print a bit map. The following procedure provides an example of how to add this test. After creating the new test, you can alter the PaintClientWindow function to display the same bit map to the user on the screen.
 * 1) Provide a method for the user to invoke this new function, such as a menu item.
 * 2) Create a new ACTION_ flag, such as ACTION_PRINT_BITMAP, to pass into AccessDevice whenever the new bit-map function is invoked.
 * 3) Write a new function, such as PrintBitmapFile;.
 * 4) Add a check to AccessDevice for the ACTION_PRINT_BITMAP flag that calls the PrintBitmapFile; function.
 * 5) Within the new function PrintBitmapFile, make use of GpiWCBitBlt to draw a bit map to the printer DC.

Note: GpiWCBitBlt is preferred over GpiBitBlt because GPiWCBitBlt is always metafiled, but only one GpiBitBlt can be metafiled per document.

Debugging
Font Test's makefile creates a debug version by default when nmake is entered from an OS/2 command line.

The debug version is created with debug and codeview options so that 32-bit debuggers, such as IPMD, can be used to source-level debug Font Test.

In general, Font Test asserts every return code from every Win, GPI, and Dev call. If the return code indicates some type of failure, an OS/2 message box is displayed. The message box lists the failing API, the return code, the result of WinGetLastError, and an interpretation of the failure if possible.

The error assertion routine is called PMAssert; and is located in the module FT32HELP.C. This routine can be modified to include other debug information.

To create a "retail" or non-debug version of Font Test enter nmake ndebug=1 from an OS/2 command line.

Note: The error code displayed from WinGetLastError corresponds to named errors that are defined in PMERR.H from the OS/2 Toolkit and documented in the OS/2 PM Programming Reference Volume 3.

Important Functions
Three functions are described here because of their importance in Font Test. Each function contains a description and a control flow. The control flow is pseudo code that explains the structure and implementation of major function calls.

AccessDevice
AccessDevice is the main function allowing access to a device. This access allows printing text files, querying device fonts, querying device caps, and querying device hardcopy caps.

Control Flow
 * 1) Call GetQueueData; to get driver data.
 * 2) If printing from Presentation Manager, display the Confirm Print Information dialog box to verify queue, font, color, and text format options.
 * 3) Call DevOpenDC; to open the output device.
 * 4) Query device or print to it based on input parameter "usActionType".
 * Possible Actions
 * ACTION_PRINT_FILE
 * Print text file from PM interface.
 * Call DevEscape( DEVESC_STARTDOC ).
 * Call PrintTextFile.
 * Call DevEscape( DEVESC_ENDDOC ).
 * ACTION_PRINT_FILE_NO_PM.
 * Print text file from an OS/2 command line.
 * Call DevEscape( DEVESC_STARTDOC ).
 * Call PrintTextFile.
 * Call DevEscape( DEVESC_ENDDOC ).
 * ACTION_QUERY_FONT
 * Call GpiQueryFonts.
 * Display the Font notebook page.
 * ACTION_QUERY_CAPS
 * Call DevQueryCaps.
 * Display Device Capabilities dialog box.
 * ACTION_QUERY_HCCAPS
 * Call DevQueryHardcopyCaps.
 * Display Device Form Information dialog box.
 * ACTION_QUERY_FORM_INFO
 * Call DevQueryHardcopyCaps.
 * Return index of HCCAPS_CURRENT form in HCINFO structure.
 * ACTION_QUERY_METRICS
 * Call GpiQueryFontmetrics; for currently realized font. Display Current Font Metrics dialog box.
 * 5.Call DevCloseDC; to close device context.

GetDefaultQueueData
If the user never selects a queue, this routine will be called to search the OS2.INI file for the system default queue.
 * Control Flow:Query OS2.INI for default queue information.

GetQueueData
This function is called to access a device on a queue to retrieve all details, such as the driver printer names, about that queue.

Control Flow
 * 1) Call GetDefaultQueueData; if no queue is selected.
 * 2) Check for server information.
 * 3) Call SplQueryQueue; to get driver data from queue.