| iTextSharp Tutorial | iTextSharp,
a Free C#-PDF library | ||||
| [Home] | [TOC] | [Next] | [PDF] | ||
Part I: Simple iText Chapter 1: Creating a document | |||||
| Creation of
a document in 5 steps: Hello World Download the source code of the first example: Chap0101.cs. This example contains the 5 most important steps to create a PDF file using iText: Step 1: Creates an instance of the iTextSharp.text.Document-object: Document document = new Document(); Step 2: Creates a Writer that listens to this document and writes the document to the Stream of your choice: PdfWriter.getInstance(document, new FileStream("Chap0101.pdf", FileMode.Create)); Step 3: Opens the document: document.Open(); Step 4: Adds content to the document: document.Add(new Paragraph("Hello World")); Step 5: Closes the document: document.Close(); Check the result here: Chap0101.pdf. | |||||
| Examining step 1: the
Document-object The iTextSharp.text.Document-object has 3 constructors: public Document(); public Document(Rectangle pageSize); public Document(Rectangle pageSize, int marginLeft, int marginRight, int marginTop, int marginBottom); The first constructor calls the second one, with PageSize.A4 as parameter. The second constructor calls the third one, with 36 as value for each margin. PageSize You could create your own Rectangle-object in a certain color and use this as pageSize. In example Chap0102.cs, we create a long, narrow document with a yellowish backgroundcolor: Rectangle pageSize = new Rectangle(144, 720); pageSize.BackgroundColor = new Color(0xFF, 0xFF, 0xDE); Document document = new Document(pageSize); This is the result: Chap0102.pdf. Normally, you don't have to worry about creating this rectangle, since you can use one of the statics in class PageSize.cs. These are the pagesizes that are provided: A0-A10, LEGAL, LETTER, HALFLETTER, _11x17, LEDGER, NOTE, B0-B5, ARCH_A-ARCH_E, FLSA and FLSE. Most these pageSizes are in PORTRAIT-format. If you want them to be in LANDSCAPE, all you have to do is rotate() the Rectangle: Document document = new Document(PageSize.A4.rotate()); Check out example Chap0103.cs and its result. Margins When creating a document, you can also define left, right, upper and lower margins: Document document = new Document(PageSize.A5, 36, 72, 108, 180); In example Chap0104.cs (and its result: Chap0104.pdf), you will see that this document has a left margin of 0.5 inch and a right margin of 1 inch. The upper margin is 1.5 inch, the lower 2.5 inch.
Remark: if you change the page size, this only has effect on the next page (see page initializations). If you change the margins, this has an immediate effect, so be careful! | |||||
| Examining step 2: the
Writer-object Once our document is created, we can create one or more instances of writers that listen to this document. All writers should be derived from the abstract class iTextSharp.text.DocWriter. For the moment there is one possibility: you can use iTextSharp.text.pdf.PdfWriter to generate documents in the Portable Document Format. If for instance you want to generate TeX-documents as well, you could write a package: iTextSharp.text.TeX.TeXWriter.
The constructor of these writer-classes is made private. You can only create an instance with the following method: public static xxxWriter getInstance(Document document, Stream os) (xxx being Pdf or Xml) You can create an instance this way: PdfWriter writer = PdfWriter.getInstance(document, new FileStream("Chap01xx.pdf")); but you will hardly ever need the object writer (except if you want to create Advanced PDF or if you want to use some very specific functionalities such as ViewerPreferences or Encryption). So it's sufficient to just get the instance: PdfWriter.getInstance(document, new FileStream("Chap01xx.pdf")); It's trivial that the first parameter should be the document you created in step 1. The second parameter can be an Stream of any kind. Until now, we have always used a System.IO.FileStream to write the document to a file, but in example Chap0105.aspx, the outputStream is a System.IO.MemoryStream. (This is not a standalone example; you will have to test this code on a Servlet Engine). Here is a sample of a code-behind version of the same example Chap0105.cs. | |||||
| Examining step 3: Meta
data + opening the document Metadata Before you add any actual data (= content), you might want to add some metadata about the document with one of these methods: public boolean addTitle(String title) public boolean addSubject(String subject) public boolean addKeywords(String keywords) public boolean addAuthor(String author) public boolean addCreator(String creator) public boolean addProducer() public boolean addCreationDate() public boolean addHeader(String name, String content) You can choose your own title, subject, keywords, author and creator, but the method that adds the producerdata should always add: iTextSharp (or a reference to iTextSharp) and the method that adds the creation date always add the current system time (as a matter of fact, these two methods are called automatically). You can also add a header with a custom name, but this will have no effect on the PdfWriter. If we look at the example in step 1: Chap0101.pdf, we see that only the producer and date are shown in the infobox. If we run Chap0106.cs, the result is a similar document: Chap0106.pdf, but there are more items added to the infobox:   Things to do BEFORE you open the document You can only add metadata BEFORE the open-method is invoked. This is a choice made by the developer of iText. In HTML meta-information is put between the HEAD-tags at the beginning of the document (the header section). Invoking the open-method causes the writer to write this header to the Stream. So there is no way to change this data once the document is 'opened'. The PDF header doesn't contain any metadata, it looks like this: %PDF-1.2 %рсту The first line indicates the generated document is a file in the Portable Document Format version 1.2. The meaning of the second line is explained in the reference manual.
In
PDF, the metadata is kept in a PdfInfo-object, written to the PdfWriter
when the document is closed. So there is no technical reason why one
couldn't alter the library to be able to add or change the metadata
at any time. It's a design choice that was made.
Encryption Another thing to do BEFORE you open the document, is to set the encryption (that is: if you want the PDF file to be encrypted). To achieve this, you use the method: public void setEncryption(boolean strength, String userPassword, String ownerPassword, int permissions);
writer.setEncryption(PdfWriter.STRENGTH40BITS, null, null, PdfWriter.AllowCopy); Chap0109.pdf can be opened without using a password, but the user is not allowed to Print, Modify,... the document. writer.setEncryption(PdfWriter.STRENGTH128BITS, "userpass", "ownerpass", PdfWriter.AllowCopy | PdfWriter.AllowPrinting); When you try to open Chap0110.pdf, you are asked for a password (type in 'userpass'). Because the AllowPrinting-preference was added, you can print this document without any problem. | |||||
| Examining step 4:
adding content In the different examples explaining step 1 to 3, you have already encountered objects such as Phrase, Paragraph,... In the next 5 chapters all these objects will be explained more thoroughly. Sometimes you may want a writer to deliberately ignore actions performed on a document. This is shown in example 11. If we create two writers: writerA and writerB (this is an exception to what was said in step 2): PdfWriter writerA = PdfWriter.getInstance(document, new FileStream("Chap0111a.pdf", FileMode.Create)); PdfWriter writerB = PdfWriter.getInstance(document, new FileStream("Chap0111b.pdf", FileMode.Create)); We can create two documents that are slightly different: writerA.Pause(); document.add(new Paragraph("This paragraph will only be added to Chap0111b.pdf, not to Chap0111a.pdf")); writerA.resume(); You can compare the results of example 11 here: Chap0111a.pdf vs. Chap0111b.pdf. | |||||
| Examining step 5:
closing the document Closing the document is very important, because it flushes and closes the outputstream to which the writer is writing. The close-method is called in the finalize-method, but you shouldn't count on that. You should always close the document yourself! | |||||
|
Advanced: reading PDF You can't 'parse' an existing PDF file using iText, you can only 'read' it page per page. What does this mean? The pdf format is just a canvas where text and graphics are placed without any structure information. As such there aren't any 'iText-objects' in a PDF file. In each page there will probably be a number of 'Strings', but you can't reconstruct a phrase or a paragraph using these strings. There are probably a number of lines drawn, but you can't retrieve a Table-object based on these lines. In short: parsing the content of a PDF-file is NOT POSSIBLE with iText. Post your question on the newsgroup news://comp.text.pdf and maybe you will get some answers from people that have built tools that can parse PDF and extract some of its contents, but don't expect tools that will perform a bullet-proof conversion to structured text. What iText DOES provide is the possibility to READ a PDF document and copy an entire page of this file into the PDF file you are constructing from scratch. This can be useful if you want to create a new document based on (an) existing document(s). You can add a Watermark, pagenumbers,... Example 12 takes a pdf file from Chapter 7 and creates a new document where 4 pages of the original document are painted on 1 page of the new document. We also added a Watermark and pagenumbers (see Chap0112.pdf). In order to fully understand the code (an how to adapt it to your needs, you will have to read Chapter 10 first) If you have an existing PDF file that represents a form, you could copy the pages of this form and paint text at precise locations on this form. You can't edit an existing PDF document, by saying: for instance replace the word Louagie by Lowagie. To achieve this, you would have to know the exact location of the word Louagie, paint a white rectangle over it and paint the word Lowagie on this white rectangle. Please avoid this kind of 'patch' work. Do your PDF editing with an Adobe product. Concat, Split, Handout, Encrypt Using the functionality to read PDFs, I have made 4 little tools that can be called from the commandline:
|
|||||
| [Top] | [TOC] | [Next] | [PDF] | ||
