# Macros

Macros are scripts which automate Komodo. They are stored toolboxes and can be launched by double-clicking the macro icon, pressing an associated custom key binding, or by binding them to event triggers.

The Macros toolbar provides quick access for recording, running, and saving macros. To show or hide the toolbar, select View|Toolbars|Macros. You can also use the Tools|Macros menu items.

## Creating Macros

Macros can be created by recording keystroke and command sequences, or written from scratch in JavaScript or Python using the Macro API.

### Recording Macros

Recording is a simple method for creating a macro. Only keystrokes (not mouse movements) are recorded.

To record a macro:

1. Select Tools|Macros|Start Recording (or use the Record Macro button in the Macro toolbar). The Komodo status bar displays "Recording Macro".
2. In the Editor Pane, enter the keystrokes to store in the macro. While entering keystrokes, pause recording by selecting Tools|Macros|Pause Recording. Select Start Recording when ready to resume macro creation.
3. To end macro recording, select Tools|Macros|Stop Recording. The status bar displays "Macro Recorded".

Note: Though keystrokes in the Editor pane can be captured and recorded in this manner, several Komodo commands cannot. If your resulting macro does not replay certain operations, you may be able to add them manually by editing the recorded macro. Consult the Writing Macros section in conjunction with the Command ID List and the Macro API for further information.

To save the most recent macro:

1. Select Tools|Macros|Save to Toolbox, or click Macro: Save to Toolbox on the Macro Toolbar.
2. Give the new macro a unique name in the Enter name for new macro field. A reference to the macro is automatically added to the Toolbox.

### Writing Macros

Use the "New Macro" Properties dialog box to write macros in either Python or JavaScript. This dialog box has tabs for specifying key bindings and Komodo event triggers that invoke the macro automatically.

To add a macro:

1. Select Add New Macro... from the Toolbox drop-down menu or a folder's right-click context menu.
2. Language: Specify the language (Python or JavaScript) in which to program the macro.
3. Set any desired macro properties.
4. Write the macro in the editor field or save what you have so far by clicking OK. You can open it in an editor tab by right-clicking on the macro icon and selecting Edit Macro. This is useful as it provides autocompletion and other Komodo editing features.

Refer to the Macro API for information about writing JavaScript and Python macros in Komodo.

## Running Macros

To run the most recently recorded macro, select Tools|Macros|Execute Last Macro. If the Macro Toolbar is open (View|Toolbars|Macro), click Macro: Run Last Macro.

To run a macro that has been saved to a project or toolbox, double-click the macro or use the key binding you have assigned to it. Alternatively, right-click the macro and select Execute Macro.

## Managing Macros

Macros can be dragged into any toolbox or toolbox folder. Right-clicking on a macro brings up a context menu with the following additional options:

- Execute Macro: Runs the selected macro.
- Edit Macro: Opens the macro in an editor tab.
- Cut/Copy/Paste: Used to duplicate or move a macro when dragging is not convenient (e.g. to a project which is currently closed).
- Show in File Manager: Shows the JSON file for the macro in the system's default file manager.
- Export as Zip File...: Exports the macro in a standard ".zip" archive.
- Rename: Changes the macro name.
- Delete: Permanently removes the selected macro from the toolbox.

## Macro Properties

Right-click on a macro and select Properties to view or edit the macro or configure the following properties.

### Assigning Key Bindings to Macros

Use the Key Binding tab to specify a key combination or sequence for invoking the macro. To add a new keybinding:

1. Select the New Key Sequence field
2. Press the desired key combinations. The Key Sequence Currently Used By field will alert you if there are any conflicts.
3. Click Add (multiple keybindings are allowed).
4. Click OK on the Properties dialog box to close it.

If the macro is in a toolbox, the assigned keybinding will always trigger the macro. If it's in a project, the keybinding will work only when that project is open.

### Assigning Custom Icons to Macros

The default macro icon can be replaced with custom icons. Komodo includes more than 600 icons, but you can use any 16x16-pixel image you wish.

To assign a custom icon to a macro:

1. In the macro's Properties dialog box, click Change Icon.
2. In the Pick an Icon dialog box, select an icon set from the drop list, choose a new icon, and click OK. To choose an icon from your filesystem, click Choose Other, and browse to the desired image file.
3. Click OK on the Properties dialog box to close it. The custom icon is displayed next to the macro.

To revert to the default icon for a selected macro, use the Reset button.

### Running Macros in the Background

Macros that invoke and do not affect the current file should be run in the background to minimize interference with Komodo responsiveness. Macros that run in the background are run in threads (Python), or in a timeout (JavaScript). To set this option:

1. Right-click the macro in the Toolbox and select Properties.
2. Select the Run in Background option.
3. Click Apply.

If a macro is not associated with a Komodo event, it can run either in the foreground or in the background.

Macros that perform "editor" functions or modify open files should always run in the foreground to "block" and prevent user interference. This prevents the user from moving the cursor and disrupting the macro currently in progress.

### Specifying Macro Triggers

Macros can be configured to execute on certain Komodo events. When an event occurs (for example, a file is opened in Komodo), the macro is triggered.

Check to make sure macro triggers are enabled in the Projects and Workspace preferences. In the Triggering Macros area, select Enable triggering of macros on Komodo events, and then click OK.

To add a trigger to a macro:

1. Select the Triggers tab on the Macro Properties dialog
2. Select the Macro should trigger on a Komodo event check box.
3. Choose one of the following triggers:
   - On startup (occurs at the end of the Komodo startup process)
   - After file open
   - Before file save (see Macro Return Values below)
   - After file save
   - Before file close (see Macro Return Values below)
   - After file close
   - On shutdown (see Macro Return Values below)
   - On a system notification
4. Set the Rank (optional): Enter a numerical rank for the macro. For example, if three macros all invoke "After a file is opened", a macro executes first (100), second (101), or third (102). The default is 100 to provide room for macros to run before the default (1-99). Note that if two macros trigger on the same event with the same rank, both execute in indeterminate order.
5. Click Apply.

#### Trigger Macro subject Variable

Trigger macros run with an argument called "subject", available as a global variable within the macro. This variable references the ko.views.manager.currentView object for post-open, pre/post-save, and pre-close trigger macros. For post-close macros, it references the URI since the view object is empty at that point. For example, in a macro with an "After file open" trigger you could use:

    alert("Just opened file " + subject.document.displayPath);

#### Macro Return Values

Komodo macros that use the event triggers "Before file save", "Before file close", or "On shutdown", can make use of return values. Macros that return that return a true value (e.g. `True` in Python, `true` in JavaScript) can interrupt the process under execution. For example, the following JavaScript macro triggering "Before file save" prevents you from saving files on Sunday:

    var currentTime = new Date();
    if (currentTime.getDay() == 7) {
      alert("Never on a Sunday!")
      return true;
    }
    else {
      return null;
    }

## Vi Command Mode Macros

Komodo's Vi emulation offers a command-line mode. Entering ':' opens a text box for entering commands. To access a macros from this mode, create a toolbox folder named Vi Commands and move or copy the macro into it. Type the macro name in the Vi command text box to run it.