# Tutorial: iText by Example

## Viewerpreferences, Pagelabels, Optional Content and Bookmarks

Viewerpreferences:
Every end user can change his viewerpreferences in Acrobat, but as producer of PDF documents, you can add some viewerpreferences to the document. This can be done with the method setViewerPreferences(). The parameter can be composed by ORing some of the constants that are explained below:

    writer1.setViewerPreferences(PdfWriter.PageLayoutTwoColumnLeft);
    writer2.setViewerPreferences(PdfWriter.HideMenubar
    	| PdfWriter.HideToolbar);
    writer3.setViewerPreferences(PdfWriter.PageLayoutTwoColumnRight
    	| PdfWriter.PageModeFullScreen
    	| PdfWriter.NonFullScreenPageModeUseThumbs);
    writer4.setViewerPreferences(PdfWriter.DisplayDocTitle);

Example: java com.lowagie.examples.objects.bookmarks.ViewerPreferences
Creates three versions of the same document, but with different viewerpreferences: see TwoColumnLeft.pdf HideMenuToolbar.pdf FullScreen.pdf WithTitle.pdf
This is the list with viewerpreferences that are supported in iText:

- The page layout to be used when the document is opened (choose one).
  - PageLayoutSinglePage - Display one page at a time. (default)
  - PageLayoutOneColumn - Display the pages in one column.
  - PageLayoutTwoColumnLeft - Display the pages in two columns, with oddnumbered pages on the left.
  - PageLayoutTwoColumnRight - Display the pages in two columns, with oddnumbered pages on the right.
- The page mode how the document should be displayed when opened (choose one).
  - PageModeUseNone - Neither document outline nor thumbnail images visible. (default)
  - PageModeUseOutlines - Document outline visible.
  - PageModeUseThumbs - Thumbnail images visible.
  - PageModeFullScreen - Full-screen mode, with no menu bar, window controls, or any other window visible.
  - PageModeUseOC - Optional content group panel visible
- HideToolbar - A flag specifying whether to hide the viewer application's tool bars when the document is active.
- HideMenubar - A flag specifying whether to hide the viewer application's menu bar when the document is active.
- HideWindowUI - A flag specifying whether to hide user interface elements in the document's window (such as scroll bars and navigation controls), leaving only the document's contents displayed.
- FitWindow - A flag specifying whether to resize the document's window to fit the size of the first displayed page.
- CenterWindow - A flag specifying whether to position the document's window in the center of the screen.
- DisplayDocTitle - A flag specifying whether to display the document's title in the top bar.
- The predominant reading order for text. This entry has no direct effect on the document's contents or page numbering, but can be used to determine the relative positioning of pages when displayed side by side or printed n-up (choose one).
  - DirectionL2R - Left to right
  - DirectionR2L - Right to left (including vertical writing systems such as Chinese, Japanese, and Korean)
- The document's page mode, specifying how to display the document on exiting full-screen mode. It is meaningful only if the page mode is PageModeFullScreen (choose one).
  - NonFullScreenPageModeUseNone - Neither document outline nor thumbnail images visible
  - NonFullScreenPageModeUseOutlines - Document outline visible
  - NonFullScreenPageModeUseThumbs - Thumbnail images visible
  - NonFullScreenPageModeUseOC - Optional content group panel visible

Go to top of the page
Pagelabels:
If you set the viewerpreferences to mode PageModeUseThumbs, you get a 'thumbnails' view of you document, showing a small version of every page. Under each thumbnail, you have a label. If you want to change the style of these page labels, you have to create a PdfPageLabels object and add a new style, content or pagenumber value, starting from a certain 'real' pagenumber.
These are the different styles you can use:

- PdfPageLabels.DECIMAL_ARABIC_NUMERALS
- PdfPageLabels.UPPERCASE_ROMAN_NUMERALS
- PdfPageLabels.LOWERCASE_ROMAN_NUMERALS
- PdfPageLabels.UPPERCASE_LETTERS
- PdfPageLabels.LOWERCASE_LETTERS
- PdfPageLabels.EMPTY

    pageLabels.addPageLabel(1, PdfPageLabels.LOWERCASE_ROMAN_NUMERALS);
    pageLabels.addPageLabel(5, PdfPageLabels.DECIMAL_ARABIC_NUMERALS);
    pageLabels.addPageLabel(8, PdfPageLabels.DECIMAL_ARABIC_NUMERALS, "A-", 8);

The first line says that the labels starting on the 'real' page 1 should be lowercase roman numerals. The second line says that the labels starting on the 'real' page 5 should be arabic numerals. The labels will start at 1, so the real page 5 will be labeled with the the 'logical pagenumber' 1. The third line says that the labels starting on the 'real' page 8 should be arabic numbers, prefixed with the String "A-". The logical numbering should start with page 8 (otherwise the first label would be "A-1").
Example: java com.lowagie.examples.objects.bookmarks.PageLabels
Creates a document with pagelabels: see PageLabels.pdf
Go to top of the page
Optional Content:
If you set the viewerpreferences to mode PageModeUseOC (only since PDF version 1.5), you will be able to turn on or off different layers in the document. You can read all about these layers in the chapter on Optional Content.
Example: java com.lowagie.examples.objects.bookmarks.Layers
Creates a document with text in different layers: see Layers.pdf
Go to top of the page
Bookmarks:
If you set the viewerpreferences to mode PageModeUseOutlines, you get an outline tree that can be used as a Table-Of-Content or as a list with bookmarks. To construct this outline tree, you need to get the rootoutline from the writer object. To this root, you can add, new PdfOutline objects:

    PdfOutline root = writer.getDirectContent().getRootOutline();
    new PdfOutline(cb.getRootOutline(), someDestination, "a bookmark");

