Miscellaneous Topics

API Calling Conventions

Revu's JavaScript API supports two ways to call functions: positional parameters and named parameters using an object literal. This flexibility allows you to choose the style that best fits your needs.

Positional Parameters

The traditional approach passes parameters in order:

app.alert("My Message", 1, 0, "Warning")

Named Parameters

Alternatively, pass a single object with named properties:

app.alert({
    cMsg: "My Message",
    nIcon: 1,
    nType: 0,
    cTitle: "Warning"
})

Both calls are identical. The parameter names in the object must match exactly those defined in the API (like cMsg, nIcon, etc.). This is why parameter names are precisely specified in the documentation.

Mixed Usage

When using named parameters, you can omit optional parameters more easily:

// Positional - must include placeholders
app.alert("Message", 1, 0, "Title", null, checkboxObj)

// Named - only include what you need
app.alert({
    cMsg: "Message",
    nIcon: 1,
    cTitle: "Title",
    oCheckbox: checkboxObj
})

PDF-Specific Objects

Rectangles

Many PDF operations use rectangle arrays to define areas on a page. A rectangle is an array of four numbers: [left, top, right, bottom].

// Define a rectangle for a form field
var rect = [72, 720, 216, 648]  // 2x1 inch box near top-left

// Add a text field using the rectangle
this.addField("myField", "text", 0, rect)

// Get a field's rectangle
var field = this.getField("myField")
var fieldRect = field.rect  // Returns [left, top, right, bottom]

Important: PDF coordinates start from the bottom-left corner of the page, with Y increasing upward. This is opposite from many graphics systems where Y increases downward.

Colors

Colors in PDF JavaScript are represented as arrays in various color spaces:

// Predefined colors
var red = color.red      // ["RGB", 1, 0, 0]
var blue = color.blue    // ["RGB", 0, 0, 1]

// Custom colors
var gray = ["G", 0.5]                    // Grayscale
var rgb = ["RGB", 0.5, 0.7, 0.3]        // RGB
var cmyk = ["CMYK", 0.1, 0.2, 0.3, 0]  // CMYK

// Using colors
field.fillColor = color.yellow
field.strokeColor = ["RGB", 0.5, 0.5, 0.5]

Spans

Text spans are objects that define formatted text segments:

var spans = [
    { text: "Regular text " },
    { text: "Bold text", fontWeight: 700 },
    { text: " and ", fontStyle: "italic" },
    { text: "colored", textColor: color.red }
]

field.richText = spans

Units and Measurements

Points

Most measurements in PDF JavaScript use points as the unit:

72 points = 1 inch
1 point = 1/72 inch

Common conversions:

// Convert inches to points
function inchesToPoints(inches) {
    return inches * 72
}

// Convert points to inches
function pointsToInches(points) {
    return points / 72
}

// Page dimensions are in points
var pageSize = this.getPageBox()
var widthInPoints = pageSize[2] - pageSize[0]
var widthInInches = widthInPoints / 72

// Standard page sizes in points
// Letter: 612 x 792 (8.5" x 11")
// Legal: 612 x 1008 (8.5" x 14")
// Tabloid: 792 x 1224 (11" x 17")

Working with Measurements

When positioning elements, remember to convert units:

// Position a field 2 inches from left, 3 inches from bottom
var leftInches = 2
var bottomInches = 3
var widthInches = 1.5
var heightInches = 0.5

var rect = [
    leftInches * 72,                          // left
    bottomInches * 72 + heightInches * 72,    // top
    leftInches * 72 + widthInches * 72,       // right
    bottomInches * 72                         // bottom
]

this.addField("myField", "text", 0, rect)

Special Considerations

Page Coordinate System

PDF coordinates differ from typical screen coordinates:

Origin (0,0) is at the bottom-left corner
Y values increase upward
X values increase to the right (standard)

var pageBox = this.getPageBox()  // Returns [0, 0, 612, 792] for letter
// pageBox[0], pageBox[1] = bottom-left (usually 0, 0)
// pageBox[2], pageBox[3] = top-right (width, height in points)

Field Naming

Form fields in PDFs support hierarchical naming using dots:

// Create related fields with hierarchical names
this.addField("address.street", "text", 0, rect1)
this.addField("address.city", "text", 0, rect2)
this.addField("address.zip", "text", 0, rect3)

// Access parent group
var addressFields = this.getField("address")  // Gets all address.* fields

String Encoding

When working with file paths or special characters:

// Use forward slashes for paths, even on Windows
var path = "/C/Users/Documents/file.pdf"  // Correct
// var path = "C:\\Users\\Documents\\file.pdf"  // Avoid

// Device-independent paths start with /
var devicePath = "/C/folder/file.txt"  // Windows C: drive

Quick Reference

Calling styles:

Positional: func(param1, param2, param3)
Named: func({name1: param1, name2: param2})

Common objects:

Rectangle: [left, top, right, bottom] in points
Color: ["RGB", r, g, b] or ["CMYK", c, m, y, k]
Span: {text: "string", fontWeight: 700}

Key measurements:

72 points = 1 inch
Letter page = 612 x 792 points
Origin at bottom-left, Y increases upward

Moving Forward

These conventions and objects are foundational to working with PDFs in Revu. Understanding coordinate systems, units, and calling conventions will help you write cleaner, more maintainable code as you build interactive PDF solutions.

Keyboard shortcuts

Revu JavaScript