GrapeCity.Documents.Excel.CustomFunction

CustomFunction Class

Represents the base type for a custom function.

Derive from this abstract class to define spreadsheet functions that behave like built-in formula functions. A custom function supplies its function name, return type, and optional parameter metadata through one of the CustomFunction constructors, and must implement Evaluate(object[], ICalcContext) to calculate the result.

After a derived function is created, register it by using AddCustomFunction(CustomFunction, bool) before using it in formulas.

Custom functions can be configured to participate in calculation caching and error propagation. Use IsVolatile to control whether repeated calls with the same arguments can reuse cached results, and use AcceptErrors to control whether error values such as #N/A or #VALUE! are passed to the function for handling. By default, custom functions are not volatile and do not accept error arguments.

This type is the synchronous custom-function base class. For asynchronous evaluation scenarios, use AsyncCustomFunction.

Inheritance

object

CustomFunction

AsyncCustomFunction

Namespace: GrapeCity.Documents.Excel

Assembly: DS.Documents.Excel.dll

Syntax

public abstract class CustomFunction

Public MustInherit Class CustomFunction

Examples

CustomFunction function = new Add2Function();
Workbook.AddCustomFunction(function, true);
worksheet.Range["A1"].Formula = "=ADD2(10,20)";
object sum = worksheet.Range["A1"].Value;

class Add2Function : CustomFunction
{
    public Add2Function()
        : base("ADD2", FunctionValueType.Number, new Parameter[] {
            new Parameter(FunctionValueType.Number),
            new Parameter(FunctionValueType.Number)
        })
    {
    }

    public override object Evaluate(object[] arguments, ICalcContext context)
    {
        double left = Convert.ToDouble(arguments[0]);
        double right = Convert.ToDouble(arguments[1]);
        return left + right;
    }
}

Constructors

Name Description

Name	Description
CustomFunction(string, FunctionValueType)	Initializes an instance of a custom function.
CustomFunction(string, FunctionValueType, Parameter[])	Initializes an instance of a custom function. This constructor passes `null` as the description to CustomFunction(string, string, FunctionValueType, Parameter[]).
CustomFunction(string, string, FunctionValueType, Parameter[])	Initializes an instance of a custom function.

CustomFunction(string, FunctionValueType)

Initializes an instance of a custom function.

CustomFunction(string, FunctionValueType, Parameter[])

Initializes an instance of a custom function.

This constructor passes null as the description to CustomFunction(string, string, FunctionValueType, Parameter[]).

CustomFunction(string, string, FunctionValueType, Parameter[])

Initializes an instance of a custom function.

Properties

Name Description

Name	Description
AcceptErrors	Gets or sets whether the function accepts error values as arguments. If this property returns `true`, error values such as `#N/A` and `#VALUE!` can be passed to Evaluate(object[], ICalcContext) for custom handling. If it returns `false`, the calculation engine returns the error immediately instead of passing the error argument to the custom function.
IsVolatile	Gets or sets whether this custom function is volatile. If this property is `true`, formulas that call this custom function are recalculated whenever calculation is triggered, even when the arguments have not changed. If it is `false`, calculation can reuse cached results for repeated calls with the same arguments.

AcceptErrors

Gets or sets whether the function accepts error values as arguments.

If this property returns true, error values such as #N/A and #VALUE! can be passed to Evaluate(object[], ICalcContext) for custom handling. If it returns false, the calculation engine returns the error immediately instead of passing the error argument to the custom function.

IsVolatile

Gets or sets whether this custom function is volatile.

If this property is true, formulas that call this custom function are recalculated whenever calculation is triggered, even when the arguments have not changed. If it is false, calculation can reuse cached results for repeated calls with the same arguments.

Methods

Name Description

Name	Description
Evaluate(object[], ICalcContext)	Calculates the result of the custom function. This method is called by the calculation engine when the custom function is evaluated. The `arguments` array contains the argument values passed to the function, and `context` provides information about the worksheet cell being calculated. If AcceptErrors returns `true`, error values can be passed in `arguments` for custom handling. Otherwise, calculation can stop before this method is called when an argument evaluates to an error.

Evaluate(object[], ICalcContext)

Calculates the result of the custom function.

This method is called by the calculation engine when the custom function is evaluated. The arguments array contains the argument values passed to the function, and context provides information about the worksheet cell being calculated.

If AcceptErrors returns true, error values can be passed in arguments for custom handling. Otherwise, calculation can stop before this method is called when an argument evaluates to an error.