Quick PDF Library is a big library and sometimes it can be a little daunting getting started, so we’ve put together a few basic tips to help you get up to speed quickly. We’ll enhance this document as we think of new tips. If you have any tips you’d like us to add to this document or questions about the intended use of certain features, please leave a comment.
Unlock the library
The UnlockKey function needs to be called and the return value checked otherwise most other functions called later will fail. More info here.
Check functions for return values
Always check the return value of the important functions such as LoadFromFile because if this function fails the subsequent function calls will fail to. Every single function returns a value. Checking for return values is not a requirement, but it can be immensely useful in ensuring the robustness of your code and debugging.
If a function is not documented as having a return value then you can assume the a return value of one (1) indicates successful. Zero (0) or other values could indicate an error or it could be returning a valid handle or ID.
Memory and direct access functions
Function names that start with DA indicate that the function is a direct access function. Functions that do not have this pre-fix are memory functions. Direct access and memory functions cannot be used together. Combining them in your code will result in your code not working correctly.
The DA functions are primarily used for PDF documents that are very large and contain thousands of pages. They are generally faster for these larger documents because the document does not need to be loaded into memory. For file sizes under 500 MB or under a few thousand pages the speed differences are negligible.
Blank document automatically loaded
When you initialise the library there is always a one page blank document in memory. It is selected and ready to use by default. This is due to the design of the library. There can never not be at least one document in memory, so if you try to delete that document using the DeletePages function, the library will automatically re-create a one page blank document.
The blank one page document uses a Letter page size which is 8.5 x 11 inches or 215.9 mm × 279.4 mm. The page size can be changed using the SetPageSize function.
New documents automatically selected
Whether you load an existing document using the LoadFromFile function or create a new document using the NewDocument function, it will automatically be selected in memory and the documents ID can be retrieved using the SelectedDocument function.
Multiple documents in memory permitted
You can have more than one document in memory and can swap between them using the ID returned from calls such functions as NewDocument and SelectedDocument. You can also count all documents in memory using the DocumentCount function and then retrieve each documents ID or filename using GetDocumentID or GetDocumentFileName. All of the document management related functions can be seen in the document management section in the function reference.
Origin point for drawing operations
The origin has coordinates of 0,0 and is the starting point for finding all other points. The origin point for a page in a PDF typically starts at a page corner. The default origin for Quick PDF Library is the bottom left page corner.
Using the SetOrigin function in Quick PDF Library you can change the point of origin to be any page corner (bottom left, top left, top right, bottom right).
By default calling QP.DrawText(10, 10, “Test”) will result in the text being drawn at 10 points in from the left of the page and 10 points up from the bottom of the page, but if you call QP.SetOrigin(1) prior to DrawText then the text will be drawn at 10 points in from the left of the page and 10 points down from the top of the page because passing the value 1 to the Origin parameter for the SetOrigin function changes the origin to top left of the page.
The default point of origin in Adobe Acrobat was the bottom left page corner up until Acrobat 8, at which point Adobe switched the point of origin to the top left page corner. As mentioned above, you can set Quick PDF Library to use any page corner in a PDF.
Measurement units
In PDF the coordinate system is called default user space. The default for the size of the unit in default user space (1/72 inch) is approximately the same as a point, a unit widely used in the printing industry. It is not exactly the same, however; there is no universal definition of a point.
Using the SetMeasurementUnits function you can change the units for all measurements given to and returned from the library. The available options are default user space, millimetres and inches.
Unicode, UTF-8 and the DLL and Delphi Editions
There are many different ways to encode Unicode characters. One way is to use strings with 16-bit characters. COM/ActiveX uses 16-bit characters, so adding Unicode support for the ActiveX edition of the library was easy.
For the Delphi and DLL editions, the strings have always been 8-bit characters. Unfortunately we can’t change the definition of functions as this would cause issues with backwards compatibility.
This means that when using the Delphi and DLL editions and working with Unicode characters, you need to encode your file names with UTF8 encoding, as mentioned in the function reference. Make sure that you pay attention to each function description as it will specifically mention if you need to encode or decode the input or output.
Different languages will have different functions to do the UTF8 encoding.
Standard Fonts
The PDF specification outlines 14 fonts that should always be available in all PDF viewers. These 14 fonts are called standard fonts and can be added to your PDF using the AddStandardFont function.
Font embedding, subset font embedding and no font embedding
There are three key ways that fonts can be handled in PDF files. They are:
Full Font Embedding = Larger file size
Recipient doesn’t need the same font to view or edit the file
Subset Font Embedding = Smaller file size
Recipient doesn’t need the same font to view but does need the same font installed in order to edit the file
No Font Embedding = Smallest file size
Recipient needs to have same fonts installed
Each option has its merits. As long as option 1 or 2 above when you are building your PDF files, then you can be sure that when your PDF is rendered or printed the font you’ve specified will be used. If you use option 3, then the PDF viewer will attempt to locate the specified font on the local machine but if it cannot be found then it will use a substitute font during the viewing/printing process.
When a PDF is displayed on your screen it is rendered in exactly the same fashion as it would be prior to being printed.
Quick PDF Library can only fully embed or subset fonts during the PDF creation process. The AddTrueTypeFont function can be used to add and embed a TrueType font in the document and the AddSubsettedFont function can be used to embed a subset of a font in the document. The AddCJKFont function is also available for CJK fonts.
