app

app is a static object that represents the Revu application and contains application specific functions and utilities.

properties

focusRect

Toggles the focus rectangle around form fields on and off

example:

app.focusRect = false

formsVersion

Exists for compatibility reasons. Always returns 9.0

fullscreen

Exists for compatibility reasons. Always returns false

language

Exists for compatibility reasons. Always returns "ENU"

numPlugIns

Exists for compatibility reasons. Always returns 0

openInPlace

Exists for compatibility reasons. Always returns false

platform

Exists for compatibility reasons. Always returns "WIN"

plugIns

Exists for compatibility reasons. Always returns an empty array

printerNames

List of installed printers. Requires Revu 21.5 or above

example:

for (var i = 0; i < app.printerNames.length; i++) {
    console.println(app.printerNames[i])
}

runtimeHighlight

Toggles highlighting form fields for improved visibility on and off

example:

app.runtimeHighlight = false // Turn off highlighting form fields

runtimeHighlightColor

The highlight color when highlighting form fields is enabled

app.runtimeHighlight = true
app.runtimeHighlightColor = color.blue

toolbar

Exists for compatibility reasons. Always returns true

toolbarHorizontal

Exists for compatibility reasons. Always returns true

toolbarVertical

Exists for compatibility reasons. Always returns true

viewerType

Exists for compatibility reasons. Always returns "Exchange-Pro"

viewerVariation

Exists for compatibility reasons. Always returns "Full"

viewerVersion

Exists for compatibility reasons. Always returns 8

viewerVersionRevu

Returns the current Revu version (i.e. 21.3.0.4216)

The presence of this property is the best way to determine that the PDF is running in the context of Revu.

example:

console.println(app.viewerVersionRevu)

methods

alert

Displays an alert box

alert(cMsg, nIcon, nType, cTitle, oDoc, oCheckbox)

cMsg: The message to be displayed

nIcon: [optional] The icon type

• 0: Error (default value)
• 1: Warning
• 2: Question
• 3: Status

nType: [optional] The button types

• 0: OK (default value)
• 1: OK, Cancel
• 2: Yes, No
• 3: Yes, No, Cancel

cTitle: [optional] The alert box title, default is "Bluebeam Revu x64"

oDoc: [optional] The Doc object associated with the alert box. Not used by Revu

oCheckbox: [optional] Checkbox object that results in a checkbox shown in the alert box. Requires Revu 21.5 or above

• cMsg: [optional] Checkbox string, default is "Do not show this message again"
• bInitialValue: [optional] Initial state of the checkbox, default is false
• bAfterValue: State of the checkbox after alert box closes

examples:

app.alert("My Message")

var checkBox = { cMsg: "Suppress going forward", bInitialValue: true }

app.alert("Warning! Something interesting happened", 1, 0, "Warning", this, checkBox)

if (checkBox.bAfterValue) {
    console.println("You wish to suppress this dialog in the future")
} else {
    console.println("You wish to see the warning again")
}

beep

Causes the application to play a sound

app.beep(nType)

nType: [optional] The sounds type

• 0: Error
• 1: Warning
• 2: Question
• 3: Status
• 4: Default (default value)

example:

app.beep(2) // Plays the question sound

beginPriv

Begins elevated privileges

app.beginPriv()

Elevates the priviledges of the current function so that secure calls can be made until app.endPriv is called. app.beginPriv can only be called within a function that is trusted. See trustedFunction for more information. Used with endPriv and trustPropagatorFunction.

clearInterval

Clears a timer previously set by setInterval.

app.clearInterval(oInterval)

oInterval: Object returned by setInterval

clearTimeOut

Clears a timer previously set by setTimeOut.

app.clearTimeOut(oTime)

oTime: Object returned by setTimeOut

endPriv

Ends elevated privileges

app.endPriv()

Returns elevated privilege in a trusted function back to normal such that secure functions can no longer be called. Used in conjunction with app.beginPriv and app.trustedFunction.

