TTMSFMXNativePDFLib
Usage
The TMSFMXNativePDFLib component is used to create rich pdf documents with support for text flow in multiple columns, rich text, images and various shapes with fill stroke and gradient colors.
Methods
| Methods name | Description |
|---|---|
| BeginDocument(FileName: String = ''); | Creates a new PDF document. If the FileName parameter is not specified, the PDF document is created in memory and returns a TMemoryStream instance when calling EndDocument. |
| CloseDocument | Close an active PDF document. |
| DrawPage(PageIndex: Integer) | Draws an existing PDF page to a new PDF document. |
| EndDocument | Ends the document and writes all remaining data from memory to a file or a memorystream, depending on the chosen action in BeginDocument. |
| GetDocumentInfo | When an existing PDF document is opened, this method retrieves the document information such as the Author, Creator, Title, Subject … When calling this method, the existing data is overwritten and applied when creating a new document. |
| GetPageCount | When an existing PDF document is opened this method returns the number of pages. |
| GetPageInfo(PageIndex: Integer) | When an existing PDF document is opened, the GetPageInfo method returns the various boxes (MediaBox, CropBox, TrimBox, ArtBox and BleedBox) that are used in that page. These boxes can be used to determine the page size and orientation. When calling this method the previous data is overwritten and applied when creating a new page. |
| IsDocumentOpened | Boolean to determine if a PDF document was already opened with OpenDocument. |
| NewPage | Creates a new PDF page. |
| OpenDocument(FileName: String) | Opens an existing PDF document from a file. |
| OpenDocument(FileStream: TMemoryStream) | Opens an existing PDF document from a TMemoryStream. |
| SaveDocumentFromStream(FileStream: TMemoryStream; FileName: String); | Saves an existing PDF document from a TMemoryStream to a file. |
| UnlockWithPassword(Password: String): Boolean; | When an existing PDF document is opened, the contents might be encrypted when calling GetDocumentInfo. This method unlocks the document with a password and returns a Boolean if the document is unlocked successfully. |
Public Properties
| Properties name | Description |
|---|---|
| MediaBox, TrimBox, BleedBox, ArtBox, CropBox | Various boxes that can be used to retrieve / set information from / to a page or document that is created / opened. The MediaBox is used to specify the width and height of the page. The MediaBox is the largest page box in a PDF. The other page boxes can equal the size of the MediaBox but they cannot be larger.The CropBox defines the region to which the page contents are to be clipped.The BleedBox determines the region to which the page contents needs to be clipped when output in a production environment. The TrimBox defines the intended dimensions of the finished page. Contrary to the CropBox, the TrimBox is very important because it defines the actual page size.The ArtBox is a bit of a special case. It can define a region within a page that is of special interest. |
| ModificationDate | The date the PDF document was modified. |
| CreationDate | The date the PDF document was created. |
| Producer | The producer of the PDF document. |
Properties
| Properties name | Description |
|---|---|
| AllowsCopying | Enable or disable copying on a new PDF password protected document. |
| AllowsPrinting | Enable or disable printing on a new PDF password protected document. |
| Author | The author of the PDF document. |
| Creator | The creator of the PDF document. |
| FillColor | The fill color used for drawing shapes and drawing text. This property is also the start color for a gradient. |
| FillColorTo | The end color for a gradient. |
| Font | The font used when drawing text in a document. |
| Footer | The footer drawn at the bottom of each new page. |
| FooterAlignment | The alignment of the footer text. |
| FooterMargins | The margins applied to the footer rectangle. |
| FooterSize | The height of the footer rectangle. |
| Header | The header drawn at the bottom of each new page. |
| HeaderAlignment | The alignment of the header text. |
| HeaderMargins | The margins applied to the header rectangle. |
| HeaderSize | The height of the header rectangle. |
| Keywords | The keywords of the PDF document. |
| LineBreakMode | The linebreakmode when drawing text in a PDF document. |
| LineWidth | The width of the stroke when drawing shapes or the width of the line when drawing lines. |
| Orientation | The orientation of a page / document. This property cannot be used to retrieve the orientation of a page, only to modify the box rectangles that are used when creating a new page. Read out the box rectangle properties after opening a document and calling GetPageInfo, to get more information about the page size and orientation. |
| OwnerPassword | The owner password of the PDF document. You can set an owner password to keep other people from printing, copying or modifying text, adding or deleting pages in your PDF files. |
| PageSize | The page size of a page / document. This property cannot be used to retrieve the page size of a page, only to modify the box rectangles that are used when creating a new page. Read out the box rectangle properties after opening a document and calling GetPageInfo, to get more information about the page size and orientation. |
| StrokeColor | The color of the stroke when drawing a shape or line. |
| Subject | The subject of the PDF document. |
| Title | The title of the PDF document. |
| UserPassword | The user password of the PDF document. This kind of password is used to help prevent opening or viewing your PDF. You can unlock your pdf passing this password in the as a parameter of the UnlockWithPassword method. |
Creating a new document
The code snippets below demonstrates how to create a new document based on a file or a memory stream. If the file exist the PDF document contents are cleared.
TMSFMXNativePDFLib1.BeginDocument(‘FileName’);
TMSFMXNativePDFLib1.NewPage;
TMSFMXNativePDFLib1.EndDocument;
To create a new document in memory use the following code:
var
ms: TMemoryStream;
begin
TMSFMXNativePDFLib1.BeginDocument;
TMSFMXNativePDFLib1.NewPage;
ms := TMSFMXNativePDFLib1.EndDocument;
end;
Opening an existing document
The code snippet below demonstrates how to open an existing document based on a file or a memory stream.
TMSFMXNativePDFLib1.OpenDocument(‘FileName’);
if TMSFMXNativePDFLib1.UnlockWithPassword(‘Password’) then //optional password unlocking
begin
TMSFMXNativePDFLib1.GetDocumentInfo; // get document information //such as the Author, Title, …
TMSFMXNativePDFLib1.GetPageInfo(1); // get page informaton such as //the MediaBox, CropBox, …
end;
TMSFMXNativePDFLib1.CloseDocument;
Opening a document from a memory stream is based on the same code but with a different OpenDocument overload.
Drawing pages from an existing PDF document
Editing a PDF page or document is only possible if the page is drawn on a different context in a new PDF Document. The reason for editing might be to add watermarks, to merge multiple documents, add or remove pages. The sample below copies the PDF pages from an existing document to a new document.
var
I: Integer;
begin
TMSFMXNativeMacPDFLib1.OpenDocument('Existing.pdf');
TMSFMXNativeMacPDFLib1.BeginDocument('New.pdf');
for I := 1 to TMSFMXNativeMacPDFLib1.GetPageCount do
begin
//copy page information
TMSFMXNativeMacPDFLib1.GetPageInfo(I);
//add page to new document
TMSFMXNativeMacPDFLib1.NewPage;
//draw page from existing document
TMSFMXNativeMacPDFLib1.DrawPage(I);
//additional manipulation / drawing
//...
end;
TMSFMXNativeMacPDFLib1.EndDocument;
TMSFMXNativeMacPDFLib1.CloseDocument;
end;
Graphics Library
The above table does not list all methods that are available in the PDF rendering library. The PDF rendering library inherits from the Graphics Library and is able to draw images, shapes / lines with solid / gradient colors and plain text. All methods start with Draw and can be used within a new PDF page. The Graphics Library also supports more complex shapes drawn within a path. The code below demonstrates how this can be achieved.
TMSFMXNativePDFLib1.BeginDocument(‘FileName’);
TMSFMXNativePDFLib1.NewPage;
TMSFMXNativePDFLib1.FillColor := TAlphaColorRec.Red;
TMSFMXNativePDFLib1.StrokeColor := TAlphaColorRec.Darkred;
TMSFMXNativePDFLib1.LineWidth := 3;
TMSFMXNativePDFLib1.DrawPathBegin;
TMSFMXNativePDFLib1.DrawPathMoveToPoint(PointF(200, 200));
TMSFMXNativePDFLib1.DrawPathAddCurveToPoint(PointF(250, 150), PointF(325, 250), PointF(200, 300));
TMSFMXNativePDFLib1.DrawPathAddCurveToPoint(PointF(75, 250), PointF(150, 150), PointF(200, 200));
TMSFMXNativePDFLib1.DrawPathClose;
TMSFMXNativePDFLib1.DrawPathEnd;
TMSFMXNativePDFLib1.EndDocument;
Graphics Library Rich Text
The Graphics Library also supports rendering rich text. For more information, please read the TTMSFMXNativeUIRichTextView chapter that explains the capabilities of rendering rich text. The method name that is being used to render rich text is “DrawRichText”. All properties related to rich text can be accessed at the RichText function directly available from the PDF Library component. Below is a sample that demonstrates this.
TMSFMXNativePDFLib1.BeginDocument(‘FileName’);
TMSFMXNativePDFLib1.NewPage;
TMSFMXNativePDFLib1.RichText.Text := ‘Hello World’;
TMSFMXNativePDFLib1.RichText.SetBold;
TMSFMXNativePDFLib1.RichText.SetForegroundColor(TAlphaColorRec.Red, 0, 5);
TMSFMXNativePDFLib1.DrawRichText(RectF(50, 50, 150, 100));
TMSFMXNativePDFLib1.EndDocument;
Text Flow
Starting from iOS 7 the PDF Rendering Library supports drawing text in multiple columns. The code below demonstrates how easy it is to specify text, a rectangle and the amount of columns. The text flow feature is also available for rich text.
lorem := 'Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry''s standard dummy text ever since '+
'the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also '+
'the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem '+
'Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum. It is a long established fact that'+
' a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal'+
' distribution of letters, as opposed to using ''Content here, content here'', making it look like readable English. '+
'Many desktop publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for ''lorem ipsum'' '+
'will uncover many web sites still in their infancy. Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like).';
r := TMSFMXNativePDFLib1.MediaBox;
InflateRect(r, -50, -50);
TMSFMXNativePDFLib1.BeginDocument(‘FileName’);
TMSFMXNativePDFLib1.NewPage;
TMSFMXNativePDFLib1.DrawText(lorem, RectF(r.Left, R.Top, r.Right, R.Top + 250), 3);
TMSFMXNativePDFLib1.EndDocument;
Text Calculation And Overflow
Each DrawText / DrawRichText call has a number of overloads to draw at a point, in a rectangle or with text flow. Additional default parameters Calculate and DetectOverFlow can be used to calculate the size of the text and the detect the number of characters that remain when drawing the text inside a rectangle with overflow capabilities. Specifying a True value to these parameters forces the method to calculate instead of drawing the text.
Images
The PDF Rendering Library supports drawing images at a specific point, with aspect ratio in a rectangle and optional PNG and JPG quality. Specifying JPG as drawing type has an additional Quality parameter from 0 to 1 where 0 is the lowest quality when drawing.