XLL+ Class Library (6.3)

Argument Details - General Tab

The controls on the General tab of the Argument Details window are divided into groups:

Definition

This group defines the basic behavior of the argument.

Name

This is the name of the argument, as it will appear in the generated C++ code.

The name must be unique within a function, and you will receive an error message if you try to specify a name that is already in use.

If the name is not a valid C++ variable name, you will recieve an error message.

The name will also be used in the Excel Formula Wizard, unless you specify a Resource ID, in which case a localized name will be used.

Type

Use this control to define the argument's data type. All the built-in data types are listed here, and so are any Extended scalar types that have been registered.

The built-in types are as follows:

Type C++ type Description
Boolean BOOL Boolean (true or false) value
Double double Floating-point number
Int long Signed integer (32-bit)
Short Int short int Signed integer (16-bit)
String const CXlStringArg& Text string
Unsigned Short Int unsigned short int Unsigned integer (16-bit)
Reference const CXlOper* A reference to an Excel cell range
Value const CXlOper* The value(s) contained in an Excel cell range
XlArray const CXlArray& An array of numbers

Rank

Value types can be assigned a rank, which defines the number of dimensions they are expected to have.

Rank Name Description
0 Scalar A single value
1 Vector A set of values contained in a single row or column
2 Matrix A set of values contained in one or more rows and one or more columns

Some types cannot be assigned a rank, and for these types the Rank control is disabled.

Vector or matrix arguments will be stored in a container, such as std::vector<T>. You can use the Vector Container or Matrix Container controls to specify a particular container class. Otherwise the default class (as defined by the DefaultVectorContainer or DefaultMatrixContainer settings) will be used.

Optional

Check this box to specify that the argument is optional. This means that the user can omit it, in which case a Default value will be used.

Appearance

This group defines the appearance of the argument.

Description

This text will appear in the Excel Formula Wizard.

The description may be localized, in which case it will appear in the language of the user.

For groups, the description builder drop-down is also displayed. This allows you the option to auto-generate the group's description, based on the names and/or descriptions of the group's member arguments.

The Excel Formula Wizard applies some constraints to argument descriptions when it displays them. You may wish to use the Preview Formula Wizard tool to see how the argument's decription will actually appear.

Resource ID

You can choose to localize the name of the argument, as it will appear in the Excel Formula Wizard. If you specify a number for the resource ID, then the ID will be used to get a string from the add-in's resource file. If an entry can be found in the resource file that matches the language of the user, then that entry will be used instead of the argument's name.

See argument names in the User Guide for more details.

Default value

This group controls the behavior of the argument when the input is missing or empty. It is disabled unless the Optional box has been checked.

Default

Use this field to specify the default value that will be used if the argument is found to be missing.

This value will be inserted directly into your code, so it should be a valid C++ expression, and of a type that can be assigned to the destination value.

For example, if you have an optional integer value, you might use any of the following as default values:

0
123
-1000
global_value

global_value will only be legal if you have defined a C++ variable of type long with this name, and the variable is available in the scope of the add-in function.

Use default if Blank

A cell often contains blank text rather than being empty. For example, the following style of formula is often used:

=IF(A1<0,"",A1)

where the value will be blank is A1 is negative.

You can specify that blank values will be treated as missing, in which case the default value will be used.

Use default if Zero

You can specify that zero values will be treated as missing, in which case the default value will be used.

Use default if not Numeric

You can specify that values that are not numbers (or dates) will be treated as missing, in which case the default value will be used.