Pins & Boxes Scripting API

All functions of Pins & Boxes can also be remote-executed from other scripts. It supports exactly the same functions as the build-in KBar-API, so please refer to the KBar API documentation for the documentation of all available functions.

Using the API is best explained with an example:

/*
This document explains how to remote-execute functions of Pins & Boxes
from other Ae scripts.

The API object used here has the same functions as the KBar API
(see https://mamoworld.com/article/pins-boxes-kbar-api)
*/

// let's get the API to do something with Pins & Boxes.
// Pass a file object to PinsAndBoxes.jsxbin as argument
// of the getPinsAndBoxes() call
// if it is not in the same folder as this script.
// See definition of this function at the end of this file
var API = getPinsAndBoxes();

// creates pins for the first layer of the active comp
var myPinLayers = API.newPins({motherLayerArray:[app.project.activeItem.layer(1)]});
// creates a shape layer box around the pins
var shapeLayerBox = API.newBox({pinLayerArray: myPinLayers, layerType:"Shape", marginLeft:50, marginRight:50, marginTop:5,marginBottom:5});
// creates some pins for the shape layer at the topLeft and bottomRight corner only
var shapePinLayers = API.newPins({
    motherLayerArray:[shapeLayerBox],
    scaleFactor: 0.5, // make the pins half the size as normal pins
    // for which locations pins should be created:
    topLeft:true,
    top:false,
    topRight:false,
    left:false,
    center:false,
    right:false,
    bottomLeft:false,
    bottom:false,
    bottomRight:true
});

// set opacity of the box to 50%
shapeLayerBox.property("ADBE Transform Group").property("ADBE Opacity").setValue(50);




/*
This function creates the pinsAndBoxes object if it does not exist yet

If scriptFile is undefined, this function assumes that PinsAndBoxes.jsxbin is
in the same folder as this script file. Otherwise, please pass a file object
for PinsAndBoxes.jsxbin as scriptfile argument.
*/

function getPinsAndBoxes(scriptFile){
    if(typeof pinsAndBoxes == 'undefined'){
        return executePinsAndBoxes(scriptFile);
    }
    return pinsAndBoxes;


    function executePinsAndBoxes(scriptFile){
        if(scriptFile === undefined){
            scriptFile = getPinsAndBoxesFromDefaultLocation();
        }
        if(!scriptFile.exists) throw new Error("could not find file "+scriptFile.fsName);
        scriptFile.open("r");
        var fileContents =  scriptFile.read();
        scriptFile.close();

        // yes, this is a global variable.
        // we use this kbar API to tell Pins & Boxes that it should not show its user interface
        // and return its API instead
        kbar = { button:{argument:"getAPI"}};
        // execute the file --> this should create the pinsAndBoxes object
        var result = eval(fileContents);

        // when Pins & Boxes understands the button command, it will set it to undefined.
        if(kbar.button !== undefined){
            throw new Error("Pins & Boxes didn't understand the getAPI action, is scriptFile pointing to another script?");
        }
        return result;
    }

    function getPinsAndBoxesFromDefaultLocation(){
        // get the folder where this script file is located
        var myFolder = (new File($.fileName)).parent;
        // find PinsAndBoxes.jsxbin in the same folder
        var scriptFile = new File(myFolder.fsName+"/PinsAndBoxes.jsxbin");
        return scriptFile;
    }
}

What about licenses?

Of course, the API will only work if a proper Pins & Boxes license is installed.