Macros

A macro consists of keystroke sequences that are recorded, saved, and executed either manually, via a key binding, or with an event trigger. When the macro is invoked, the recorded keystrokes and instructions execute. Only keystrokes (not mouse movements) are recorded within macros. Note that, with the exception of the Find dialog box, macros that call external dialog boxes are not supported. Macros are stored in projects or the Toolbox. Custom key bindings can be assigned to macros.

The Macros toolbar provides quick access for recording, running, and saving macros. To open or close the toolbar, select View|Toolbars|Macros. Alternatively, select Tools|Macros.

Creating Macros

Macros can be created via recording keystrokes, or by programming macro commands in the Macros properties dialog. For information about programming macros, refer to the Macro API.

 

Recording Macros

Recording is a simple method for creating a macro. Recording a macro requires typing a series of keystrokes in the Editor Pane. To record a macro:

  1. Select Tools|Macros|Start Recording. 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".

Alternatively, use the Macros Toolbar to invoke the commands.

 

Saving Recorded Macros

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.

 

Programming Macros

Use the "New Macro" Properties dialog box to program macros in either Python or JavaScript. Additionally, use this dialog box to specify macro key bindings and Komodo triggers that invoke the macro automatically.

To add a macro:

  1. Select Toolbox|Add|New Macro... or Project|Add|New Macro.... Alternatively, use the Add buttons within the Project or Toolbox tab, or right-click a project or folder name and select Add.
  2. On the Macro tab, configure the following options:
    • New Macro: Enter the name of the macro (displayed in the Toolbox and Project Manager) in the field.
    • Change Icon: Click to select a custom icon to associate with this macro.
    • Reset: Clears the icon choice.
    • Language: Specify the language (Python or JavaScript) in which to program the macro.
  3. Program the macro in the Language editor field.
  4. Click OK.

Refer to the Macro API for information about programming macros.

 

Running Macros

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

To run a macro that has been saved to a file and assigned to a project or to the Toolbox, double-click the macro, or use the key binding assigned to the macro. Alternatively, right-click the macro in the Project Manager or the Toolbox and select Execute Macro from the context menu.

 

Specifying Macro Triggers

Macros can be configured to execute based on certain Komodo events or triggers. When an event occurs (for example, a file is opened in Komodo), the macro is triggered and then executes. A macro that triggers "editor" functions or modifies open files should run in the foreground to block user access to the editor. Macros running in the foreground run and "block" until they return. This prevents the user from moving the cursor and disrupting the macro currently in progress.

Macro Return Values

Use the Macros Properties dialog box to specify a macro return value. Entering return 1; is syntactically valid as a true value in either Python or JavaScript. Macros that return true and invoke before a Komodo event can interrupt the process under execution. For example, a macro can prevent a file from being saved if true is returned. If a macro returns "None" in JavaScript, or "Null" in Python, it evaluates to false and does not interrupt the Komodo event in progress.

Note: Be sure to enable macro triggers via the Projects and Workspace Preferences in Komodo's 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. Right-click the macro in the Toolbox and select Properties.
  2. Select the Triggers tab on the Macro Properties dialog box to access the following options:
    • Macro should trigger on a Komodo event: Select the check box to access the trigger events.
    • Select the event you want to trigger the macro:
      • At the tail end of the Komodo startup process
      • After a file is opened
      • Before a file is saved
      • After a file is saved
      • Before a file is closed
      • After a file is closed
      • Before Komodo shuts down (as part of File/Exit)
    • Rank: 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.
  3. Click Apply.

 

Running Macros in the Background

If a macro is not associated with a Komodo event, it can run either in the foreground or in the background. Depending on the use case, some macros should run in the background while others are more suitable for running in the foreground. Macros that invoke and do not affect the current file are best run in the background to minimize interference with Komodo responsiveness. 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. Macros that run in the background are run in threads in Python, or in a timeout in JavaScript.

To run a macro in the background:

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

 

Storing Macros in Projects or the Toolbox

Macros are added to the Toolbox via the Tools|Macros|Save to Toolbox option. However, you can manually add macros to the Toolbox, or to a project in the Project Manager.

To add a new macro to a project or the Toolbox:

  1. Right-click the name of the project, or the name of a folder within a project or the Toolbox, and select Add|New Macro from the context menu. Alternatively, select Project|Add|New Macro or Toolbox|Add|New Macro from the drop-down menu, or select New Macro from the Add button in the Project or Toolbox tab.
  2. Follow the instructions in the Programming Macros section.
  3. Click OK.

Alternatively, existing macros can be dragged and dropped between the Toolbox and the Project Manager.

 

Macro Options

To access macro options, right-click the macro name in a project or the Toolbox and select the desired option.

  • Execute Macro: Use this option to run the selected macro.
  • Cut/Copy/Paste: These options are used to remove the macro from a project or the Toolbox, or to move macros between the project and the Toolbox (and vice versa).
  • Export as Project File: When this option is invoked, a new project file is created that contains the macro from which the option is invoked. You are prompted to provide the name of the new project file and the directory where it will be stored. To open the new project file, select File|Open|Project.
  • Export Package: Macros can be archived and distributed among multiple Komodo users via "packages". Packages are compressed archive files that contain the macro from which the Export Package option was invoked. Packages are stored in files with a ".kpz" extension, and can be opened by any archiving utility that supports libz (for example WinZip). The Export Package option differs from the Export as Project File option in that copies of filesystem-based components (such as files and dialog projects) are included in the archive. Conversely, Export as Project File creates a project with a reference to the component's original location and does not create copies of the components. When Export Package is invoked, you are prompted for a name and file location for the package. Exported packages can only be imported into "container" objects in Komodo, such as projects, the Toolbox, and folders within projects and the Toolbox. See Toolbox - Exporting and Importing Toolbox Contents, Projects - Importing and Exporting Projects via Packages, Folders - Import Contents from Package for more information.
  • Rename: To change the name of a macro, select this option and enter a new name.
  • Delete: To remove a macro from a project or the Toolbox, select this option. The macro is permanently deleted.

 

Assigning Custom Icons to Macros

The default macro icon can be replaced with custom icons. Komodo includes more than 600 icons; alternatively, select a custom image stored on a local or network drive (use 16x16-pixel images for best results).

To assign a custom icon to a macro:

  1. In the project or in the Toolbox, right-click the desired macro and select Properties. Alternatively, click the macro in the Projects tab or Toolbox tab, then select Projects|macro_name|Properties or Toolboxmacro_name|Properties.
  2. In the Properties dialog box, click Change Icon.
  3. In the Pick an Icon dialog box, select a new icon and click OK. Alternatively, click Choose Other, and browse to the desired image file.
  4. In the properties dialog box for the macro, click OK. The custom icon is displayed next to the macro.

To revert to the default icon for a selected macro:

  1. On the Projects tab or Toolbox tab, right-click the desired macro and select Properties.
  2. Click Reset, then click OK. The default icon is displayed next to the macro.

 

Assigning Key Bindings to Macros

Custom key bindings can be assigned to macros stored in the Toolbox or in a Project. Use the Key Binding tab in the macro's Properties to specify the keystrokes that invoke the macro. See Key Bindings for Custom Components for more information.