In the next section, you will learn how to create objects such as 'someDestination'. In the example below, we use PageEvents to add an entry to the outline tree every time a new Paragraph is added to the document.
Example: java com.lowagie.examples.objects.bookmarks.Bookmarks
Creates a document with Bookmarks for every new Paragraph that is added: see Bookmarks.pdf
Go to top of the page
Creating Destinations:
In the chapter on Anchors, we already defined destinations, by giving a name to a Chunk object (setLocalDestination). The position on the page of this Chunk defined the destination.
In this section, we are going to create destinations of the types: Destination.XYZ, Destination.FIT, Destination.FITH, Destination.FITV, Destination.FITR, Destination.FITB, Destination.FITBH or Destination.FITBV, using one of the following constructors:

- public PdfDestination(int type) can be used for types FIT and FITB. FIT points to the current page, with its contents magnified just enough to fit the entire page within the window both horizontally and vertically. FITB does the same, but the contents are magnified just enough to fit its bounding box.
- public PdfDestination(int type, float parameter) can be used for types FITH, FITV, FITBH and FITBV.
  If type equals FITBV, the height of the bounding box of a page will fit the window of the Reader. The parameter will specify the x coordinate of the left edge of the window.
  If the type equals FITV the height of the entire page will fit the window and the parameter will specify the x coordinate of the left edge.
  If type equals FITBH, the width of the bounding box of a page will fit the window of the Reader. The parameter will specify the y coordinate of the top edge of the window.
  If the type equals FITH the width of the entire page will fit the window and the parameter will specify the y coordinate of the top edge.
- public PdfDestination(int type, float left, float top, float zoom) can be used for type XYZ with the coordinates (left, top) as the top-left corner of the destination window and the contents of the page magnified by the factor zoom. A negative value for any of the parameters left or top, or a zoom value of 0 specifies that the current value of that parameter is to be retained unchanged.
- public PdfDestination(int type, float left, float bottom, float right, float top) can be used for type FITR the destination will be a rectangle specified by the coordinates left, bottom, right, and top. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the rectangle within the window in the other dimension.

When a destination is created, it is not linked to a certain page in the document. Only when add the destination the outline tree, it will point to the 'current' page. In the chapter on Anchors, we already used some destinations in Actions. Now we are going to use destinations as targets for our bookmarks. We will draw several crosses on a page and jumps to these crosses from the outline tree.

    PdfDestination d1 = new PdfDestination(PdfDestination.XYZ, 300, 800, 0);
    PdfDestination d2 = new PdfDestination(PdfDestination.FITH, 500);
    PdfDestination d3 = new PdfDestination(PdfDestination.FITR, 200, 300, 400, 500);
    PdfDestination d4 = new PdfDestination(PdfDestination.FITBV, 100);
    PdfDestination d5 = new PdfDestination(PdfDestination.FIT);

Example: java com.lowagie.examples.objects.bookmarks.Destinations
Creates a document with destinations that can be called from Bookmarks: see Destinations.pdf
Go to top of the page
Outlines and Actions:
In the previous examples we used the outline tree to jump to a certain PdfDestination, but we can also use a PdfOutline to trigger a PdfAction (see the chapter on Actions).

    PdfOutline root = writer.getDirectContent().getRootOutline();
    new PdfOutline(root,
    	new PdfAction("http://www.lowagie.com/iText"), "Bruno's iText site");
    new PdfOutline(other,
    	PdfAction.javaScript("app.alert('Hello');\r", writer), "Say Hello");

Example: java com.lowagie.examples.objects.bookmarks.OutlineActions
Creates a document with external destinations or actions that can be called from Bookmarks: see OutlineActions.pdf remote.pdf
Go to top of the page
the Chapter and Section object:
If all the examples above are overkill, if you only need a simple tree with some chapters and (sub)sections, you needn't define destinations and add them to a rootoutline or a parent outline. You can simply use the objects Chapter and Section. They build a tree and number titles automatically.

    Paragraph cTitle = new Paragraph("This is chapter 1", chapterFont);
    Chapter chapter = new Chapter(cTitle, 1);
    Paragraph sTitle = new Paragraph("This is section 1 in chapter 1", sectionFont);
    Section section = chapter.addSection(sTitle, 1);

Some caveats:

- The content of a complete Chapter (including subsections) is only 'flushed' to the writer at the moment you add the chapter to the document.
  - avoid mixing Chapter.add() and Document.add invocations. If you add a Chunk1 to a Chapter first, then a Chunk2 to the document and finally add the chapter, Chunk2 will come before Chunk1 in the resulting document.
  - avoid creating Chapters that are too large: all the chapter content is kept in memory as long as you don't add the chapter to the doc.
- Every chapter starts on a new page automatically. If you want to have a section within a chapter starting on a new page, you will have to use Chunk.NEXTPAGE.

Example: java com.lowagie.examples.objects.bookmarks.ChapterSection
Creates a document with Chapters and Sections (automatic outlines): see ChapterSection.pdf
Go to top of the page
Amazon books:
amazon.co.uk-link
amazon.co.uk-link