PDFlib 8 Windows COM/.NET Tutorial

4.4 String Handling in PDFlib
4.4.1 Content Strings, Hypertext Strings, and Name Strings
PDF and operating system requirements impose different string handling in PDFlib depending
on the purpose of a string. The PDFlib API uses the string types below. All relevant
parameters and options are marked as content string, hypertext string, or name
string in the PDFlib API Reference.
Content strings, hypertext strings, and name strings can be used with Unicode and
8-bit encodings.The details of string handling depend on the language binding, and are
discussed in Section 4.4.2, »Strings in Unicode-aware Language Bindings«, page 109 .
Content strings. Content strings are used to create genuine page content (page descriptions)
according to the encoding chosen by the user for a particular font. All
function parameters with the name text in the PDFlib API Reference for the page content
functions fall in this class. Since content strings are represented with glyphs from a particular
font, the range of usable characters depends on the font/encoding combination.
Examples:
The text parameters of show( ), fit_textline( ), add_textflow( ).
Hypertext strings. Hypertext strings are used for interactive features such as bookmarks
and annotations, and are explicitly labeled Hypertext string in the function descriptions.
Many parameters and options of the functions for interactive features fall in
this class, as well as some others. The range of characters which can be displayed depends
on external factors, such as the fonts available to Acrobat and the operating system.
Examples:
fieldname option of add_table_cell( )
name option of define_layer( )
destname option of create_action( )
text parameter of create_bookmark( )
Name strings. Name strings: these are used for external file names, font names, block
names, etc., and are marked as Name string in the function descriptions.Examples:
filename parameters of begin_document( ) and create_pvf( )
fontname parameter of load_font( )
profilename parameter of load_iccprofile( )
File names are a special case: the option filenamehandling specifies how PDFlib converts
filenames supplied to the API to something which can be used with the local file system.
4.4.2 Strings in Unicode-aware Language Bindings
If a development environment supports the string data type and uses Unicode internally
we call the binding Unicode-aware. The following PDFlib language bindings are Unicode-aware:
> C++
> COM
> .NET
> Java
106 Chapter 4: Unicode and Legacy Encodings (Edition for COM, .NET, and REALbasic)