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.
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"
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.
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.
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.
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.
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.
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.
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:
goto
: go to a destination within the current documentremotegoto
: go to a destination in a different documenturi
: open a urilaunch
: open an application or fileFor goto
and remotegoto
actions the following keys may be present:
page
: the page to go tomode
: The value will be one of:XYZ
, Fit
, FitH
, FitV
,
FitR
, FitB
, FitBH
, FitBV
left
: XYZ
, FitV
, FitBV
& FitR
modestop
: XYZ
, FitH
, FitBH
& FitR
modesright
: FitR
modebottom
: FitR
modezoom
: XYZ
modeA 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
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
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
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