PDF Widget

The pdf widget displays an interactive pdf control. It uses the open source PDFium library and is available for all platforms with the exception of HTML5.

PDF widget

Creating a PDF Widget

A pdf widget can be created by dragging it out from the Tools Palette, where it appears with the following icon:

Alternatively it can be created in script using:

create widget as "com.livecode.widget.pdf"

Using the PDF Widget

The PDF widget has a wide range of properties allowing you to alter the appearance of the widget, the way the user can interact with the document and providing details about the loaded document.

Loading documents

Set the fileData to the binary data of a PDF document or the fileName of the widget to the full path to a PDF document and the widget will load the file and render it. Additionally, password protected documents are supported using the password property.

Document information

The documentPages property returns an array with an element for each page in order with name (if available), width and height keys, however, if only page count is required the numberOfPages property gives direct access to that.

The documentMetadata property returns an array with the metadata of the document such as title, author and creation date.

The documentViewerPreferences returns any preferences the author may have set about how the document should be displayed or printed.

Document display

Use the pageDisplay property of the widget to change the document display from single page mode to horizontal or vertical scrolling. When in single page mode the flipPages property controls the animation style when paging and the lockPage property controls the user's ability to change pages. During the flip animation the pageBackColor is used for the back side of the page. At the end of a user initiated page change the pageChanged message is sent with the current page number and the previous page number as parameters. The currentPage property may also be used to determine the current page number being displayed or change the page. When not in single page mode setting the currentPage will change the scroll of the widget so that the specifed page is displayed.

The widget border look can be altered using the showBorder, borderWidth, threeD, borderColor, topColor and bottomColor properties in the same way as many other LiveCode objects. The default position of the page within the widget can be controlled using the pageGravity and pagePadding properties. Use the opaque and backColor properties to alter look of the area around the page. Additionally the page border look can be changed using the pageBorderColor, pageBorderWidth, showPageBorder properties.

The widgets supports control over the drawing of annotations on the PDF using the drawAnnotations property.

Scrolling and zooming the document

Control scrolling of the document with the hScroll, vScroll, hScrollbar, vScrollbar, pageLocation, pageRect and lockScroll properties. The size of the rendered page may be controlled using the zoom property with a zoom of 100 rendering the page at its intrinsic size as returned by the documentPages. For example, here is some code scaling display of page 1 to the width of the widget:

local tPages
put the documentPages of widget "pdf" into tPages
local tFixedWidth
put the pagePadding of widget "pdf" * 2 into tFixedWidth
if the showBorder of widget "pdf" then
  add the borderWidth of widget "pdf" * 2 to tFixedWidth
end if
if the showPageBorder of widget "pdf" then
  add the pageBorderWith of widget "pdf" * 2 to tFixedWidth
end if
set the zoom of widget "pdf" to \
        (the width of widget "pdf" - tFixedWidth) \
        / tPages[1]["width"] * 100

The widget supports pinch zoom on mobile platforms and sends the zoomChanged message. To ensure a fixed zoom set the lockZoom property to true. Use the formattedRect property to get the size required to render the current page in single displayMode or all pages in the other modes at the current zoom and with the current border and padding settings.

Text selection

The PDF widget also supports text selection when the autoHilight property is true. The hilitedRange can be used to determine the pages and charachters curently selected and the hilitedRangeText can be used to get the text of the selection. When the selection is changed the selectionChanged message is sent. For example, here is some code that will put the length of the hilited text into a field when it changes:

on selectionChanged
    local tLength
    put the length of the hilitedRangeText into tLength
    put tLength && "characters selected" into field "length"
end selectionChanged

Use the hiliteColor property to change the color used to indicate text selections.

Actions and destinations

The widget uses an array to represent PDF actions. The type key of the array is the type of action and may be one of:

For goto and remotegoto actions the following keys may be present:

A remotegoto or launch action have a filepath key while the uri action has a uripath key.

The documentOpenAction property is the action that should be performed when opening the document. The documentNamedDestinations property is an array which has the names for the keys and their associated goto actions for the elements.

The currentDestination property will return the closest named destination if there is one on the current page, however, it is most useful for navigation to goto actions. For example, here is some code that will execute the documentOpenAction if it is a goto type:

set the fileName of widget "PDF" to tPath
local tAction
put the documentOpenAction of widget "PDF" into tAction
if tAction["type"] is "goto" then
    set the currentDestination of widget "PDF" to tAction
end if

Links

Whenever a user clicks on a link on a page the linkClicked message is sent with an array detailing the link action. For example, here is some code that will execute the link action if it is either a "goto" or "uri" type:

on linkClicked pAction
    switch pAction
        case "goto"
            set the currentDestination of me to pAction
            break
        case "uri"
            launch url pAction["uripath"]
            break
    end switch
end linkClicked

Links on PDF pages do not have a drawn representation. They are a rectaingle on the page that has an action associated with it, however, in order to indicate to the user where the links are on the page the widget has a linkStyles property. The linkStyles array allows you to specify border, fill and style for a link rectangle. For example, here is some code to draw a blue line under uri links and a green semi-transparent fill around a goto link:

local tStyles
put "uri" into tStyles[1]["type"]
put 0,0,255,255 into tStyles[1]["lineColor"]
put 2 into tStyles[1]["lineWidth"]
put "underline" into tStyles[1]["style"]
put "goto" into tStyles[2]["type"]
put 0,255,0,50 into tStyles[2]["fillColor"]
set the linkStyles of widget "pdf" to tStyles

Bookmarks

The documentBookmarks property is an array that may be deeply nested to represent a heirarchy of bookmarks. The array is numerically indexed where each element is an action array which may also have a title key and a children key. Where a children key is present it is also a numerically indexed array in the same format. For example, here is some code that sets the text of a menu button to a bookmark menu then sets the currentDestination when an item is picked.

on mouseDown
    set the text of me to BuildMenu(the documentBookmarks of widget "PDF")
end mouseDown

function BuildMenu pBookmarks, pIndent
    local tMenu
    repeat for each element tElement in pBookmarks
        put pIndent & tElement["title"] & return after tMenu
        if tElement["children"] is an array then
            put BuildMenu(tElement["children"], tab & pIndent)
        end if
    end repeat
    delete char -1 of tMenu
    return tMenu
end BuildMenu

on menuPick pWhich
    set the currentDestination of widget "PDF" to \
            FindTitle(the documentBookmarks of widget "PDF", pWhich)
end menuPick

function FindTitle pBookmarks, pWhich
    local tTitle
    set the itemDelimiter to "|"
    put item 1 of pWhich into tTitle
    delete item 1 of pWhich
    repeat for each element tElement in pBookmarks
        if tElement["title"] is tTitle then
            if pWhich is empty then
                return tElement
            else if tElement["children"] is an array then
                return FindTitle(tElement["children"], pWhich)
            end if
        end if
    end repeat
    return empty
end FindTitle

Document images

When a user clicks on an image on a displayed page the imageClicked message is sent. Use the clickedImage property to get an array of imageData, width and height. For example, here is some code that handles imageClicked and sets the imageData of an image to the data from the clickedImage.

on imageClicked
    local tClicked
    put the clickedImage of me into tClicked
    lock screen
    set the width of image "clicked" to tClicked["width"]
    set the height of image "clicked" to tClicked["height"]
    set the imageData of image "clicked" to tClicked["imageData"]
end imageClicked