Grapple Download

Make and use your own tools.

A plugin is a tool you pick up like the Pen. It draws on the Viewer and the Timeline, puts its settings in the Inspector, and sends every edit through History. Grapple draws its interface with its own controls, so it looks and behaves like the rest of the app.

The Plugins tab

The Plugins tab sits beside Project and History. Each plugin is a card with its name, what it does, and where it works: Panel, Viewer or Timeline. A card also shows when a plugin isn't ready, with "Needs your approval", or "Not available" and the reason.

  • Import takes a .grapple-tool file or a plugin folder.
  • Make with Ape opens Ape ready to write one.
  • A card's menu has Inspect (the manifest and every source file), Edit with Ape, Duplicate, Export… and Remove.

Each project keeps its own copy of the plugins it uses, so removing one from your library breaks nothing.

Use a plugin

  1. Click the plugin's card in the Plugins tab. The card shows as selected, the plugin's icon joins the end of the Stage's tool rail, and its section opens at the top of the Inspector.
  2. Set what it acts on. Each target has a row, such as "3 selected layers" or "Not set", and Use selection fills it from what you've selected.
  3. Use its panel, and its shapes on the Viewer and the Timeline. They draw and take your input only while the plugin is in your hand, and a press outside them still selects as usual.

Choose another tool, or Stop using in the menu of the plugin's Inspector section, and the plugin steps aside. Click its card again and its settings come back. Each action is one History row, named by the action's label.

Approve a plugin

The first time you use a plugin version that runs code, or asks for more than reading, on your computer, Grapple shows its own dialog titled with the plugin's name, such as Allow "Nudge" to run?

  • It lists each action with "Edits your project" or "Reads your project".
  • It ends: "Its code runs isolated from your files, other apps and the network."
  • Cancel is the default.

Approval is for that exact version, so a changed plugin asks again. Ape can't approve a plugin: when Ape calls one that needs approval, you see the same dialog and Ape waits for your answer.

Ask Ape to make one

  1. Choose Make with Ape in the Plugins tab. Ape opens with a request to use its plugin-writing skill already in the composer. Or just describe the tool in the Ape chat.
  2. Say what it does, its settings and its buttons: "Make a plugin called Nudge with one number, Distance in pixels, and a button that moves the selected layers right by that distance."
  3. Ape writes the plugin with its plugin guidance, validates it and installs it in your library. Click its card and approve it to use it.

To change a plugin later, choose Edit with Ape on its card.

Write a plugin

A plugin is a manifest, an interface document and a Python file. This manifest describes Nudge:

{"schemaVersion": 2, "id": "personal.nudge", "version": "1", "label": "Nudge",
 "description": "Moves the selected layers right by a chosen distance.",
 "ui": "ui.json", "python": "main.py",
 "capabilities": ["project.read", "project.edit"],
 "settings": [{"id": "distance", "label": "Distance in pixels",
               "valueType": "number", "default": 10}],
 "actions": [{"id": "nudge_right", "label": "Nudge right",
              "effect": "projectEdit", "arguments": ["distance"]}]}

And this is its main.py:

import grapple as gp

def nudge_right(ctx, distance):
    for layer in ctx.selection:
        position = layer.get("Position")
        layer.set("Position", gp.Vec2(position.x + distance, position.y))
One function per action
Named by the action's id, taking ctx and the action's arguments.
One action, one History row
Named by the action's label, and taken back with one undo.
Settings save themselves
A control bound to a setting saves it when you commit a value, for the session or with the project.
Code runs on commit
A button, a committed value, the end of a drag, or a call from Ape. During a drag, Grapple only redraws the plugin's views.

Project Python modules, scripts and effects are the other ways to build your own tools: see Python in Grapple.

When a plugin doesn't validate

Grapple tells you what to write without running the code, naming the file and line, such as "main.py: define def nudge_right(ctx, distance): for the action nudge_right." An interface that doesn't validate shows a sentence beginning "Fix this interface definition:" where the interface would be. Edit with Ape opens Ape on a copy, ready to fix it.