DTWAIN_AddPDFText

The following function is available only with DTWAIN / PDF.

The DTWAIN_AddPDFText adds text to a PDF page that is acquired using DTWAIN_AcquireFile or DTWAIN_AcquireFileEx.

DTWAIN_BOOL DTWAIN_AddPDFText (

Parameters

Source

Specifies a selected TWAIN Source.

szText

Specifies the text to display on the generated PDF page.

xPos, yPos

Specifies the position, specified in points, of where the text is to be placed on the page.

szFontName

The name of the font to be used for the text.

fontHeight

  The height to use for the font.

fontRGBColor

The color to use for the text, specified as an RGB value.

renderMode

   One of the specified render modes used to display the text.

scaling

   Horizontal scaling factor to use when displaying the text.

charSpacing

Specifies the spacing width between characters.

wordSpacing

Specifies the spacing width between words.

strokeWidth

If renderMode specifies a stroked rendering mode, this parameter specifies the stroke width of the characters.

displayFlags

Specifies which pages to display the text, as well as which parameters from DTWAIN_AddPDFText to ignore when displaying the text.

Return Values:

If the function succeeds, TRUE is returned, otherwise FALSE is returned.

Character specific version

Comments:

The DTWAIN_AddPDFText function adds a line of text to a PDF page that was generated using DTWAIN_AcquireFile or DTWAIN_AcquireFileEx, and DTWAIN_PDF or DTWAIN_PDFMULTI is used as the file type to acquire.  Usage of DTWAIN_AddPDFText can be used to add custom text, page numbers, etc. to each PDF page generated.  You can call DTWAIN_AddPDFText multiple times to add multiple lines of text to a PDF page.

Once the PDF file is generated, the text that is added is removed from the Source.  In other words, your application will need to call DTWAIN_AddPDFText again for each call to DTWAIN_AcquireFile or DTWAIN_AcquireFileEx.

The szText argument is the text to display on the page.

The xPos and yPos arguments determine where the text is placed on the PDF page (specified by (xPos, yPos)).   The xPos and yPos parameters are specified in points, where a point is 1/72 of an inch (i.e. there are 72 points per inch).  So for example, an 8.5" x 11" page has a width of 612 points and a height of 792 points.

The coordinate system used by PDF is based on the lower-left hand corner of the page being location (0, 0).  The x-position increases as you go to the right edge of the page, and the y-position increases as you go up the page.  For example, to place text on the left edge and close to the vertical center of an 8.5" x 11" inch page, the coordinates would be approximately (0, 396).

The szFontName is the name of the font to use for the text.  Currently the only fonts supported are the Adobe 14 fonts, specified below:

In the table above, the column on the left denotes the string name of the font.  This name is the name you would specify in the szFontName parameter. The column on the right is the DTWAIN constant that represents the name, and this constant can be used to get the string name by calling the DTWAIN_GetPDFType1FontName function.

The reason why it may be more desirable for DTWAIN_GetPDFType1FontName to return the name instead of specifying the literal string name is that using DTWAIN_GetPDFType1FontName returns the name without any misspelled or typographical errors..  Since the font name must match exactly with the Adobe 14 font name, calling DTWAIN_GetPDFType1FontName eliminates the chance that the name is incorrect.

For example, the two snippets of code below are equivalent DTWAIN_AddPDFText calls:

1) DTWAIN_AddPDFText( Source, "Some Text", 0, 0, "Helvetica-Bold", ...)

2) char buf[100];

   DTWAIN_GetPDFType1FontName(DTWAIN_FONT_HELVETICABOLD, buf, 100);

   DTWAIN_AddPDFText( Source, "Some Text", 0, 0, buf, ...);

The advantage of 1) is that it takes only a single call.  The disadvantage, even though it isn't shown here, is that when writing code this way leaves a big possibility that the font name was misspelled by the programmer.

The advantage of 2) is that it guarantees that the font name is correct.  The disadvantage is that it takes an additional function call (DTWAIN_GetPDFType1FontName) to return the font name.

The fontHeight argument is the height of the font in points.  Heights of 8, 10, and 12 are normally used, but height can be any integral value.

The fontRGBColor argument denotes the color of the text.  This value is specified by combining the Red (R), Green (G), and Blue (B) components thereby deriving a single color.  The number that is generated from the combination of these colors is the same value used in HTML color values that you may see when you display the HTML of any web page (the color is usually denoted by a six-digit hexadecimal number, #rrggbb, where "rr" is red, "gg" is green, and "bb" is the blue component).

The red, green, and blue components range from 0 to 255 for each component.  There are several ways to generate the RGB color, given the component values of R,G, and B.

1) For Windows C/C++ programmers, the Windows API contains an RGB( ) macro that can be used to generate the color number.

2) For non-Windows programmers, use the DTWAIN_MakeRGB( ) function to generate the RGB value.

Black text has an RGB value where all the components are 0, while white text has an RGB value where all the components are 255.  In between are the various shades of color (for example, gray has values of 127 for all the components).  You can get an idea if you are using Windows, and you display a "Color Picker" dialog:

