Options»Generate Function Tree

Use this command to generate a function tree from a header file. This command opens a dialog box, which contains the following options:

  • Input header file—The header file from which to generate the function tree. LabWindows/CVI fills in this field with the currently active header file.
  • Instrument name—The name of the instrument to generate.
  • Function prefix—The common prefix for functions in the instrument. For example, if you have the following functions in the header file

    int DllExport __CFUNC MyInstrumentInit (void);
    int DllExport __CFUNC_C MyInstrumentFormat (char *format, ...);
    int DllExport __CFUNC MyInstrumentClose (void);


    you should use MyInstrument as the prefix.

    The first character in the prefix can be a letter or an underscore only. All of the rest of the characters in the prefix can be an alphanumeric character or an underscore.

    If you use an underscore in the header file to separate the prefix from the function name, you must also include an underscore in Prefix.
  • Default qualifier—The default qualifier for functions in the instrument. LabWindows/CVI will include in the generated function tree only the functions with the default qualifier you specify or the specified default qualifier appended with _C. For example, for the preceding functions, you should use DllExport __CFUNC as the default qualifier.
  • Output function tree—The absolute path of the generated function panel file.
  • Output header—The absolute path of the generated header file. This header file is identical to the one used for generating the function tree except that all the special tags are removed. This field is optional. LabWindows/CVI preserves white space from the header file to the generated header file.

LabWindows/CVI creates a function panel for each function. You must follow specific rules and use special tags in the header file.

When you complete the Generate Function Tree dialog box and click OK, LabWindows/CVI performs the following actions for each function panel it creates.

  • Removes the function prefix
  • Capitalizes the first letter
  • Inserts a space before each first capital letter or digit in a group of capitals or digits

    For example, Set6100SensorRpms becomes Set 6100 Sensor Rpms
  • Replaces substrings, specified with XCHG and PXCH, in function names and parameter names
  • Places the function in the function tree under the current class and with the current parameters

Rules for Header Files

