



	advanced \| search help

Reference

Komodo

Macros

Macro API

Python Macros

Running a Komodo command (XPCOM)

MyASPN >> Reference >> Komodo >> Macros >> Macro API >> Python Macros

Komodo documentation

Macro API

The Komodo Macro API

Macros in Komodo can be written in JavaScript or Python. The Macro API for JavaScript is a subset of the Komodo JavaScript API. Python macros have access to the XPCOM interface. The komodo. namespace for macro functions is deprecated, but currently still available for supporting older macros and providing functions in Python for which there are not direct equivalents in XPCOM.

The interfaces for the two macro languages are described separately:

JavaScript Macros
Python Macros

Warning

The macro system is a powerful mechanism by which Komodo users can execute arbitrary code inside the Komodo process. It is easy for novices to write macros that can significantly disrupt Komodo's behavior, leading to instability and data loss. Avoid experimenting with macros while working with important files.

Of particular note:

Macros that never terminate (for example, due to infinite loops) can hang Komodo.
Macros that modify the buffer should never be run in the background, as multiple threads accessing the editor object could cause crashes.
Macros that modify the scimoz object should be written with care, to avoid data loss.

Feedback

The Komodo JavaScript API is under active development. If you have questions or feedback about the API, please post to the Komodo Macros and Extensions forum.

The API described below may change in future releases (we will of course try to minimize backwards-incompatible changes).

JavaScript Macros

For macros, the most important parts of the Komodo JavaScript API are:

The ko.views.manager.currentView object which contains:
- The scimoz object for manipulation of code buffers.
- The document object for manipulation of documents in memory.
- The document.file object, corresponding to files on disk.
The ko.commands.doCommand(...) function to execute Komodo commands.
The ko.open.URI(...) function to open a local or remote file using a URI.
The ko.projects.findPart(...) function to find other components (snippets, run commands, other macros, etc).
The ko.interpolate object which contains:
- The interpolateStrings(...) function for evaluation of interpolation codes
- The getWordUnderCursor() function to retrieve the word under the editing cursor.
The ko.run.runEncodedCommand(...) function to open a local or remote file using a URI.

ko.views.manager.currentView.scimoz

The ko.views.manager.currentView.scimoz object corresponds to the main text editing widget that contains and manipulates files in the Editor Pane. It is a thin wrapper around the Scintilla widget, an open-source component written by Neil Hodgson (www.scintilla.org).

The Scintilla API is large, complex and subject to change. This document only contains the calls most relevant to Komodo, and notes some common patterns of use relevant to changing the editor widget.

scimoz Attributes

int currentPos: The location (in character units) of the caret.
int anchor: The location (in character units) of the selection anchor.
string text: The contents of the buffer.
string selText: The contents of the selection (readonly).
long scrollWidth: The width of the scroll area (in pixels).
long xOffset: The horizontal scroll position (in pixels) of the start of the text view.
boolean viewEOL: Whether to show end-of-line markers or not.
long viewWS: Whether to show whitespace characters (0: no, 1: yes).
long eOLMode: The characters that are inserted when the user presses 'Enter': either 'CRLF' (0 - the default on Windows), 'CR' (1) or 'LF' (2 - the default on Linux).
long tabWidth: The size of a tab as a multiple of the size of a space character.
long indent: The size of indentation in terms of the width of a space.
boolean useTabs: Whether indentation should be created out of a mixture of tabs and spaces (1) or be based purely on spaces (0).
boolean indentationGuides: Whether to show indentation guides or not.
readonly long firstVisibleLine: The line number of the first visible line in the text view.
long lineCount: The number of lines in the text view.
long textLength: The length of the current buffer in characters.
long targetStart: The start of the target region; see replaceTarget.
long targetEnd: The end of the target region; see replaceTarget.
long linesOnScreen: The number of complete lines visible on the screen.

scimoz Methods

