Function Wizard - Arguments Tab

The Arguments Tab contains a toolbar and a grid.

The toolbar contains commands for use with arguments, and the grid contains a summary of each of the add-in function's arguments.

You can add a new argument by typing into any of the columns of the empty row which appears at the bottom of the grid.

You can use the grid's controls to manipulate the list of arguments:

Selecting arguments
Copy and paste arguments
Drag and drop arguments
Reorder arguments
Arrange arguments into groups

Columns

The columns of the grid are listed below, with a link to the property that each column contains.

Name

This is the name of the argument as it will appear in C++ code, and (usually) also as it will appear in the Excel Formula Wizard.

It should be unique within a function; when you copy or drag-copy arguments the wizard will ensure that the names of new arguments are unique.

If you want the argument name to be localized in Excel (i.e. to appear in the language of the user) then use the Resource ID column.

Type

The type of value that will be passed from Excel to the add-in function.

Use the drop-down to control the data type, and whether it is a single value, a vector or a matrix.

All the built-in data types are listed in the drop-down, 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

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

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.

To show or hide the Resource ID column, use the View Resource ID Column command.

Optional

Check this box to make the argument optional. If the argument is empty or missing then the value in the Default column will be used.

To show or hide the Optional column, use the View Optional Column command.

Default

If the argument is marked as optional and the argument is empty or missing at run-time then the value in the Default column will be used.

To show or hide the Default column, use the View Default Value Column command.

Container

This column allows you to specify the C++ container class into which the argument's values will be copied.

If you leave it blank, then the default container class (as defined by the DefaultVectorContainer or DefaultMatrixContainer setting) will be used.

For details of the notation to be used for the container class, see Argument.ContainerClass.

Working with the argument list

Selecting arguments

You can select an argument by left-clicking with the mouse in one of the cells of the row that contains it. You can also use the arrow keys on the keyboard to move from cell to cell and row to row.

Multiple selection works in the same way as in the file list of the Windows Explorer. Holding the shift key down while left-clicking or moving with the arrow keys extends the selection: the selection will include the last active row and the newly selected row, and all rows in between.

Holding the control key down while left-clicking allows you to select a new row without deselecting the currently selected row(s). If the row clicked on is already selected, then it will be deselected.

Copy/Paste

You can use the Copy argument and Cut argument commands to put the selected arguments into the clipboard.

From there you can use the Paste argument command to insert them at a different location within the function's argument list. Alternatively you can paste them to a different function, after selecting a different function in the Wizard.

Drag and drop

You can move one or more arguments within the list of arguments by clicking within the selected arguments and dragging the mouse.

If you hold down the CTRL key at the same time as dragging then you will get a new copy of the dragged arguments. (The names of the new arguments will be altered to ensure uniqueness.)

Argument order

You can use drag and drop to move arguments up or down in the argument order. Select the arguments you want to move, and drag them with the mouse to a position earlier or later in the list.

You can also the Move argument up and Move argument down commands to change the selected argument's position.

Groups

Sometimes it is necessary or desirable to create a grouped argument. This is a group of arguments that appear as a single argument in Excel, but is split into its component inner arguments by the validation code.

The Function Wizard offers a variety of tools for working with groups.

The New Group command can be used to create a new empty group, to which you can then add new or existing arguments.
The Group arguments and Ungroup arguments commands can be used to group selected arguments or to ungroup an existing group.
You can drag an argument into or out of a group using the mouse.
You can use the Move argument right and Move argument left commands to move a group into or out of a group respectively.