Ewa.Workbook.getRangeA1Async(addressA1, callback, userContext)

Last modified: June 14, 2011

Applies to: apps for SharePoint | SharePoint Server 2010

In this article
Return Value

Gets the specified range in the open workbook asynchronously using the Excel "A1" range notation as an input parameter.

Ewa.Workbook.getRangeA1Async(addressA1, callback, userContext);


The range to get in A1 notation.


The function that is called when the request is completed.


An object provided as a way for callers to pass state through the asynchronous call.

The Ewa.Workbook.getRangeA1Async method gets a range asynchronously by using A1 notation as one of the input parameters. For example A4:B9, which specifies a range located on the specified worksheet that begins at cell A4 and extends to cell B9.

Note Note

Discontiguous ranges are not supported. Specifying discontinguous ranges causes a range parse error.

Specifying addressA1 without a sheet name (for example, "B1:C2") will fail.

Note Note

Ewa.Workbook.getRangeA1Async cannot generate a range on a chart sheet.

You can also use other Excel addressing besides sheetName!R1C1 notation when specifying addressA1. For example, the following are all acceptable ways to specify addressA1:

  • Sheet3!NamedRange1, where NamedRange1 is a named range

  • Sheet1!MyDefinedName, where MyDefinedName a defined name

  • Table1[Column4], where Table1 is a table

The following code example shows how to add a button and a text input box to the page and then adds code to the button onClick event that takes the range address entered into the text box (in A1 notation) and activates the specified range.

<script type="text/javascript">
var ewa = null;
// Add event handler for onload event.
if (window.attachEvent) 
    window.attachEvent("onload", ewaOmPageLoad);    
    window.addEventListener("DOMContentLoaded", ewaOmPageLoad, false); 

// Add event handler for applicationReady event.
function ewaOmPageLoad() 

function getEwa()
    // Get a reference to the Excel Services Web Part.
    ewa = Ewa.EwaControl.getInstances().getItem(0);                                       

function getRangeA1Button()
    // Get the A1 address entered.
    var a1Address = document.forms.aspnetForm.GetRangeAddress.value;
    // Call getRangeA1Async with the A1 address entered.
    ewa.getActiveWorkbook().getRangeA1Async(a1Address, getRangeA1Callback, null);    

function getRangeA1Callback(asyncResult)
    // getRangeA1Async returns a range object through the AsyncResult object.
    var range = asyncResult.getReturnValue();
    // Activate the range that the user entered.
    // Pass in range as user context so it can be used in callback.

function activateAsyncCallback(asyncResult)
    // activateAsync does not return a range through AsyncResult so 
    // get the range from the user context passed in with activateAsync call.
    var range = asyncResult.getUserContext();
    // Display which address for which range was activated.
    window.status = "Range located at A1 address: " + range.getAddressA1() + " was activated.";

<input type="button" id="GetRange" VALUE="Get Range" onclick="getRangeA1Button()">
<input type="text" id="GetRangeAddress" value="Enter A1 Address">