execDialog

Displays a custom modal dialog to the user.

app.execDialog(monitor, inheritDialog, parentDoc)

monitor: Object that describes the dialog

inheritDialog: [optional] Dialog object to reuse. Not used by Revu

parentDoc: [optional] Doc object to be used as the parent. Not used by Revu

Returns a string matching an ItemID found in the monitor object

monitor

The monitor parameter is an object literal. Some properties are callback functions that are each called at various points of the lifecycle of the dialog and the description property represents the contents of the dialog.

All callback functions take a single parameter, dialog of type Dialog.

Dialog

A Dialog object is passed into each of the above callbacks and has the following methods.

description

The description parameter of the monitor object is also an object literal that describes the UI elements of the dialog.

align_children

The following are the valid options for align_children

• "align_left"
• "align_center"
• "align_right"
• "align_top"
• "align_fill": Stretches across the parent
• "align_distribute": Distributes horizontally
• "align_row": Behaves the same as "align_distribute"
• "align_offscreen": Behaves the same as "align_fill"

elements

The elements parameter of the description object is an array of element objects with the following properties

type

• "button": Button
• "check_box": Checkbox
• "radio": Radiobutton
• "list_box": List box
• "hier_list_box": Tree
• "static_text": Label
• "edit_text": Text Box
• "popup": Combo Box
• "ok": Ok button
• "ok_cancel": Ok and Cancel buttons
• "ok_cancel_other": Ok, Cancel, and Other buttons
• "view": Container that holds child elements
• "cluster": Container with a frame that holds child elements
• "gap": Spacer

There are a few additional properites for element objects dependent on the type

example:

Document level script:

// Suggestion entry form where a user can choose whether a bug or a feature
var dialogSuggestion = {
    initialize: function(dialog) {
        console.println("initialize")
        // Set to a feature by default
        dialog.load({"rd02": true})
        this.isBug = false
        // Disable bug type because it is a feature by default
        dialog.enable({
            "rd03" : this.isBug,
            "rd04" : this.isBug
        });
    },
    commit: function(dialog) {
        // When the user presses "Ok", this handler will execute first
        console.println("commit")
        var results = dialog.store()

        console.println("Title: " + results["edt1"])
        console.println("Description: " + results["edt2"])
        console.println("Type: " + (results["rd01"] ? "Bug" : "Feature"))
        if (this.isBug) {
            console.println("Bug Type: " + (results["rd03"] ? "New" : "Regression"))
        }
    },
    ok: function(dialog) {
        console.println("Ok")
    },
    rd01: function (dialog) {
        this.toggleIsBug(dialog) // Toggle for changing either Bug or Feature
    },
    rd02: function (dialog) {
        this.toggleIsBug(dialog)
    },
    toggleIsBug: function(dialog) {
        this.isBug = !this.isBug;
        dialog.enable({
            "rd03" : this.isBug,
            "rd04" : this.isBug
        });
        if (!this.isBug) {
            dialog.load({
                "rd03": false,
                "rd04": false 
            })
        }
    },
    cancel: function(dialog) {
        console.println("Cancel")
    },
    description:
    {
        name: "Suggestion",
        elements:
        [
            {
                type: "view",
                align_children: "align_left",
                elements: [
                    {
                        type: "view",
                        align_children: "align_row",
                        elements: [
                            {
                                type: "static_text",
                                name: "Title:",
                                width: 100,
                                height: 20
                            },
                            {
                                type: "edit_text",
                                name: "",
                                item_id: "edt1",
                                width: 200,
                                height: 20
                            }
                        ]
                    },
                    {
                        type: "view",
                        align_children: "align_row",
                        elements: [
                            {
                                type: "static_text",
                                name: "Description:",
                                width: 100,
                                height: 20
                            },
                            {
                                type: "edit_text",
                                name: "",
                                item_id: "edt2",
                                width: 200,
                                height: 100,
                                multiline: true
                            }
                        ]
                    },
                    {
                        type: "view",
                        align_children: "align_row",
                        elements: [
                            {
                                type: "static_text",
                                name: "Type: "
                            },
                            {
                                type: "radio",
                                item_id: "rd01",
                                group_id: "rad0",
                                name: "Bug"

                            },
                            {
                                type: "radio",
                                item_id: "rd02",
                                group_id: "rad0",
                                name: "Feature",
                            }
                        ]
                    },
                    {
                        type: "view",
                        align_children: "align_row",
                        elements: [
                            {
                                type: "static_text",
                                name: "Bug Type: "
                            },
                            {
                                type: "radio",
                                item_id: "rd03",
                                group_id: "rad1",
                                name: "New"

                            },
                            {
                                type: "radio",
                                item_id: "rd04",
                                group_id: "rad1",
                                name: "Regression",
                            }
                        ]
                    }
                ]
            },
            {
                type: "gap",
                height: 10
            },
            {
                type: "ok_cancel"
            }
        ]
    }
};

