Custom Names in Formulas

Formulas may include custom, user-defined names. Custom names are identifiers to represent information in the spreadsheet. A custom name can refer to a cell, a range of cells, a computed value, or a formula. (Methods that deal with custom names provide the same functionality as the Name in Excel.) A custom name can contain up to 255 characters and can include letters, numbers, or underscores. The first character must be a letter or an underscore.

The name's value can be assigned or retrieved as either a string object or as an expression object. Refer to the Assembly Reference for more details on the methods that add or get custom names.

From the example in C#:

SetCustomName("Total", 0, 0, new GrapeCity.CalcEngine.Expressions.CalcCellExpression(3, 2));

a name called Total is created that represents the cell at absolute location 3,2. Assuming A1 notation (ReferenceStyle = A1), then this would be equivalent to:

SetCustomName("Total", 0,0, "$D$3");

In Excel, this would be equivalent to:

Name: Total Refers To: =$D$3

Once the name is defined, the name can be used in formulas. When the formula is evaluated, the name's value is referenced and evaluated. Given the above definition, the following two formula assignments would produce the same result:

gcSpreadSheet1.ActiveSheet.SetFormula(0, 0, "Total"); gcSpreadSheet1.ActiveSheet.SetFormula(0, 0, "$D$3");

Note that the string versions of the SetCustomName and GetCustomName methods take the base row or base column arguments. These arguments are used to parse or unparse relative addresses in A1 notation. These arguments are ignored when using absolute addresses or when using R1C1 notation. A1 notation requires a base location from which the relative offset is computed.

For example:

SetCustomName("Beta", 0, 0, "D3"); // same as "R[2]C[3]" SetCustomName("Gamma", 4, 4, "D3"); // same as "R[-2]C[-1]"

In other words, cell D3 is +3/+2 from cell A1 but -1/-2 from cell E5. In Excel, the Insert > Name > Define dialog uses the active cell as the base location.