Macro API

Introduction to the Komodo Macro API

Komodo macros can be written in either JavaScript or Python. As much as possible, the API calls are the same regardless of the language. Exceptions are noted where appropriate.

In both Python and JavaScript, there is a top-level komodo object that contains both variables and utility functions. These are:

  • The editor object for manipulation of code buffers.
  • The document object for manipulation of documents in memory.
  • The file type, corresponding to files on disk.
  • The doCommand(...) function to execute Komodo "commands".
  • The findPart(...) function to find other components (snippets, run commands, other macros, etc).
  • The interpolate(...) function for evaluation of interpolation codes.
  • The getWordUnderCursor() function to retrieve the word under the editing cursor.

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. We encourage users to experiment with macros when not 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 editor object should be written with care, to avoid data loss
  • .

Feedback

Komodo 3.0 is the first release of Komodo with a published macro API. We expect the API to change in response to customer feedback. As such, the API described below may change in future releases (we will of course try to minimize backwards-incompatible changes). Questions and feedback on the API are encouraged via the komodo-discuss mailing list.

The editor Object

The komodo.editor 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.

editor 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 Unix).
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.

komodo.editor Methods

void emptyUndoBuffer()
Empty the undo buffer.
void undo()
Undo the last action.
void cut()
Cut current selection (komodo.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 XXX.
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 komodo.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 capitalisation (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.

editor Object 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:

    komodo.editor.beginUndoAction()
    try {
        ...  // do your sequence here
    } finally {
        komodo.editor.endUndoAction()
    }

For Python:

    komodo.editor.beginUndoAction()
    try:
        ...  # do your sequence here
    finally:
        komodo.editor.endUndoAction()

The document Object

The komodo.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 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.

The file Object

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

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").

The komodo.doCommand Function

Signature:

    komodo.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:

    komodo.view.setFocus()

The komodo.findPart Function

Signature:

    komodo.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

The komodo.interpolate Function

Signature:

    komodo.interpolate(s, bracketed=False) -> 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.

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.

The komodo.getWordUnderCursor Function

Signature:

    komodo.getWordUnderCursor() -> string

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