Button event:

app.execDialog(dialogSuggestion)

execMenuItem

Executes a menu item. The only command supported by Revu is "SaveAs".

app.execMenuItem(cCommand)

cCommand: command to execute

example:

app.execMenuItem("SaveAs")

getPath

Returns specfic paths based on a category and requested folder type

app.getPath(cCategory, cFolder)

cCategory: [optional] category of requested folder

• "app": application level folders (default value)
• "user": user level folders

cFolder: [optional] particular folder

• "javascript": app level JavaScript folder (applicable only for "app")
• "stamps": stamp folder (applicable only for "app")
• "root": user's preference folder (default value, applicable only for "user")
• "documents": user's "My Documents" folder (applicable only for "user")

example:

console.println(app.getPath("app", "javascript"))

which prints the following:

/C/ProgramData/Bluebeam Software/Bluebeam Revu/21/Revu/JavaScript

goBack

Navigates backward

app.goBack()

Navigates the user to the previous view in the view stack. This is equivalent of a user clicking the 'Previous View' button in Revu.

example:

var button = this.getField("backButton")
if (!button) // Check if button exists already
{
    var aRect = this.getPageBox()
    var width = aRect[2] - aRect[0]
    var height = aRect[1] - aRect[3]
    rect = [width / 2 - 40, 
            height - 36, 
            width / 2 + 40, 
            height - 15] // Button is 80x21
    button = this.addField("backButton", "button", 0, rect)
    button.fillColor = color.ltGray
    button.strokeColor = color.black
    button.borderStyle = border.b
    button.buttonSetCaption("Back")             
    button.setAction("MouseUp", "app.goBack()")
}

This example creates a back navigation button. This could be a document level script which would run when the PDF opens. It checks to see if the back button exists, and if not it creates one. This example could be expanded to loop over all pages in a document to create a button per page.

goForward

Navigates forward

app.goForward()

Navigates the user to the next view in the view stack. This is equivalent of a user clicking the 'Next View' button in Revu.

See app.goBack for a relevant example

launchURL

Launches a URL as a WebTab in Revu

app.launchURL(cURL, bNewFrame)

cURL: URL to launch

bNewFrame: [optional] Specifies whether to create a new window, default is false. Not used by Revu

When called from an untrusted context, LaunchURL will prompt the user with a security warning and they must click 'Allow' for the URL to launch.

example

app.launchURL("www.bluebeam.com")

mailMsg

Sends an e-mail using the default e-mail program configured with MAPI

app.mailMsg(bUI, cTo, cCc, cBcc, cSubject cMsg)

bUI: Specifies whether to show the e-mail window before sending. Revu ignores this value acting as though it is always true.

cTo: [optional] List of e-mail addresses separated by semicolons

cCC: [optional] List of CC addresses separated by semicolons

cBcc: [optional] List of BCC addresses separated by semicolons