Your header files must conform to the following rules:

  • Declare all non-LabWindows/CVI types in the header file with typedef. #define for a type does not work.

    The Generate Function Tree command does not support typedef identifiers for function pointer types.
  • For enums, keep the following rules in mind:
    • Declare one enum per line.
    • Use a comment (//) after the enum to be used as a value label in the function panel.
    • Do not assign values. LabWindows/CVI ignores assigned values.
    • Do not use additional comments in enums; the // comment specifies an optional label for each enum value.
    • Avoid semicolons inside enumeration lists, including comments.
  • Use const char string[] for input strings.
  • Make sure that function declarations contain the specified function qualifier. For example, if you specified CVIFUNC as function qualifier, every function must start with CVIFUNC or CVIFUNC_C.
  • Avoid nested comments or combination of comment styles (//, /**/, or /* // */).
  • Do not use nested structures (a structure within another structure). Multiple bracket levels are not recognized.
  • Do not use comments inside function declarations or within parameter lists.

Tags in Header Files

Note  The following tags might appear similar to the tags you use to document source code. However, you can use the following tags only in .h files for the purpose of defining a function tree structure. You can use the documentation comment tags only in .c files for the purpose of adding information that appears in function prototype tooltips or generated help files.

You can use the following tags in the header file. Add the tags on the line immediately preceding the function. For example, specify the following:

/// SLD 2
/// BIN 3/MyEnum2
/// RNG 4/MyEnum2
i8 CVIFUNC MyInstr_ClassNoneFunction3 (MyEnum1 parameter1, MyEnum1 parameter2, i16 parameter3, u16 parameter4);

Tag Description
/// ; Comment here Ignores the whole line as a comment.
/// INCL Parses the specified header file. Use this tag to parse data types defined in other header files.

This tag applies to the header file immediately following the tag.

Example use

/// INCL
# include "file.h"
/// INCL
# include <anotherFile.h>
/// -> Class Name Creates a new class node of the specified name.
/// <- Class Name Goes one level up/back in the function tree. The class name is optional and is used for better orientation in the header file.
/// OUT p1,... Specifies which parameter of a function is output.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.

Example use
/// OUT 2,3,4
void SplitPath (char Pathname[], char Drive_Name[], char Directory_Name[], char File_Name[]);
/// PTYP p1/type,... Changes the parameter type for the specified parameters.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.

Example use
/// PTYP 2/Any Type,4/Any Array,5/Numeric Array
/// DFLT p1/val,... Specifies the default value for a parameter.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.
/// CUST p1/dll/fn,... Specifies the customization DLL and handler for a parameter.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.
/// EHDV p1/value,... Specifies which enum has an additional default value. A default value is added to the beginning of the enum. You can use this tag with RNG and SLD tags.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.
/// ENUM name Starts a list of #define values that represents an enum of the specified name. You can use this tag with RNG, BIN, and SLD tags. The list of values must end with an empty line.

You can use the ENUM tag and/or a C typedef in the header file from which you generate a function tree, as is shown in the following example:

typedef enum
{
zero, //my zero
one, //my one
two, //my two
} test;

/// ENUM binary
#define on 1 //one
#define off 2 //two

/// BIN 1/binary
/// DFLT 1/on
/// SLD 2
int CVIFUNC T_function (int para1, test para2);
/// BIN p1/enum,... Specifies which parameter of a function is a binary control. enum is optional; it specifies the enum name. enum is the name of a regular enum or an enum created using the ENUM tag. The parameter must be of an enum type if you omit the slash. The enum must contain exactly two values.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.

Example use
/// BIN 2
void OpenFile(char Pathname[], enumTxtBin mode);


Example use
/// BIN 2/enumTxtBin
void OpenFile(char Pathname[], unsigned mode);
/// SLD p1/enum,... Specifies which parameter of a function is a slide control. enum is optional; it specifies the enum name. enum is the name of a regular enum or an enum created using the ENUM tag. The parameter must be of an enum type if you omit the slash. The enum must contain at least two values.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.

Example use
/// SLD 2
void OpenFile(char Pathname[], enumTxtBin mode);


Example use
/// SLD 2/enumTxtBin
void OpenFile(char Pathname[], unsigned mode);
/// RNG p1/enum,... Specifies which parameter of a function is a ring control. enum is optional; it specifies the enum name. enum is name of a regular enum or an enum created using the ENUM tag. The parameter must be of an enum type if you omit the slash. The enum must contain at least one value.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.

Example use
/// ; You can omit the RNG tag in this case.
/// ; The ring is created automatically if an
/// ; enum is found in the place of the parameter type.
/// RNG 2
void OpenFile(char Pathname[], enumTxtBin mode);


Example use
/// RNG 2/enumTxtBin
void OpenFile(char Pathname[], unsigned mode);
/// ERNG p1,... Specifies which parameter of a function is a ring control with no values. This tag is used mostly for Set/GetAttribute functions. The parameter type cannot be of an enum type.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.

Ring controls cannot be empty. LabWindows/CVI inserts 0 as the default value for the ring control when you generate the function tree.
/// NUM p1/MinVal/MaxVal/IncVal/Precision Specifies the minimum value and maximum value of a numeric control, how much to increment the numeric control, and the precision of the control.

This tag applies only to the function immediately following the tag.

Example use
/// NUM 3/0.0/100.0/1.0/2
int CVIFUNC SetPercentage (int panel, int myCtrl, double percentage, char *label);
/// XCHG s1/s2,... Replaces string s1 with s2 in function panel titles.

You must specify /// XCHG on the line following the function to stop replacements. Do not include multiple instances of this tag without specifying /// XCHG between them. If you do so, the last instance overrides the previous instances.

For example, if you have a function with a name PrefixVXIPnPCfg, the generated title for this function is V XIPn PCfg, because of the word splitting mechanism. You can correct problems like this by using the XCHG tag. For example, place the following XCHG tag in front of the function in your header file: /// XCHG V XIPn PCfg/VXI PnP Configuration. Your function panel title will then be VXI PnP Configuration.

You can place '|' characters around s1 to replace s1 only if it matches the entire function panel title. For example, if you include the following line in a header file: /// XCHG Fill/Fill Table, the Fill function panel name will become Fill Table and the Fill Tree function panel name will become Fill Table Tree. If you include the following line in the header file instead: /// XCHG |Fill|/Fill Table, the Fill function panel name will become Fill Table but the Fill Tree function panel name will remain Fill Tree.
/// PXCH s1/s2,... Replaces string s1 with s2 in function panel controls.

You must specify /// PXCH on the line following the function to stop replacements. Do not include multiple instances of this tag without specifying /// PXCH between them. If you do so, the last instance overrides the previous instances.

You can place '|' characters around s1 to replace s1 only if it matches the entire parameter name. For example, if you include the following lines in a header file:

/// PXCH l/length
int GetLength(char *literals, int l);


LabWindows/CVI will replace the 'l' characters in both parameters with "length". Therefore, the literals parameter will become lengthiteralengths.

However, if you include the following lines in the header file:

/// PXCH |l|/length
int GetLength(char *literals, int l);


LabWindows/CVI will replace only the l parameter with length. The literals parameter will remain literals.
/// BINB type/OffVal/OnVal/defVal Specifies what data type to associate with a binary switch control. This tag also specifies labels for both values and index of the default value. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances. You cannot use this tag for an enum type.

Example use
/// BINB int/Off/On/1

long MyFunction(int parameter1, unsigned short parameter2, int parameter3, short parameter4);


When you specify which data type is associated with a binary control, all parameters of that data type in the function are generated as binary switches. In the previous example code, both parameter1 and parameter3 are generated as a binary switch with labels Off and On with a default value of On.
Note  NI recommends that you use the BINB tag only for Boolean parameters.
/// VARG type/name,... Adds the specified parameters at the end of the parameter list that ends with ... (variable argument list).

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.

Example use
/// VARG Any Type/Value,int/Number of Elements

You optionally can specify the name of the help file whose contents are copied into the control help for name. Use the following tag:

/// VARG type/name/helpfile, type2/name2/helpfile2

If you want the function prototype to have a variable argument list (...), you must use the following syntax:

/// VARG Any Type/parameterName
/// RETV name Specifies the name of the return value. If you do not use this tag or you use the tag without a name, the default name Return value is used.

Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.
/// LDEP dependency Specifies a dependency to add to the dependency load list.

Example use
/// LDEP toolbox.fp
/// FP title Specifies the title of the instrument. If you do not use this tag, the function panel filename is used for the function panel title.

Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.
/// ADDT typename Adds a type to the function panel.

Adds: typename
typename []
typename *
typename **
typename *[]
/// EX Excludes the following lines from function panel generation. This tag ignores all other tags, functions, enums, and so on until it finds the UNEX tag.

Note  The code excluded from the generation still has to follow the syntax. If you want to exclude code that is not syntactically correct, use comments instead. Also, EX and UNEX tags support nesting.
/// UNEX Stops excluding code from function panel generation. This tag supports nesting.
/// HFP helpfile Copies the contents of helpfile into the instrument help of the function tree.

Do not include multiple instances of this tag. If you do so, the last instance overrides the previous instances.
/// HIFP help text Specifies the help text for the function tree. Do not include multiple instances of this tag. If you do so, the last instance overrides the previous instances. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

Example use
/// HIFP Describe the function tree.
/// HCL helpfile Sets the class help for the class node following this tag to the contents of helpfile.

This tag applies only to the first class node following this tag. Do not include multiple instances of this tag for a class node. If you do so, the last instance overrides the previous instances.
/// HICL help text Specifies the help text for the class. This tag applies only to the first class node following this tag. Do not include multiple instances of this tag for a class node. If you do so, the last instance overrides the previous instances. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

Example use
/// HICL Describe the class.
/// HFUN helpfile Sets the function help for the function following this tag to the contents of helpfile.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.
/// HIFN help text Specifies the help text for the function. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

Example use
/// HIFN SampleFunction returns the value of a control.
/// HPAR p1/helpfile1,... Sets the help for parameter p1 for the function following this tag to the contents of helpfile1.

This tag applies only to the function immediately following the tag. Do not include multiple instances of this tag for a function. If you do so, the last instance overrides the previous instances.
/// HIPAR p1/help text Specifies the help text for a parameter. p1 is the parameter for which you want to specify help. Do not include multiple instances of this tag for a single parameter. If you do so, the last instance overrides the previous instances. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

You do not need to provide help text for every parameter. If a parameter does not have help text specified for it, LabWindows/CVI displays the function help, if it exists.

Example use
/// HIPAR p1/The name and description of the control.
/// HIPAR p2/The name and description of the control.
/// HRET helpfile Sets the help for the return value for the functions following this tag to the contents of helpfile. If you do not use this tag or you use this tag without a help file name, the default help "No help available" is used.

Do not include multiple instances of this tag. If you do so, the last instance overrides the previous instances.
/// HIRET help text Specifies the help text for the return value. Do not include multiple instances of this tag for a return value. If you do so, the last instance overrides the previous instances. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

Example use
/// HIRET The return value indicates whether the function was successful.

WAS THIS ARTICLE HELPFUL?

Not Helpful