Dashboard > Developers > Macro API Reference
Macro API Reference
Added by Alan Tam , last edited by Chi-Ming To on Oct 16, 2008  (view change)

The following is a documentation of individual declarations available in Macro. For a general guideline to Macro, please refer to the Macro Guide.

Macro API versus Grid API

EditGrid Macro Framework is composed of two parts.

  • Macro API (to be described in this page), allows you to define a set of facts, such as attaching a JavaScript function to a spreadsheet change or a user action.
  • Grid API, provides an Object-Oriented API to allow a macro to manipulate the grid inside JavaScript functions defined above.

You can, in fact, write a macro without using Macro API at all, by writing Grid API code in only macro.onLoad and macro.onUnload. You will find this quite troublesome as you should remember to detach every event handler you attached. This is the primary reason we allow you to define event handlers using Macro API. The facts you specify using Macro API are defined at the outermost scope. If you have to define event handlers during macro execution, you have to use the Grid API equivalent and manage the life cycle yourself.

Calling Grid API

Use the global variable grid to access the editgrid.Grid object of the RTU Grid. Then you can start applying Grid API on this object. For example, you can use

to obtain cells of the current sheet and a named sheet respectively. You can use getRange to replace getCell to work on cells in bulk.

Defining event listeners.

// Triggered when the macro is loaded
macro.onLoad = function () { ... };

// Triggered when the macro is unloaded
macro.onUnload = function () { ... };

// Triggered when the cursor enters edit mode
cursor.onStartEdit = function (inputText, cell) { ... };

// Triggered when the cursor exits edit mode
cursor.onFinishEdit = function (inputText, cell) { ... };

// Triggered when the cursor is removed
cursor.onMove = function (fromRange, toRange) { ... };

// Triggered when the value of some cells in a range is changed
data.onValueChange['Sheet1!A2:C4'] = function (range) { ... };
data.onValueChange['Sheet1'] = function (range) { ... };
// Hint: use range.eachCell(function () { ... }); to loop each cell

// Triggered when the style of some cells in a range is changed
data.onStyleChange['Sheet1!A2:C4'] = function (range) { ... };

// Triggered when the value/stlye of some cells in a range is changed
data.onRangeChange['Sheet1:A2:C4'] = function (type, range) { ... };

// Triggered when a new sheet is added/a sheet is deleted/moved/renamed
data.onSheetsChange = function (sheet) { ... };

Defining an action.

// Define an action, which could be called by defining a button
//     =button("Button Text", "editgrid:action(MACRONAME:ActionName)")
action['ActionName'] = function () { ... };

// Define a shortcut key
shortcut['Alt C'] = function () { ... };

// Define a toolbar button
toolbar['Toolbar Text'] = function () { ... };
toolbar.image = "url...";
toolbar.tooltip = "tooltip...";

Defining a toolbox.

// Define a toolbox, which shows the HTML when open() is called
toolbox['ToolboxName'] = {
    html: '<button id="button">click me</button>',
    // To be called when the "click" event of an element "button" is called
    onButtonClick: function () { ... }

function openIt() {
function closeIt() {

// If you need to modify the toolbox contents afterward, you need to modify the DOM directly.
// You can access the "document" element of the toolbox using "toolbox['ToolboxName'].doc".
// For example, you can access the button by
//    toolbox['ToolboxName'].doc.getElementByid('button')
// or simply
//    toolbox['ToolboxName'].button
Powered by Atlassian Confluence 2.7, the Enterprise Wiki. Bug/feature request - Atlassian news - Contact administrators