1.1.2 X-Function Builder

Open X-Function Builder by clicking Tools: X-Function Builder.

X-Function Name

Input the X-Function name in the X-Function edit box.

Do not give your X-Function the same name as an existing LabTalk macro, OGS file, LabTalk command, or LabTalk callable Origin C function.

If two or more of these have the same name, the priority order of calling is: LabTalk macros > LabTalk OGS > X-Function > LabTalk callable Origin C functions > LabTalk commands.


X-Function Variables

Name

Specify the name of the variable. When the X-Function is executed by script, you have to assign values to variables using their names. Therefore, we recommend that you use shorter names and begin them with different characters.

Label

Specify a label for the variable. Special characters and white space are allowed. Displays on the X-Function dialog as control label. If not specified, variable name will be used.

Input/Output

Specify whether the variable is used for input, output or both.

Data Type

Specify the variable data type.

More details can be referred to below in the Variable Data Type and Default Value section.

Data

Specify the default value for the variable. More details can be referred to below in the Variable Data Type and Default Value section.

Control

Specify the control for the variable in the dialog box (combo box, slider, etc.).

More details can be referred to below in the Control Types section.

Option String

Specify an option string for the variable. You can apply advanced settings with option strings, such as grouping several variables together, enabling recalculation, etc. More details can be referred to below in the Option String section.

Theme ID

Specify the Theme ID for the variable. If not assigned, the Theme ID of the variable will refer to the index of the variable. The Theme ID is used in the theme file for the X-Function dialog.

More details can be referred to below in the Theme ID section.

Variable Data Type and Default Value

X-Functions provide dozens of data types, as below.

  1. Basic Data Type
    • Types are double, string, int.
    • The default value can be 0 for numeric or kept empty for string type.
  2. Origin Composite Data Type
    • Types are vector, vector<string>, vector<complex>, and matrix.
    • For example, a vector can attach to a worksheet column as input or output.
    • The default value can be <active>, <new>, or <unassigned>.
    • For more details, please refer to the Origin C help Composite Data Types book.
  3. Origin Object Type
    • The types are Column, Range, GraphLayer and other Origin Object types.
    • The default value can be <active>, <new>, <input>, or <unassigned>.
    • Origin C provides the function BOOL okxf_resolve_string_get_origin_object(LPCSTR lpcsz, OriginObject* pObj) to get an Origin Object from a GetN tree string value.
    • For more details, please refer to the Origin C help Internal Origin Objects] book.
  4. TreeNode Type
    • Types are TreeNode, ReportData, and ReportTree. TreeNode is input, ReportData and ReportTree are output.
  5. Origin Graphical Object Control
    • Types are ButtonInfo, LineInfo, TextInfo and so on.
    • To see the usage, open a built-in X-Function from OriginEXE\X-Functions\Data Manipulation\curve translate.OXF in X-Function Builder as an example.
  6. Report Type

Control Types

After specifying the different control strings in the variables grid Control column in the X-Function Builder, we can easily create different types of user interface controls in the X-Function dialog.

Usage Data Type Control String
Numeric Edit Box double  
Text Edit Box string  
Check Box int 0|1
Combo Box int
  • string1|string2|string3
  • CaseA:string1|CaseB:string2|CaseC:string3
Editable Combo Box string Keep empty in the Control column in the Variables grid, but add the codes below to the xfname_before_execute function to set the var variable control as an editable combo box.
if( nGetNDialog > 0 )
    trGetN.var.SetAttribute(STR_COMBO_ATTRIB, "|aa|bb|cc");
Radio Box int Radio:string1|string2|string3
Slider int/double slider:start|end|nstep
Color List int
  • ColorList, 24 basic colors panel
  • Color0, normal colors panel
Graph Browser string
  • ...Graph for one graph
  • ...Graphs for multiple graphs

Origin supports interface settings for the Graph Browser in an OriginC function, using the control string GraphBrowserFilter. See X-Function Graph Browser Dialog Example for details.

Text Edit Box with File Browser Button string
  • ...File for single file
  • ...Files for multiple files
Text Edit Box with Path Browser Button string
  • ...Path, to open the select folder dialog
  • ...Path2, to open the browse folder dialog

Note: Set system variable @FBL = 0 will toggle new/old folder browser, i.e. ...Path to open the browse folder dialog, while ...Path2 to open the select folder dialog.

Text Edit Box with Save As Browser Button string ...Save

Option String

We can set the special string in the Option String column to specify the action of a variable. For example, setting the recalculate default mode, setting the number of decimal digits for a numeric control, or setting the default name of an output object. For more details, see Reference: X-Function Option Strings.

Theme ID

The Theme ID is used in the X-Function dialog theme file, and the default value is 0. If you keep the Theme ID of all the variables at 0(default), the Theme ID in the theme file will be converted according to the index of the variable, beginning from 1.

When you want to insert a variable into an existing X-Function (to append a variable as the last, there's no need do this), in order to remain compatible with the existing theme file, you need to:

  1. Before inserting the variable, change the Theme ID from 0 to the index of the variable.
  2. Insert the variable.
  3. Set the Theme ID for the inserted variable as the maximum to avoid repeats.

Tree View

Click the Tree View button Ocguide xf treeview button.png to switch to tree view. The settings in Tree View are mainly used to create X-Function dialogs, add X-Functions to the Origin menu, and add documentation. See the next chapter, Customizing an X-Function, for details.

Ocguide xf treeview.png