cSubject: [optional] Subject line of e-mail

cMsg: [optional] Message body of e-mail

example:

app.mailMsg(true, "support@bluebeam.com", "". "", "Subject", "Message")

openDoc

Opens a PDF document and returns the corresponding Doc object.

app.openDoc(cPath, oDoc, cFS, bHidden, bUseConv, cDest)

cPath: Device-independent path to the PDF file to open.

oDoc: [optional] Doc object used to resolve relative paths. Default is null.

cFS: [optional] Only the empty string is supported, which specifies that the path is to a file on the local file system. Default is "".

bHidden: [optional] Specifies whether or not to open the file as a tab in Revu. Default is false.

bUseConv: [optional] Revu ignores this value acting as though it is always false

cDest: [optional] Named destination (known as a 'Place' in Revu), specifying a location in the PDF file to navigate to.

example:

var doc = app.openDoc("/c/path/to/my/file.pdf")

popUpMenu

Displays a Popup menu to the user. Note: popUpMenuEx is the preferred method for showing Popup menus.

app.popUpMenu(...items)

items: Can be either strings or Arrays. If the parameter is a string, the result is a menu item with that value. "-" is a special case that represents a separator. If the parameter is an Array, a sub-menu is created where the first element in the array is the parent node, and the remaining elements are the sub-menu. Arrays can be nested further.

Returns the menu item selected by the user

simple example:

var selection = app.popUpMenu("Menu Item")

nested example:

var selection = app.popUpMenu(
    "Node 1",
    "-",
    ["Node 2", "Child 1", "Child 2"],
    ["Node 3", "Child 3", "Child 4"]
)

popUpMenuEx

Requires Revu 21.5 or above

Displays a Popup menu to the user.

app.popUpMenuEx(...items)

items: One or more MenuItem objects.

Returns the cReturn parameter of the selected item, or null if no item was selected.

example:

// Loosely equivalent to the popUp example, but also showing bMarked and cReturn
var selection = app.popUpMenuEx(
    {cName: "Node 1"},
    {cName: "-"},
    {cName: "Node 2", oSubMenu: 
        [
            {cName: "Child 1", bMarked: true, cReturn: "C1"},
            {cName: "Child 2", cReturn: "C2"}
        ]
    },
    {cName: "Node 3", oSubMenu: 
        [
            {cName: "Child 3", cReturn: "C3"},
            {cName: "Child 4", cReturn: "C4"}
        ]
    }
)
app.alert(selection)

response

Displays a dialog box prompting the user with a question and an input box.

app.response(cQuestion, cTitle, cDefault, bPassword, cLabel)

cQuestion: The question.

cTitle: [optional] Dialog box title.

cDefault: [optional] Default value for the answer. Default is ""

bPassword: [optional] If true, hides the users reponse with asterisk characters. Default is false

cLabel: [optional] Label before the input box. Default is ""

Returns a string with the user's reponse. If the clicks cancel, null will be returned.

example:

var response = app.response({
    cQuestion: "What is your name?",
    cTitle: "Enter Name",
    cDefault: "John Doe",
    cLabel: "Name"
})
if (response != null)
    app.alert("Your name is " + response)

setInterval

Sets a JavaScript expression to run at specific time intervals.

app.setInterval(cExpr, nMilliseconds)

cExpr: JavaScript expression to run

nMilliseconds: Time interval in milliseconds

Returns an object that can be used when calling clearInterval

example:

// Goes in a document level script
// Moves the button back and forward on the screen until the user clicks the button

var forward = true

function callback() {
    var b = this.getField("movingButton")
    var rect = b.rect
    if (forward && rect[2] < 602) { // Because 8.5 inches is 612 points
        rect[0] += 10
        rect[2] += 10
        b.rect = rect
    } else {
        forward = false
    }

    if (!forward && rect[0] > 10) {
        rect[0] -= 10
        rect[2] -= 10
        b.rect = rect
    } else {
        forward = true
    }
}

