PDDR/2 - Font Test 32-Bit Printing Utility

From EDM2
Jump to: navigation, search
Printer Device Driver Reference

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:

#DevQueryCaps General device information
#DevQueryHardcopyCaps Device hardcopy information
#GpiQueryFontmetrics Device font information
#GpiQueryWidthTable Current width table information
#GpiQueryKerningPairs Current kerning pair table information

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:

  • 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.

Notes:

  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:

  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.

Notes

  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:

FT32 [drive:][directory][filename] /? /p

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.

Cancel Exits a dialog box without performing the specified task.
Done Closes the dialog box after you have completed viewing the information.
Help Opens the online help to provide information about the current dialog box.
OK Confirms the selections in the dialog box and begins processing.

Select the OK pushbutton to close the notebook and save any changes made to any page in the notebook. All changes will be applied to the program after the notebook is closed.

The OK push button differs from the Save push button because changes made are lost when the program is closed.

Open Confirms the selection of a file to be opened.
Save Saves the selections in the dialog box as the defaults that will be used for all subsequent invocations of Font Test until the defaults are changed.
Search Begins searching for a specified text string.

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:

  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.

or

  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.

or

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

FT32 <filename>

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:
  1. Select fonts with resolutions that match your printer's resolution, or the fonts will be printed in the incorrect size.
  2. When a new font is selected, its nominal point size is shown in the point size spin button.
  3. 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.
Scalable Point Size This title appears when the selected font can be scaled (point size can be changed) between an upper and 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.

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:
  1. Select an item from the Select Item list. The Select Item's Color color palette will show the current color for Window Text.
  2. Select the color from the Select Item's Color color palette.
  3. 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.
Print Character Boxes Prints character boxes for each character.

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).

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.
Print Dual Column Prints text output in two columns. This is also called 2- up printing.

Recommendations:

  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.
Print File Name Prints the file name at the bottom of each page of output.

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.

Page Numbers Prints the page number at the bottom of each page of output.

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.

Text Border Draws a box around each page of output.

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.

Line Number Creates and prints a line number for each line of printed text output.
Title Text Prints a title at the top of each page.

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.

Title Text
When the Title Text option is selected in the Text Format Options list, 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. Bitmaps 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 occurrence 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 #GetQueueData() 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 #GetDefaultQueueData().

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 #GetQueueData() and #AccessDevice(); 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 #AccessDevice() 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():

Function DC Type (INFO/QUEUED) Action Description
ClientWndProc INIT_DLG

OD_INFO

ACTION_QUERY_FORM_INFO Used to query printer driver about what types of forms it supports for output, their sizes and availabilities.
IDM_QUERY_CAPS

OD_INFO

ACTION_QUERY_CAPS Used to query device capabilities such as resolution (dpi) colors supported etc.
IDMB_QUERY_HCCAPS

IDM_QUERY_HCCAPS

OD_INFO

ACTION_QUERY_HCCAPS Used to query the printer driver about what types of forms it supports for output and the sizes and availabilities of the forms.
IDMB_QUERY_METRICS

IDM_QUERY_METRICS

OD_INFO

ACTION_QUERY_METRICS Used to query fontmetrics of the font currently selected in the printer for its size information.
PrintThread OD_QUEUED ACTION_PRINT_FILE_NO_PM Used to print a file from the command line.
OD_QUEUED ACTION_PRINT_FILE Used to print a file from Font Test's PM interface.
FontThread OD_INFO ACTION_QUERY_FONT Used to query printer driver for all the fonts and designer fontmetrics supported by the current device.

Adding New Tests

The function #AccessDevice(); 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.

  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.

After creating the new test, you can alter the PaintClientWindow() function to display the same bit map to the user on the screen.

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.
Retrieved from "http://www.edm2.com/index.php?title=PDDR/2_-_Font_Test_32-Bit_Printing_Utility&oldid=79454"