Version | Date | Comments |
2.0.0 | 11.29.00 | Version 2.0.0 documentation reflects code changes from code Version 1.1.0. (Note: Documentation and code version numbers are designed to be independent of each other, and may not agree.) |
Notice
The information contained in this document is subject to change without notice.
Hewlett-Packard makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.Hewlett-Packard shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.
All SDK documentation included in this list, received with the Hewlett-Packard Appliance Printing Software Development Kit, or received at a later date as a result of communication with any Hewlett-Packard employee regarding the Hewlett-Packard Appliance Printing Software Development Kit, is Hewlett-Packard "confidential" information.
Licensee shall not export or re-export the Hewlett-Packard documentation, or copies or variations thereof. Licensee may use Hewlett-Packard documentation only to develop Licensee Printer Drivers for exclusive use only on Hewlett-Packard printers.
Licensee shall assure that all Hewlett-Packard Software and all documentation based on Hewlett-Packard Documentation include the following notice:
"Copyright © [year]
Hewlett-Packard Company.
All Rights Reserved."
Hewlett-Packard Documentation has been developed entirely at private expense and is provided as "Commercial Computer Software" or "restricted computer software." Use, duplication or disclosure by the US Government or a US Government subcontractor is subject to the restrictions set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clauses in DFARS 252.227-7013 or as set forth in subparagraph (c) (1) and (2) of the Commercial Computer Software-Restricted Rights clauses in FAR 52.227-19, as applicable. The Contractor is Hewlett-Packard Company, 3000 Hanover Street, Palo Alto, California 94304.
Copyright ă 2000
Hewlett-Packard Company.
All rights reserved.
This document provides the information needed to understand the relationship between Device-based text and the Hewlett-Packard Appliance Printing Software Development Kit (SDK). Device-based text is simply font types that are built into the printer. The availability of built-in fonts depends on the printer model and print mode. (In some modes, no fonts are available.)
Rather than rendering text on the host system, text can be sent as a stream of ASCII codes, to be rendered by the printer firmware using one of its built-in fonts. Device-based text can often result in much sharper output depending on the host system facilities for rendering text at high resolutions and merging with graphics. Learn more about device-based fonts by reviewing the following topics.
Enumerating the Available Fonts Realizing the Desired Font Page Formatting and GetTextExtent TextOut The X Coordinate The Y Coordinate Additional Information / See Also
Device-based are accessed by an assortment of functions that allow page positioning of textual strings, and access to certain font treatments such as fixed vs. proportional spacing, text size, and bold, italic or underline.
The advantages of using device-based text depend on the font rendering capabilities of the host system. In other words, device-based text is more advantageous for host environments that do not have a font rendering engine and instead rely on a set of pre-rendered bitmap fonts stored in memory. These pre-rendered fonts are typically stored at screen resolution (72 dpi,) and print relatively poorly. Use of the device-based fonts offers a dramatic increase in print quality.
Another advantage of using device text is speed - especially in cases where the print document is text-only. Compared to raster data, the printer driver has very little processing to perform on device text. Since device text is sent in ASCII format, the amount of data sent to the printer is much smaller and therefore can be sent more quickly. The printer is also able to store more text in ASCII format in its buffers and process the text more quickly.
The disadvantages of using device text are found in flexibility and formatting. Some calculations must be performed by the host system for page layout including scaling device text to the right size, and properly lining up device text and image graphics data. In addition, only a limited range of text sizes are available. Depending on the printer model, these are usually in the 6 to 14 point range, making ideal page formatting potentially a little more difficult. However, larger text can be achieved by sending it as part of the image data while the smaller text remains device-based. For readability, it is more important that smaller text be of higher quality.
The following device fonts are supported by Hewlett-Packard DeskJet printers:
Treatments available for these fonts:
Courier (Fixed Pitch/ Serif) – 6, 12, 24 pitch
LetterGothic (Fixed Pitch/ Sans-Serif) – 6, 12, 24 pitch
CGTimes (Proportional/ Serif) – 6, 8, 10, 12, 14 point
Univers (Proportional/ Sans-Serif) – 6, 10, 12, point
Bold, Italic, Underline
Using device-based fonts entails using some or all of the following API functions:
PrintContext::EnumFont | PrintContext::RealizeFont |
Font::GetName | Font::IsBoldAllowed |
Font::IsItalicAllowed | Font::IsUnderlineAllowed |
Font::IsColorAllowed | Font::IsProportional |
Font::HasSerif | Font::GetPitch |
Font::GetTextExtent | Job::TextOut |
For more information on these and other API functions, refer to the API document.
A typical usage scenario might be to first find the fonts available (if any), by implementing an EnumFont while loop and querying the reference font for its properties. The pass-by reference iCurrIdx will be returned to 0 after a full cycle of the available fonts. Note ‘thePC’ is a pointer to a previously instantiated PrintContext object. The following code sample looks for proportionally spaced font and a fixed pitch font that are sans-serif:
int PropSerifIdx = 0;
int FixedSerifIdx = 0;
int iCurrIdx = 0;
ReferenceFont* currFont = NULL;
while( currFont = thePC->EnumFont( iCurrIdx)) != NULL )
{
if ( (currFont->IsProportional() == TRUE) &&
(currFont->HasSerif() == FALSE) )
{
PropSerifIdx = iCurrIdx;
break;
}
if ( (currFont->IsProportional() == FALSE) &&
(currFont->HasSerif() == FALSE) )
{
FixedSerifIdx = iCurrIdx;
break;
}
}
Once the type of font is found that has the desired attributes, its index value (in this example, PropSerifIdx), is used to ‘realize’ an actual font object as shown in the following code fragment. Refer to the RealizeFont API reference for the complete function.
Font* fntPropSerif = thePC->RealizeFont( PropSerifIdx, … )
Multiple fonts may be instantiated at one time via this mechanism creating some flexibility in implementation; developers may choose to realize only a few font styles such as a proportional font and a fixed pitch font, and change treatments (i.e. bold on/off,) on the fly by manipulating public variables in the font class (fntPropSerif->bBold = TRUE).
Developers may also choose to realize font objects [font style & treatment] for each or several of the text objects on the page ahead of time. Creation of this font list or array would allow walking down the page and simply sending the correct font where applicable. This is more applicable when a set number of fonts/treatments are expected, as system resources may prohibit having too many font objects instantiated at one time. These implementation decisions are of course on a system by system basis.
Proper page formatting requires the host to know how much space the text string takes up. This is necessary in order to find out if the text will fit on one line or if it will overlap a graphic object on the page. For this purpose, GetTextExtent will accept a text string and return its length and height, (the number of printer pixels from the baseline to the top of the tallest character of this string based on the font and size on a 300 dpi grid). Tracking this length and height is vital to correct placement of text on the page. Each TextOut call will require page placement coordinates.
TextOut is THE function for sending a device text string to the printed page. TextOut is conceptually quite simple, taking as parameters the text string, number of characters in the string, font, and x & y coordinates. The coordinates x & y specify the text currently being sent to the printer. The baseline is the invisible line upon which the line of text rests; the descender of a character (like y or g) hangs below this baseline. The x & y coordinates are of course critical to the correct layout of a page.
The x coordinate is used for text placement across the width of the page and is extremely relevant when text is being placed next to a graphic, or if multiple text strings are placed on the same line. Because text may have different attributes (such as a word in the middle of a line being Bold,) it may require several TextOut calls to compose this line. Example:
This is a sample line of text with a Bold text string in the middle.
In this example, the first part of the line is sent via TextOut at the left margin (x = 0). Next is a call to TextOut for the Bold text string for which the x coordinate is based off the length of the first text string. The final text string is again normal text and its x coordinate is based off the length of the two previous TextOut calls. The length of these strings is made available by first calling GetTextExtent with each of these strings, as described previously in GetTextExtent.
The y coordinate is used for text placement along the height of the page. Two important factors exist for the Y placement of text; both relate to remembering that the Y coordinate is at the baseline (not the top) of a piece of text.
First, recall that GetTextExtent returned a height value. This is the number of printer pixels from the baseline to the top of the tallest character for the string, based on the font and size. For proper placement of consecutive lines of text, the Y coordinate used must allow for the height of the string and a few pixels of spacing (or leading) between the lines of text. If this calculation is not performed correctly, the consecutive lines of text will appear scrunched together or may overlap.
As a result of the Y coordinate (baseline) being at the bottom of the text string, it is important that the text be sent early enough for the printer to factor this in before printing the top portion of the text. The printer’s memory buffer is capable of storing an entire page of text, so if the host’s page formatting code allows all of the device text to be sent ahead of time, this may be a preferable option.
In other systems, the page formatter may only look at one band of data at a time in order to format a mixed device-text and raster-graphics print job. In such cases it is a common error to send the text "too late". Each row of raster data sent to the printer (SendRaster) will increment the printer mechanism in order to print the row. As mentioned, if the TextOut call is not made soon enough to compensate for the height of the text, the top portion of the text may be clipped and the printer will print only the lower section of text as determined by the current position of the mechanism on the page.
For a more in-depth description of the individual API functions and specific usage info, please refer to the API document.
For more information on Device-Based Fonts within the code, refer to the Sample Code document.