In the lower right hand corner of the dialog are the Red, Green, and Blue components of the color described in "Color|Solid".

An example:

DTWAIN_AddText(Source, "Some Text", 0, 0, "Helvetica", 12, DTWAIN_MakeRGB( 0, 78, 152 ), ... )

This creates text that has the same color denoted in the sample Color Picker dialog above..

DTWAIN_AddText(Source, "Some Text", 0, 0, "Helvetica", 12, DTWAIN_MakeRGB( 0, 78, 152 ), ... )

This creates text that has a gray color (this is if the DTWAIN_PDFTEXT_NORGBCOLOR is not specified in the displayFlags argument).

The renderMode argument denotes the rendering mode to use when displaying the text.  The rendering mode determines if the text will be solid, shaded, invisible (useful to create a searchable PDF file), "hollow" (stroked), etc.

The various rendering modes and their effect are listed below:

The scaling argument denotes the amount of horizontal scaling to use when displaying the text.  Setting this value adjusts the width of the text that's printed.   For example, a scaling value of 100.0 will leave the text unadjusted, while a scaling of 50.0 reduces the text width by 50%, while a scaling factor of 200.0 will increase the width by twice the normal width.

The charSpacing arguments denotes the space between characters of the words in the text.  This value is denoted in points (there are 72 points per inch), and this value is added to the "natural" spacing between characters.  Please note that this value can be between 0 and 1, meaning that the extra spacing can be finely tuned to a distance less than a point, and that charSpacing can be a negative value, denoting a reduction in the space used between each character.

DTWAIN_AddText(Source, "Some Text", 0, 0, "Helvetica", 12, DTWAIN_MakeRGB( 127, 127, 127 ), 0, 0.25... )

The 0.25 denotes that the extra spacing to add between characters is 1/4th of a point, which is equivalent to 1/288 of an inch (approximately 0.0035 inches).   Please note that the scaling parameter is ignored if displayFlags has set the DTWAIN_PDFTEXT_NOSCALING bit set.

The wordSpacing argument denotes the extra space between words (words are separated by the space (ASCII 32) character).  This value is also specified in points.  Similar to charSpacing this value can be fractional and negative (to reduce the spacing between words).

The strokeWidth argument is only used if renderMode is 1 or 2.  The strokeWidth denotes the width, in points, of the outline of each of the characters.  Usual values are 1, but a thicker line may be desired (a value of 2 or higher).

Page Display Flags

The displayFlags argument denotes two things:

The displayFlags is a combination of two values.  The first value must be the page(s) to print the text.  The following table describes the possible values:

The displayFlags must use only one of the page options above.    Please note: The DTWAIN_PDFTEXT_CURRENTPAGE is only useful if you're processing DTWAIN notifications during a multi-page acquisition, and want to change the text on each page.   See the "SavePDF_PageNumber" example program found in the DTWAIN installation to see how to use the DTWAIN_PDFTEXT_CURRENTPAGE effectively.

Tip:  If you desire to customize exactly which page your text will be placed on, the best way is to use the DTWAIN_PDFTEXT_CURRENTPAGE, and capture the DTWAIN_TN_FILEPAGESAVING notification. This notification is always sent once (and only once) before a PDF page is generated.   Your application should keep some sort of a counter variable within the notification that gets incremented each time DTWAIN_TN_FILEPAGESAVING is sent.  If the counter equals the page number that you want to add text to, call DTWAIN_AddPDFText using the DTWAIN_PDFTEXT_CURRENTPAGE flag.

The second thing that displayFlags denotes is which set of parameters from the parameter list are to be ignored.  The table below lists the possible values:

Therefore, displayFlags is a combination of exactly one page constant, and zero or more parameter constants. For example, if you want text to appear  on the lower-left hand corner of only first page, colored gray, using the Helvetica font, and scaled to 50%, the following would be done:

LONG options = DTWAIN_PDFTEXT_FIRSTPAGE | DTWAIN_PDFTEXT_NOCHARSPACING |

                       DTWAIN_PDFTEXT_NOWORDSPACING | DTWAIN_PDFTEXT_NORENDERMODE |

                       DTWAIN_PDFTEXT_NOFONTSIZE;

DTWAIN_AddPDFText( Source, "Some Text", 0, 0, "Helvetica", 0, DTWAIN_MakeRGB(127,127,127), 0, 50.0, 0, 0, 0, options );

The code above that generates the options value just combines the values using the bitwise OR (C/C++ programmers only).  If your language doesn't have a bitwise OR operator, you can simply add the values together.

When the "Some Text" is displayed, it will be located in the lower left hand corner of the page (position (0,0)), use the "Helvetica" font, and be colored grayed, and scaled to 50%.  The font size, word spacing, character spacing, and render mode arguments are ignored, therefore the default  values are used for these settings.  This means that the font size will be 10 points, the word and character spacing will be 0, and the render mode will be 0.

TWAIN State Transitions

State 4(if Source is not opened)

State 5, 6, 7

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function

See Also

DTWAIN_AcquireBuffered, DTWAIN_AcquireNative, DTWAIN_AcquireFile