void emptyUndoBuffer(): Empty the undo buffer.
void undo(): Undo the last action.
void cut(): Cut current selection (ko.commands.doCommand('cmdCut') is the preferred method).
void copy(): Copy current current selection.
void paste(): Replace current selection with the clipboard contents.
void clear(): Clear current selection.
long replaceTarget(in long length, in string text): Replace the target text with the argument text. Text is counted so it can contain NULs. Returns the length of the replacement text..
string getTextRange(in long min, in long max): Return a range of characters from the current buffer.
void insertText(in long pos, in string text): Insert text at a specified position.
void colourise(in long start, in long end): Force the re-coloring of the specified range.
wchar getWCharAt(in long pos): Get the (Unicode) character at the specified position.
void addText(in long length, in string text): Add text to the end of the current buffer.
void selectAll(): Select the entire buffer.
void gotoLine(in long line): Jump to the specified line.
void gotoPos(in long pos): Jump to the specified position in the buffer.
void deleteBack(): Delete the character to the left of the cursor.
void newLine(): Add a newline (note: this is a less 'smart' newline than can be obtained using ko.commands.doCommand('cmd_newlineExtra').
void redo(): Redo the last action.
boolean canRedo(): There is an action that can be redone.
void beginUndoAction(): Begin an undo block (see note).
void endUndoAction(): End an undo block (see note).
long getColumn(in long pos): Get the column (0-based) of the specified position.
long getLineEndPosition(in long line): Get the position corresponding to the last character on the specified line (not including EOL characters).
void setSel(in long start, in long end): Make selection start at start and end at end.
long lineFromPosition(in long pos): Get the line number (0-indexed) from character position pos.
long positionFromLine(in long line): Get character position which begins the specified line.
void lineScroll(in long columns, in long lines): This will attempt to scroll the display by the number of columns and lines that you specify. Positive line values increase the line number at the top of the screen (i.e. they move the text upwards as far as the user is concerned). Negative line values do the reverse.
void scrollCaret(): If the current position (this is the caret if there is no selection) is not visible, the view is scrolled to make it visible.
long lineLength(in long line): Return the length of the current line.
void replaceSel(string): Replace current selection with the text in the string.
void lineDown(): Move cursor down one line.
void lineDownExtend(): Extend selection down one line.
void lineUp(): Move cursor up one line.
void lineUpExtend(): Extend selection up one line.
void charLeft(): Move cursor one character to the left.
void charLeftExtend(): Extend selection one character to the left.
void charRight(): Move cursor one character to the right.
void charRightExtend(): Extend selection one character to the right.
void wordLeft(): Move cursor one word to the left.
void wordLeftExtend(): Extend selection one word to the left.
void wordRight(): Move cursor one word to the right.
void wordRightExtend(): Extend selection one word to the right.
void home(): Move cursor to the Home position.
void homeExtend(): Extend selection to the Home position.
void lineEnd(): Move cursor to the end of the line.
void lineEndExtend(): Extend selection to the end of the line.
void documentStart(): Move cursor to the start of the document.
void documentStartExtend(): Extend selection to the start of the document.
void documentEnd(): Move cursor to the end of the document.
void documentEndExtend(): Extend selection to the end of the document.
void pageUp(): Page up.
void pageUpExtend(): Extend selection one page up.
void pageDown(): Page down.
void pageDownExtend(): Extend selection one page down.
void editToggleOvertype(): Toggle overtype mode.
void vCHome(): Move cursor to the first non-whitespace character on a line or, if none, the beginning of a line.
void vCHomeExtend(): Extend the selection to the first non-whitespace character on a line or, if none, the beginning of a line.
void zoomIn(): Increase font size.
void zoomOut(): Decrease font size.
void delWordLeft(): Delete word to the left of the cursor.
void delWordRight(): Delete word to the right of the cursor.
void lineCopy(): Copy line at the cursor.
void lineCut(): Cut line at the cursor.
void lineDelete(): Delete line at the cursor.
void lineTranspose(): Transpose current line and previous line.
void lineDuplicate(): Duplicate current line.
void lowerCase(): Convert selection to lower case.
void upperCase(): Convert selection to upper case.
void lineScrollDown(): Scroll display down one line.
void lineScrollUp(): Scroll display up one line.
void deleteBackNotLine(): Delete last character except if at beginning of line.
void homeDisplay(): Move cursor to Home position for the current display line (as opposed to the buffer line when word wrap is enabled).
void homeDisplayExtend(): Extend selection to the Home position for the current display line (as opposed to the buffer line when word wrap is enabled).
void lineEndDisplay(): Move cursor to end of the current display line (as opposed to the buffer line when word wrap is enabled).
void lineEndDisplayExtend(): Extend selection to the end of the current display line (as opposed to the buffer line when word wrap is enabled).
void wordPartLeft(): Move cursor a word segment to the left. Word segments are marked by capitalization (aCamelCaseIdentifier) or underscores (an_under_bar_ident).
void wordPartLeftExtend(): Extend selection a word segment (as described in void wordPartLeft()) to the left.
void wordPartRight(): Move cursor a word segment (as described in void wordPartLeft()) to the right.
void wordPartRightExtend(): Extend selection a word segment (as described in void wordPartLeft()) to the right.
void delLineLeft(): Delete to beginning of line.
void delLineRight(): Delete to end of line.
void paraDown(): Move cursor one paragraph down.
void paraDownExtend(): Extend selection one paragraph down.
void paraUp(): Move cursor one paragraph up.
void paraUpExtend(): Extend selection one paragraph up.

scimoz Notes

Invalid Parameters: The Scintilla API assumes that users of the API do their own error-checking. Passing arguments that are out of bounds or otherwise erroneous can result in Komodo crashing.

The Undo Stack: Scintilla manages the "undo" stack. To treat a sequence of operations as a single operation for the sake of Undo/Redo, wrap these operations in a beginUndoAction / endUndoAction pair. The endUndoAction must be called even in the case of an exception in the code. Otherwise, the undo stack will be corrupted and might lose data.

For example, for JavaScript:

ko.views.manager.currentView.scimoz.beginUndoAction()
try {
    ...  // do your sequence here
} finally {
    ko.views.manager.currentView.scimoz.endUndoAction()
}

ko.views.manager.currentView.document

The ko.views.manager.currentView.document object refers to the current document. A document contains the contents of the file being edited. These contents will be different than those of the file on disk if the file is unsaved or "dirty".

document Attributes

string baseName: The basename of the document (e.g. "myfile.txt").
string displayPath: The display path of the document (e.g. "C:\Code\myfile.txt").
file: The document.file object corresponding to the document (null if the document is unsaved).
string buffer: The contents of the document (Unicode string).
boolean isDirty: Whether there are unsaved changes to the document.
boolean isUntitled: Whether the document has never been saved.
string language: The language that this document is viewed as ("Python", "Perl", etc.

ko.views.manager.currentView.document.file

The file object is an attribute of document objects, and corresponds to a wrapper object around the file object.

`document.file` attributes

string URI: The URI to the file (e.g. "file:///C:/Code/myfile.txt").
string displayPath: The display path of the file (e.g. "C:\Code\myfile.txt"), or the URI if the URI is not of the file:// scheme.
string baseName: The base name of the file (e.g. "myfile.txt").
string dirName: The directory of the file (e.g. "C:\Code").

ko.commands.doCommand()

Signature:

ko.commands.doCommand(commandId)

Execute the internal Komodo command specified by commandId.

Command IDs and their corresponding functions are available in the Command ID reference.

Most editor-related commands require that the Editor Pane be in focus. To ensure focus before invoking doCommand, set the focus explicitly as follows:

ko.views.currentView.setFocus()

ko.open.URI()

Signature:

ko.open.URI(uri_string#line_number)

Open the file specified by the URI string and move the cursor to the line number specified after '#' (if any).

All file access protocols used by Komodo are valid. For example:

ko.open.URI("file:///home/user/example.txt#33");
ko.open.URI("ftp://example.org/pub/example.xml");
ko.open.URI("scp:///host.example.org/home/user/file.txt#11");

ko.projects.findPart()

Signature:

ko.projects.findPart(type, name, where) -> part

Find a "part" (the internal name for a component such as a snippet, another macro, a run command, etc) in the Toolbox or a project.

type: The type of component to search for. It can be one of:
- "snippet"
- "command"
- "macro"
- "file"
- "folder"
- "dialog"
- "URL"
- "template"
- "DirectoryShortcut"
name: The component's name.
where: A string corresponding to the component container that should be searched. Supported values are:

"toolbox"

search in the Toolbox

"shared toolbox"

search in the Shared Toolbox (if enabled)

"toolboxes"

search in both the Toolbox and the Shared Toolbox

"container"

search the project or Toolbox that contains the current macro

"*"

search all of the above

ko.interpolate.interpolateString()

Signature:

ko.interpolate.interpolateString(s[, bracketed]) -> string

Evaluate interpolation shortcuts in the given string.

s: The string to interpolate.
bracketed: An optional boolean value indicating whether plain (e.g. %F) or bracketed (e.g. [[%F]]) syntax is being used. If not specified, plain interpolation is used (i.e. bracketed=false)</.

ko.interpolate.getWordUnderCursor()

Signature:

ko.interpolate.getWordUnderCursor() -> string

This function returns the word under the cursor in the current buffer.

ko.run.runEncodedCommand()

Signature:

ko.run.runEncodedCommand(window, command[, callback]) -> string

Runs a shell command and optional callback function.

window: Required (literal) argument indicating Komodo's top-level window object. This allows the method to be called from dialog boxes or other sub-windows.
command: The shell command to run. Can include arguments in Python dict format.
callback: An optional callback function.

For example:

function did_it() {
  alert("Done.");
}
ko.run.runEncodedCommand(window, 'sleep 5', did_it);

Command options and environment variables can be added in curly braces "{...}" after the command in Python dict format. For example:

ko.run.runEncodedCommand(window,
  'svn up "%F" {"cwd": "%D", "env": "SVN_SSH=plink.exe"}')

The following JavaScript macro uses Komodo's cmd_refreshStatus function as the callback in ko.run.runEncodedCommand(). This updates the SCC status information after running 'svn up' on the file in the current editor tab:

if (komodo.view) {
  komodo.view.setFocus();
  
  ko.run.runEncodedCommand(window,
      'svn up "%F"',
      (function (view) {
          return function () {
              view.setFocus();
              komodo.doCommand('cmd_refreshStatus');
          }
      })(komodo.view)
  );
};

Python Macros

Macros written in Python can use the XPCOM interface. Though it is deprecated, komodo. namespace is still available for those functions (interpolate() and getWordUnderCursor()) which cannot be done easily with XPCOM.

To use the XPCOM components described below, add the following to your macro:

from xpcom import components

Creating a view object

There is no global object in Python macros to get the current "view" (i.e. the main active Komodo tab) because this can change during macro execution. Instead, a view object can be created in the macro at the point where it will be used. For example:

viewSvc = components.classes["@activestate.com/koViewService;1"]\
    .getService(components.interfaces.koIViewService)
view = viewSvc.currentView

The view object will have the same properties as ko.views.manager.currentView, exposing:

The scimoz object for manipulation of code buffers.
The document object for manipulation of documents in memory.
The document.file object, corresponding to files on disk.

Opening a URI

To open a URI:

obsvc = components.classes["@mozilla.org/observer-service;1"].\
    getService(components.interfaces.nsIObserverService);
obsvc.notifyObservers(None, 'open-url', uri);

Interpolate a string

There is currently no equivalent in XPCOM for evaluating interpolation codes. This can be done using the old komodo namespace as follows:

import komodo
komodo.interpolate()

Some interpolation shortcuts cannot be used within Python macros. These include %P and %ask, and the :orask modifier on other shortcuts. A ValueError is raised if they are used.

Get word under cursor

There is currently no equivalent in XPCOM to retrieve the word under the editing cursor. This can be done using the old komodo namespace as follows:

import komodo
komodo.getWordUnderCursor()

Running a Komodo command

To execute Komodo command:

def doCommand(commandId):
    _observerSvc = components.classes["@mozilla.org/observer-service;1"]\
        .getService(components.interfaces.nsIObserverService)
    _observerSvc.notifyObservers(None, 'command-docommand', commandId);

Find a part

To find other components (snippets, run commands, other macros, etc):

var _partSvc = components.classes["@activestate.com/koPartService;1"]
            .getService(components.interfaces.koIPartService);
_partSvc.findPartForRunningMacro(type, name, where);

Warning

Feedback

scimoz Attributes

scimoz Methods

scimoz Notes

document Attributes

document.file attributes

`document.file` attributes