This directive allows you to accomplish the same thing you could do in the driver dialogs manually, i.e. define a bookmark template that automatically creates bookmarks based on matching a set of font attributes in the file. The directive is the same as that for the Explicit Bookmark Template Definition, except that it also specifies the font attributes to be used to automatically identify text within the document for the creation of implicit bookmarks.
//PDFX,Bookmarks.DefineTemplate, ID, parentID, dspColor, dspAttributes}, matFlags, matFont, matStyle, matSize, matDelta, matColor
Parameters
ID, parentID, dspColor and dspAttributes are the same as for Explicit Bookmark Template Definition.
Symbol |
Values |
Description |
|---|---|---|
matFlags |
Specifies which attributes will be used to implicitly identify bookmarks in the text. Choose one or more of the following: |
|
1 |
If this bit is set, the font name specified is used by the matFont parameter to determine all matching text/strings. matFont may not be NULL or an empty string when this flag is set. |
|
2 |
If this bit is set, the font style specified is used by the matStyle parameter to determine all matching text/strings. |
|
4 |
If this bit is set, the font size specified is used by the matSize and matDelta parameters to determine all matching text/strings. Text with the font size nDet_Size ± matDelta matches and is therefore added as a bookmark item. See warning in Comments below. |
|
8 |
Match on text color (RGB) |
|
matFont |
|
Specifies the name of the font to be matched against. |
matStyle |
Specifies the font attributes to be matched against, from the following choices: |
|
0 |
Normal |
|
1 |
Bold |
|
2 |
Italic |
|
3 |
Bold Italic |
|
matSize |
|
matSize (+/- matDelta) specifies the size of the font to be matched against, in tenths of points (e.g. 100 = 10.0 point). See Comments for warning on font size matching. |
matDelta |
|
Specifies a font size range, in tenths of points, to use in conjunction with matSize to identify implicit bookmarks by the font size. See warning note above. |
matColor |
|
Specifies an RGB value (using hex notation, i.e. &hBBGGRR, as for dspAttributes) to match against. See Comments for additional notes. |
Comments
Note that while the implicit bookmark method may appear to offer advantages over the explicit method described in the previous topics, in practice the explicit method is probably easier to use and actually requires fewer directives (one for each explicit bookmark, vs. at least two to change the font and then change it back, or four if color matching is involved.)
Font size matching warning: when specifying fonts in a document (see //SETFONT), the requested size is only used as a hint to the font mapper, and furthermore different fonts measure their heights in different ways, so matching against font size is inherently imprecise and therefore unreliable. You can partly make up for that by using the matDelta value to effectively create a range of sizes to match against, but this is only practical for fonts whose sizes are sufficiently different from every other font size to allow for a margin of imprecision without overlap. (For this reason, matching against other attributes will be more reliable.)
Color matching is actually the most precise way to match text, provided you use the //SETTEXTCOLOR directive judiciously to associate specific RGB color values with specific types or levels of bookmarks. Note that unlike the case with matSize, the matColor value is exact, so you can create colors that are distinct to the bookmark matching logic but seem the same to the naked eye. (For example, &h010101 will look just as black as &h000000 to the human eye.)
Examples
//;Define top level template (ID 1); match on Cambria font (any size,color,style))
//PDFX,Bookmarks.DefineTemplate,1,0,&h000000,0,1,”Cambria”
//;Define second level template (ID 2), match on any RED text
//PDFX,Bookmarks.DefineTemplate,2,1,&h000000,0,8, ,0,0,0,&h0000ff
Compatibility
Requires PDFXv5+.