var aRect = this.getPageBox()
var width = aRect[2] - aRect[0]
var height = aRect[1] - aRect[3]
rect = [width / 2 - 40, 
        height - 36, 
        width / 2 + 40, 
        height - 15] // Button is 80x21
var button = this.addField("movingButton", "button", 0, rect)
button.fillColor = color.ltGray
button.strokeColor = color.black
button.borderStyle = border.b
button.buttonSetCaption("Stop Me!")             
button.setAction("MouseUp", "app.clearInterval(intervalObj)")

var intervalObj = app.setInterval("callback()", 100)

setTimeOut

Sets a JavaScript expression to run after a set time elapses. Similar to setInterval with the difference that the expression only runs once.

app.setTimeOut(cExpr, nMilliseconds)

cExpr: JavaScript expression to run

nMilliseconds: Time interval in milliseconds

Returns an object that can be used when calling clearTimeOut

example:

var timeoutObj = app.setTimeOut("app.alert('I was set to go 5 seconds ago')", 5000)

trustedFunction

Establishes trust for a function in a folder level script to be able to have secure code that can be called from untrusted contexts.

trustedFunction(oFunc)

oFunc: Function to trust

Certain functions, such as util.readFileIntoStream, must be run securely. Arbitrary PDF files of unknown origin should not be able to ready the contents of files off disk. There are 3 ways to be able to safely execute these secure functions.

1. Trust a specific file or folder in Revu preferences
2. Trust certified PDF files in Revu preferences
3. Mark functions in folder level scripts as trusted

trustedFunction corresponds to method 3 in the above list. trustedFunction is used in conjunction with beginPriv, endPriv, and trustPropagatorFunction so that PDFs regardless of where they are stored are able to call secure functions.

A use case for using trustedFunction would be an organization that wants to push out a company specific JavaScript library of secure code across their organization by rolling out a .js file to the app level JavaScript folder of each users computers, and then embed JavaScript in PDF files that call into functions inside this JavaScript library. For reference, the app level folder is: C:\ProgramData\Bluebeam Software\Bluebeam Revu\21\Revu\JavaScript

A function that calls secure code would be passed into trustedFunction, and then within that function any secure blocks would need to be wrapped between calls of app.beginPriv and app.endPriv. If there are intermediate helper functions that call secure code, then app.trustPropogatorFunction must be used to mark that the helper functions should inherit any trust granted by a function that was passed into trustedFunction.

example:

Folder level JavaScript:

trustedReadFile = app.trustedFunction(function(path) {
    app.beginPriv()
    var s = util.readFileIntoStream(path)
    app.endPriv()
    return s
})

MouseUp button JavaScript:

var stream = trustedReadFile("/path/to/my/file.txt") // Your path would be here
var contents = util.stringFromStream(stream)
app.alert(contents)

See that the mouse up handler is calling the secure function trustedReadFile found in the folder level script. Without calling trustedFunction and using beginPriv/endPriv, there would be a security error.

trustPropagatorFunction

Cascades trust when helper functions are called from trusted functions. See trustedFunction

app.trustPropagatorFunction(oFunc)

oFunc: Function that should inherit trust

example:

trustedHelper = app.trustPropagatorFunction(function() {
    app.beginPriv()
    // Secure code
    app.endPriv()
})

trustedFunction = app.trustedFunction(function() {
    app.beginPriv()
    trustedHelper()
    app.endPriv()
})

objects

MenuItem

Object that represents the parameters of popUpMenuEx. The object has the following properties:

cName: Menu item name. "-" is used to specify a separator.

bMarked: [optional] Boolean specifying if the item is checked

bEnabled: [optional] Boolean specifying if the item is enabled

cReturn: [optional] String specifying the return value if the item is selected. Default is cName

oSubMenu: [optional] A MenuItem object or array of MenuItem objects representing a submitem