Declare and describe an add-in function
IMPLEMENT_XLLFN4( LABEL nmEntryPoint, LABEL nmEntryPoint4, LABEL nmEntryPoint12, const char* pszArgTemplate4, const wchar_t* pszArgTemplate12, const wchar_t* pszName, const char* pszArgNames4, const wchar_t* pszArgNames12, const char* pszCategory4, const wchar_t* pszCategory12, const char* pszHelpText4, const wchar_t* pszHelpText12, const char* pszArgHelpText4, const wchar_t* pszArgHelpText12, unsigned int usHelpTopic, const wchar_t* pszHelpTopic, const wchar_t* pszExt12, int usType, int usMinVersion, int usMaxVersion ); |
Unique name of the add-in function. Note that the function name is not in quotes - it is a label, not a string. Most of the other arguments to the macro are strings, so they can be either string literals (such as _T("RB")) or references to strings (e.g. CMyXllApp::m_pszDefCategory).
Unique name of the add-in function's wrapper function, as used by Excel 2003 and earlier. Note that the function name is not in quotes - it is a label, not a string.
Unique name of the add-in function's wrapper function, as used by Excel 2007 and above. Note that the function name is not in quotes - it is a label, not a string.
The type text of the function as used by Excel 2003 and earlier, containing the data type of the return value and data types of the arguments. The first letter of the type text specifies the return value. Subsequent letters, starting with the second, specify the data types of the arguments, in order. For a list of data types and the letters used to represent them see Data types. Thus if, for example, if the string is "AB", it represents a function that returns a Boolean result and takes one double argument. See the table in Data types for a full list of the data types supported.
In addition, the string can be terminated by one or both of the characters '#' and '!'. The hash symbol ('#') indicates that resolution of the function's arguments is delayed. Experienced SDK programmers will appreciate the occasional utility of this option. See the Excel 97 Developer's Kit (Microsoft Press) for more information.
The '!' suffix makes the function volatile. Volatile functions are resolved every time any part of a worksheet is recalculated, or when the F9 function key is pressed or when Application.Calculate() is invoked. This option is useful when the results of functions are determined by outside factors (such as the current time, or data held in a database) in addition to the value of their arguments.
The type text of the function as used by Excel 2007 and above, containing the data type of the return value and data types of the arguments. The first letter of the type text specifies the return value. Subsequent letters, starting with the second, specify the data types of the arguments, in order. For a list of data types and the letters used to represent them see Data types. Thus if, for example, if the string is "AB", it represents a function that returns a Boolean result and takes one double argument. See the table in Data types for a full list of the data types supported.
In addition, the string can be terminated by any or all of the characters '#', '!' and '$'. The hash symbol ('#') indicates that resolution of the function's arguments is delayed. Experienced SDK programmers will appreciate the occasional utility of this option. See the Excel 97 Developer's Kit (Microsoft Press) for more information.
The '!' suffix makes the function volatile. Volatile functions are resolved every time any part of a worksheet is recalculated, or when the F9 function key is pressed or when Application.Calculate() is invoked. This option is useful when the results of functions are determined by outside factors (such as the current time, or data held in a database) in addition to the value of their arguments.
The '$' suffix declares that the function is thread-safe. This permits the Excel calculation engine to call the function in multiple threads and on multiple processors.
Name of function as exported to Excel. This is the function's name as you will use it in Excel - it does not need to be the same as the 'C' name of the function.
The names of the function's arguments, as used by Excel 2003 and earlier, separated by commas. For example, "Arg1,Arg2".
You can localize each argument name by using resoure IDs.
The names of the function's arguments, as used by Excel 2007 and above, separated by commas. For example, L"Arg1,Arg2".
You can localize each argument name by using resoure IDs.
The category under which the function will appear in the Excel Function Wizard, under Excel 2003 and below.
This argument is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Category for more information.
The category under which the function will appear in the Excel Function Wizard, under Excel 2007 and above.
This argument is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Category for more information.
The description of the function which will appear in the Excel Function Wizard, under Excel 2003 and below.
This help text is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Help text for more information.
The description of the function which will appear in the Excel Function Wizard, under Excel 2007 and above.
This help text is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Help text for more information.
The descriptions of the function's arguments which will appear in the Excel Function Wizard, under Excel 2003 and below. Each description should be separated from the next by a null character ("\0"). An extra null character should terminate the string. Thus a function that concatenates its two arguments might have argument help text as follows: "Left-hand string\0Right-hand string\0\0".
Each of the arguments' help texts is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Help text for more information.
The descriptions of the function's arguments which will appear in the Excel Function Wizard, under Excel 2007 and above. Each description should be separated from the next by a null character ("\0"). An extra null character should terminate the string. Thus a function that concatenates its two arguments might have argument help text as follows: L"Left-hand string\0Right-hand string\0\0".
Each of the arguments' help texts is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Help text for more information.
The Help ID of the topic that describes this add-in function. 0 indicates that no help is available.
The name of the topic that describes this add-in function. If this string is empty, then usHelpTopic will be used.
A full definition of the function, in a proprietary format. It is this string that is read by the XLL+ Function Wizard, since it contains a complete definition of the function.
Flag indicating from where the function may be invoked. 1 indicates that the function is available only from Excel worksheets; 2 that it is available only from Excel macro sheets; 3 that it is available in both. No other values are acceptable.
The minimum Excel major version number required. If the Excel major version number is less than this value, then the function will not be registered. Ignored if zero.
The maximum Excel major version number allowed. If the Excel major version number is greater than this value, then the function will not be registered. Ignored if zero.
The IMPLEMENT_XLLFN4 macro manages the registration of a 'C' function as an Excel add-in function. It is supported by the XLL Plus Function Wizard, which can be used to maintain the code for both the macro and the function definition.
Note that several of the string arguments to the macro accept resource ID strings which are loaded from the application resource file at run-time.
The macro defines a static instance of a 'C' structure (XLLFN) which contains the details that define the add-in function. It also defines another 'C' structure (XLLFN_INIT) whose constructor function will add the address of the XLLFN to a global chain intitialised at DLL load time, before any other methods or call-back functions are invoked.
When the function AddStaticFns() is called during the DLL's InitInstance() method, the functions defined in the global chain are added to the CXllApp object's function list. During the XllLoad operation invoked by Excel when the XLL is opened, this list of functions is registered with Excel using the SDK xlfRegister entry-point.
Header: xllplus.h