The controls on the General tab of the Argument Details window are divided into groups:
This group defines the basic behavior of the argument.
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.
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 |
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.
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.
This group defines the appearance of the argument.
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.
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.
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.
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.
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.
You can specify that zero values will be treated as missing, in which case the default value will be used.
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.