Someone asked in the Xojo Forum if it was possible to create thumbnails (Xojo Picture objects) from a page of a PDF in order to display it in an iOS app. Sure it is! Continue reading to learn how in this step-by-step tutorial.
What You Need
In order to do this we need the following pieces of the puzzle:
- A FolderItem pointing to the PDF file. For our tutorial we will use a FolderItem pointing to a file that has been copied to the Resources folder of the iOS app using a “Copy To” build step.
- The number of pages in the PDF document.
- The rect or bounds of the page in the PDF document.
- Create a Picture from a given page in the PDF document.
Except for the first piece, we are going to make use of the powerful
Declare feature. This feature allows us to create native objects from the iOS frameworks and call methods / functions on these, or any of the available functions.
Getting the Number of Pages
First, create a new iOS project in Xojo. Next, add a new Module to the project and name it “External” using its Inspector Panel (you can choose any name).
Next, add a new Method to that module using the following signature in the Inspector Panel:
- Method Name: NumberOfPages
- Parameters: PDFDocFile As FolderItem
- Return Type: Integer
- Scope: Global
Type now the following code in the Code Editor for the method:
// Declares against the Foundation framework. // Once "Declared" we can use them from our Xojo code Declare Function NSClassFromString Lib "Foundation" (clsName As CFStringRef) As Ptr Declare Function FileURLWithPath Lib "Foundation" Selector "fileURLWithPath:" (obj As ptr, path As CFStringRef) As Ptr Declare Function CGPDFDocumentCreateWithURL Lib "CoreGraphics" (url As Ptr) As Ptr Declare Function CGPDFDocumentGetNumberOfPages Lib "CoreGraphics" (PDF As Ptr) As Integer // We get the native path from the received FolderItem Var path As String = PDFDocFile.NativePath // Here we are creating an NSURL object Var URLClass As ptr = NSClassFromString("NSURL") If URLClass = Nil Then Exit // And now we get the reference to the file using the path in combination // With the created NSURL instance Var pathPointer As Ptr = fileURLWithPath(URLClass, path) // We are getting here a reference to the PDF document using the // previous reference for that. Var docReference As Ptr = CGPDFDocumentCreateWithURL(pathPointer) If docReference = Nil Then Exit // Lastly, we only need to call this CoreGraphics function // to get the number of pages from the reference to the // PDF document we got in the previous step Return CGPDFDocumentGetNumberOfPages(docReference)
Creating a Picture from a PDF
Add the method in charge of returning a
Picture created from the page of the PDF document received as parameters. As we did previously, pass along a
FolderItem pointing to the PDF document and the page number as an integer (all PDF document pages start at index 1).
Before creating the method we need to add some
Structs before to our module. These are needed both for passing values to some CoreGraphics calls and also to receive this kind of types as the value returned by some of these.
With the “External” module selected in the Navigator, add a new
Structure and name it as
NSOrigin with following values in the Structure Editor:
Add a second
Structure with the name
NSSize and the following values:
And the third
NSRect with the following values:
Add the second method to the “External” module using the following values in the Inspector Panel:
- Method Name: GetPDFThumbnailForPage
- Parameters: PDF As FolderItem, page As Integer
- Return Type: Picture
- Scope: Global
Next, type the following code in the Code Editor for the method:
// Declares for Foundation Calls Declare Function NSClassFromString Lib "Foundation" (clsName As CFStringRef) As Ptr Declare Function FileURLWithPath Lib "Foundation" Selector "fileURLWithPath:" (obj As Ptr, path As CFStringRef) As Ptr Declare Function DataLength Lib "Foundation" Selector "length" (obj As Ptr) As Integer Declare Sub GetDataBytes Lib "Foundation" Selector "getBytes:length:" (obj As Ptr, buff As Ptr, len As Integer) // Declares for CoreGraphics calls Declare Sub CGContextDrawPDFPage Lib "CoreGraphics" (ctx As Ptr, page As Ptr) Declare Sub CGContextFillRect Lib "CoreGraphics" (ctx As Ptr, rect As NSRect) Declare Sub CGContextRestoreGState Lib "CoreGraphics" (obj As Ptr) Declare Sub CGContextSaveGState Lib "CoreGraphics" (ctx As Ptr) Declare Sub CGContextScaleCTM Lib "CoreGraphics" (ctx As Ptr, x As CGFloat, y As CGFloat) Declare Sub CGContextSetGrayFillColor Lib "CoreGraphics" (ctx As Ptr, x As CGFloat, y As CGFloat) Declare Sub CGContextTranslateCTM Lib "CoreGraphics" (ctx As Ptr, x As CGFloat, y As CGFloat) Declare Function CGPDFDocumentCreateWithURL Lib "CoreGraphics" (url As Ptr) As Ptr Declare Function CGPDFDocumentGetPage Lib "CoreGraphics" (doc As Ptr, page As Integer) As Ptr Declare Sub CGPDFDocumentRelease Lib "CoreGraphics" (PDF As Ptr) Declare Function CGPDFPageGetBoxRect Lib "CoreGraphics" (page As Ptr, box As UInt32) As NSRect // Declares for UIKit calls Declare Sub UIGraphicsBeginImageContext Lib "UIKit" (size As NSSize) Declare Sub UIGraphicsEndImageContext Lib "UIKit" () Declare Function UIGraphicsGetCurrentContext Lib "UIKit" () As Ptr Declare Function UIGraphicsGetImageFromCurrentImageContext Lib "UIKit" () As Ptr Declare Function UIImagePNGRepresentation Lib "UIKit" (img As Ptr) As Ptr If PDF = Nil Then Exit Var path As String = PDF.NativePath // Getting a reference to the NSURL class Var URLClass As ptr = NSClassFromString("NSURL") If URLClass = Nil Then Exit // Getting a reference to a file URL from the given path Var pathPointer As Ptr = fileURLWithPath(URLClass, path) // Getting a reference to the PDF document, from the URL file pointer Var docReference As Ptr = CGPDFDocumentCreateWithURL(pathPointer) If docReference = Nil Then Exit // Getting a reference to the object pointing to the page in the PDF document Var pageRef As Ptr = CGPDFDocumentGetPage(docReference, page) // Getting the bounds for the page Var pageBounds As NSRect = CGPDFPageGetBoxRect(pageRef, 0) Var maxHV As Integer = Max(pageBounds.RectSize.Width, pageBounds.RectSize.Height) If pageRef = Nil Then Exit Var pageRect As NSRect pageRect.Origin.X = 0 pageRect.Origin.Y = 0 pageRect.RectSize.Width = maxHV pageRect.RectSize.Height = maxHV // Starting an Image context UIGraphicsBeginImageContext(pageRect.RectSize) // And getting the reference to the current context Var imgCtx As Ptr = UIGraphicsGetCurrentContext // We save the graphics state CGContextSaveGState(imgCtx) // Matrix translation and Scale CGContextTranslateCTM(imgCtx, 0.0, pageRect.RectSize.Height) CGContextScaleCTM(imgCtx, 1.0, -0.95) CGContextSetGrayFillColor(imgCtx, 1.0, 1.0) CGContextFillRect(imgCtx, pageRect) // Drawing the PDF Page into the graphic context CGContextDrawPDFPage(imgCtx, pageref) // Getting an UIImage from the graphics context Var img As Ptr = UIGraphicsGetImageFromCurrentImageContext // Getting an NSDATA object with the PNG representation from the image Var pngDATA As Ptr = UIImagePNGRepresentation(img) // We need to get the length of the raw data… Var dlen As Integer = DataLength(pngDATA) // …in order to create a memoryblock with the right size Var mb As New MemoryBlock(dlen) Var mbPtr As Ptr = mb // And now we can dump the PNG data from the NSDATA objecto to the memoryblock GetDataBytes(pngDATA, mbPtr, dlen) // In order to create a Xojo Picture from it Var p As Picture = Picture.FromData(mb) // Clean-up CGContextRestoreGState(imgCtx) UIGraphicsEndImageContext CGPDFDocumentRelease(docReference) Return p
Designing the UI for the iOS App
Now we have everything we need in order to get the page thumbnails as Pictures. So let’s create a simple user interface to test it.
Screen1 in the Navigator so the Layout Editor is displayed in the IDE. Next, drag an
ImageViewer from the Library to the Layout Editor. It should look like this:
Table object from the Library and put it below the
ImageViewer in the Layout Editor. It should like like this:
The UI of our iOS app is completed!
Reference the PDF File
You might want to use another technique to get the
FolderItem for the PDF document file; but in order to keep this tutorial as short as possible we will a reference just the one PDF file previously copied to the Resources folder of the App.
In order to do that, select the iOS icon in the Navigator and choose the
Add To "Build Settings" > Build Step > Copy Files option. This will add a new
CopyFiles1 object to the Navigator, displaying the associated Editor.
Simply drag and drop the PDF file you want in the main area of the Editor (or click in the icon with the plus symbol from the toolbar), and make sure to select the following values in the associated Inspector Panel:
- Applies To: Both
- Architecture: Any
- Destination: Resources Folder
Screen1 item in the Navigator again and add a new Property to it, using the following values in the associated Inspector Panel:
- Name: PDFDocFile
- Type: FolderItem
- Scope: Public
Let’s Roll the Ball!
Our example iOS app is almost done. We only need to write the logic that will make use of the methods we wrote in the “External” Module.
Screen1 item selected in the Navigator, select the option
Add to "Screen1" > Event Handler… from the contextual menu. Next, select the
Opening event and confirm the selection so it is added to
The last action will automatically select the
Opening event in the Navigator, bringing the associated Code Editor to the main area of the IDE. Add the following lines of code:
Var PDFFileCopiedToResources As String = "Introduction to Programming with Xojo.pdf" PDFDocFile = SpecialFolder.Resource(PDFFileCopiedToResources) Var numberOfPages As Integer = NumberOfPages(PDFDocFile) For x As Integer = 1 To numberOfPages Table1.AddRow("Page " + x.ToString) Next x ImageViewer1.Image = GetPDFThumbnailForPage(PDFDocFile, 1)
Observe the variable named
PDFFileCopiedToResources. In this case it is assigned the name of the file copied to the Resources folder using the Build Step. Change that to the name of the file you copied and make sure to include the “.PDF” extension as part of the file name.
This code calls the
NumberOfPages method in order to get the number of pages. Then we use a
For…Next loop to add as many “Page x” rows to the table as there are pages in the PDF document.
Also, as you can see, the last line calls the second method so the
ImageViewer1 control displays the first page of the document every time the app is run.
Lastly, select the
Table1 item in the Navigator and choose the
Add to "Table1" > Event Handler… option from the contextual menu. Select the entry
SelectionChanged in the resulting window and confirm the selection so it is added to the control.
The last action will select the just added Event Handler in the Navigator, bringing the associated Editor to the main area of the Xojo IDE. This is the event that will be executed every time the user changes the row selected in the table. Type the following line of code:
ImageViewer1.Image = GetPDFThumbnailForPage(PDFDocFile, row + 1)
Running the App
The app is complete now, so we can click on the Run button to launch the Xcode Simulator and run our app on it. You should be able to see something similar to the image displayed below. Tap (or click) on any row you want so the ImageViewer displays the thumbnail for the selected page and that’s all!