1.4.2 X-Function Option Strings

X-Function, Option Strings

A - Recalculate ModeX-Function, Recalculate Mode

Recalculate Options enable you to control the Recalculate mode of an X-Function. By default, when the X-Function includes one of the following Origin Object types as an input or output variable: XYRange, XYZRange, vector, Column, matrix and MatrixObject, it allows you to use Manual, Auto or None as the Recalculate mode (the default mode is Manual). Please note that if the variable is used as both an input and output variable, the Recalculate mode is forbidden, and the Recalculate combo box will be hidden.

A:0x00

Hides the Recalculate combo box from the X-Function dialog.

Example

1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Run this X-Function with the command OptionStringA -d; in the Command Window. In the dialog that opens, you will not see the Recalculate combo box.
   

A:0x01

Sets None as the default Recalculate mode. This mode is available for both input variables and output variables.

Example

1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Run this X-Function with the command OptionStringA1 -d; in the Command Window. In the dialog that opens, the Recalculate combo box shows with None selected.
   

A:0x02

Allows sorting on the output columns with the Recalculate mode. It works for output variables only.

Example

1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Create a new worksheet with one column and fill this column with row numbers. Then highlight the column and run the X-Function with the command OptionStringA2 -d; in the Command window. After clicking the OK button, two empty output columns with locks will show, as below.
   
3. Click on the header of column B to highlight it, then move the mouse to the Sort Worksheet item of the right-click menu. The sub context menu is available for sorting the output columns.
   

A:0x04

Allows the Recalculate mode, but the Recalculate combo box will be hidden in the X-Function dialog.

B - Browser Dialog OptionsX-Function, Browser Dialog Options

Browser Dialog Options control the settings in the Page/Graph Browser dialog, which is opened by a button in the X-Function dialog. They can also be used to filter the opened dialog. Please refer to the example about X-Function Graph Browser dialog.

B:0x0001

Sorts all pages in the Page/Graph Browser once the dialog opens.

B:0x0002

Excludes 3D graphs from the Graph Browser.

C - Miscellaneous Options

C:0x0001X-Function, Disable Auto Assigning Column Designatioin

Disables composite ranges from assigning column designation. Take an output variable with XYRange type, for example. If this option string is not specified for the variable, there will be two output columns, one with X designation and the other with Y designation. Otherwise, the two columns will both have the default Y designation.

C:0x0002X-Function, New Hidden Page

Creates a new page with hidden state.

C:0x0004 X-Function, Disable Undo

Makes an X-Function non-undoable.

C:0x0010 X-Function, Missing Data Display Format

By default, if a variable with double type is missing a value, this variable will show nothing (empty cell). This option string is used to show this kind of empty variable as "--".

C:0x0100 X-Function, Set Output Range Dimension

This option string is only available for output variables of Range type. If the output variable is set to <new>, a valid Origin C Range object will be created, but without a new column for it. This option string helps the user prepare rows and columns for the output range objects inside the X-Function body.

C:0x0200

This option string is only available for output variables of Range type. If the output variable is set to <new>, it will replicate the input Range, with the same number of columns and rows.

C:0x0400

Applicable to MarkerInfo and ButtonInfo XVariable. If set will make it hidden.

C:0x0800

Applicable to output XVariable. If set will suppress writable checking.

C:0x1000

Applicable to any XVariable. If set will always support generate script from dialog.

C:0x2000

Available from 9.0. Applicable to Output Page/Layer XVariable. If set will check the value of another XVariable call "hide" to determine to hide new created page.

C:0x4000

Available from 9.0. Applicable to XVariable which is group begin (with Option String G ). If set will not hide whole branch if current XVariable is hidden.

E - Execution ControlX-Function, Execution Control

E:V

Used in the X-Function wizard and X-Function bar to keep the real value of a variable. The destination created by the first Apply button will be used by the subsequent Apply buttons.

F - Dialog Numeric Display FormatX-Function, Dialog Numeric Display Format

F:*6*

Provides a format string for displaying numeric values with double type. The standard LabTalk numeric format notation, such as *(Origin global numeric format setting), .2(two decimal digits), etc., can be used.

FT - Data Plot Selection FilterX-Function Data Plot Selection Filter

FT:str1|str2

Specifies the tags for the action filter of data selection from a graph. If a data object contains tags str1 or str2, it will be ignored when selecting the data hunting menu item Add all plots in active page/layer.

Example

This example will show how to use the FT option string to exclude the data plot with tag name TestCurves when selecting all plots from a graph.

1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Open this X-Function in Code Builder, then copy the following code and paste it into the body of the main function, OptionStringFT, then click the Compile button .

   // Put data to output XYRange
   vector vx, vy;
   vx.Data(1, 10, 1);
   vy = vx;
   oy.SetData(&vy, &vx);
   
   // The specified name should be the same as options string "FT" of iy
   tag_columns_in_data_range(oy, "TestCurves"); 
   
   // Get source range graph, and plot results on this graph 
   vector<uint> vnIDs;
   if( iy.GetPlots(vnIDs) > 0 )
   {
   	DataPlot dp;
   	dp = (DataPlot)Project.GetObject(vnIDs[0]);
   	GraphLayer gl;
   	dp.GetParent(gl);
   	
   	gl.AddPlot(oy);
   }

3. Import the file <Origin Installation Folder>\Samples\Curve Fitting\Multiple Gaussians.dat to a new worksheet. Highlight all columns and make a graph with line plots. Activate the newly created graph and run OptionStringFT -d; in the Command Window, then click the OK button to generate the output XY columns in the source worksheet and add its plot to the source graph.
4. Activate the graph and run OptionStringFT -d; again to open the X-Function dialog. In the Input XY branch, the newly outputted data plot from above is not there, because of the tag name TestCurves of this data plot.

FV - Specify the Source of Output VariableX-Function, Specify the Source of Output Variable

FV:varname specifies the name of the input variable for each output variable. Then the information of this variable's book/sheet/object will be traced and shared with the output variable when the output variable is set by <input>/<same>. For example, suppose an X-Function contains three XYRange variables: the first two are input variables and the last one is an output variable. If the name of one input variable is set to the output variable by this option string, the output columns will be the same as the specified input columns when output is set as <input> or <same>. Otherwise, the output columns will be the same as the first input columns.

G - Grouping Controls on GUIX-Function, Grouping Controls on Dialog

Used to group related variables in the X-Function dialog. Add G:Group Name in the Option String field of the variable for the beginning of the group, and G in the Option String field of another variable for the end of the group.

G:Group

The beginning of the group. By default, the branch of the group is closed. To set the branch as open for the first time, open the dialog and add a dash before Group Name, like G:-Group Name. Then the dialog will remember the branch status when opened next time.

G

The end of the group.

Example

1. Press F10 to open X-Function Builder. Create an X-Function as the following image shows and then click the Save button to save it into <Origin User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Run OptionStringG -d; in the Command window. The dialog that opens will look like the one below.
   

H - Setting Result Tables Shown StyleX-Function, Set Result Tables Shown Style

1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Open this X-Function in Code Builder, and add the following needed header file after the line //put additional include files here.

   #include <ReportTree.h>

3. Copy the following code into the main function, OptionStringH, which is used to do basic statistical analysis on the selected data and then prepare the report sheet for the results.

   // Get data from Data Range object
   matrix mData;
   if( rng.GetData(mData) <= 0 )
   {
   	XF_THROW("No data is selected");
   }
   
   // Calculate the basic statistics on each column 
   vector vPoints, vSum, vSD;
   for(int index = 0; index < mData.GetNumCols(); index++)		
   {
   	vector vData;
   	mData.GetColumn(vData, index);
   	
   	int nPoints;
   	double dSum, dSD;
   	ocmath_basic_summary_stats(vData.GetSize(), vData, &nPoints, 
   				&dSum, &dSD);
   	
   	vPoints.Add(nPoints);
   	vSum.Add(dSum);
   	vSD.Add(dSD);
   }	
   
   // Create data table
   int nID = 0; // ID should be unique
   ReportTable rTable = rt.CreateTable("Report", "Report Table", ++nID, 0, 1);	
   rTable.AddColumn(vPoints, "N", ++nID, "Points", OKDATAOBJ_DESIGNATION_Y);
   rTable.AddColumn(vSum, "Sum", ++nID, "Sum", OKDATAOBJ_DESIGNATION_Y);
   rTable.AddColumn(vSD, "SD", ++nID, "SD", OKDATAOBJ_DESIGNATION_Y);
   
   // Set this attribute as 0 not to specify any format.
   // Many bits GETNBRANCH_* defined in oc_const.h to set table display format.
   rTable.SetAttribute(TREE_Table, GETNBRANCH_TRANSPOSE);

4. Create a new worksheet with five columns, then fill all the columns with uniform random data (by highlighting all columns and selecting context menu item Fill Columns With: Uniform Random Numbers). Run OptionStringH -d; in the Command window to open the dialog. In the dialog, make sure that all the columns are selected for Input Data and <new> is selected for Report. Click the OK button and the report sheet will be displayed in the normal format (H:0).
   
5. Open the X-Function in the X-Function Builder again and change H:0 to H:1. Then save it. Run OptionStringH -d; in the Command window again. This time the report sheet will display in hierarchical table format (H:1).
   

I - Restrict the Behavior of Input Range ControlX-Function, Input Range Control

Restricts the input data range and modifies the behavior of the interactive controls. This Option String only works for the following input data types: Range, XYRange, XYRangeComplex, XYZRange, vector, vector<string>, and vector<complex>.

I:0x0001

Allows multiple data selection in the 1st subrange.

I:0x0002

Allows multiple data selection in the 2nd subrange.

I:0x0004

Allows multiple data selection in the 3rd subrange.

I:0x0008

Allows multiple data selection in all subranges.

I:0x0010

Restricts to one dataset.

I:0x0020

Supports Y error, XYRange only.

I:0x0040

Supports label area in Range. By using this Option String, the output range will not clear the data before execution, which is similar to I:0x00040000.

I:0x0080

The <input> option will disappear from the pop-up menu of the output variable.

I:0x0100

The <new> option will disappear from the pop-up menu of the output variable.

I:0x0200

The (<input>,<new>) options will disappear from the pop-up menu of the output variable, XYRange only.

I:0x0400

Gets rid of the button for the pop-up menu.

I:0x0800

Gets rid of the interactive button.

I:0x1000

Valid for input variables with vector and Column type only. When the string for data selection is obtained, Columns are identified by indices, but not the short names of the columns.

I:0x2000

This Option String will make the vector variable only use the Y column while initializing.

I:0x4000

Shows the Column Browser button.

I:0x8000

Sets variable as read-only, both I:0x0400 and I:0x0800 together will also work.

I:0x00010000

Gets rid of row selection while initializing or during interactive moment. Variable type: Column, Range and XYRange.

I:0x00020000

Replaces the range string of the whole sheet with column notation. For example, if a worksheet in Book1 named Sheet1 contains two columns, then the range string [Book1]Sheet1 will be replaced with [Book1]Sheet1!1:2.

I:0x00040000

This Option String makes the output range not clear the data before finishing the execution. Without this Option String, if there is no overlap in the input data ranges, columns in the output ranges will be cleared before using new data.

Example

1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Open this X-Function in Code Builder, then copy the following code, which will copy data from the input column to the output column, into the body of the main function, OptionStringI, and then click the Compile button .

   orng = irng;

3. Create a new worksheet with two columns: column A and column B, then select the first 10 rows in column A and choose Fill Range with: Row Numbers from the right-click menu to fill these 10 rows with row numbers. Run OptionStringI -d; in the Command Window, choose column A as input and column B as output, then click the OK button. The result is that column B is now also filled with row numbers.
4. Select the first 5 rows from column A, right-click them to open the context menu, and choose the Delete item to delete these 5 rows. The color of the lock on the header of column B changes from green to yellow. Click the lock and choose Recalculate from the pop-up menu. The result is that the original data in the last 5 rows of column B are kept there, as shown in the following image.
   

I:0x00080000

Makes all columns hidden in the interactive pop-up menu.

I:0x00100000

If there are no selections in the active graph layer and the range variable is set by using <active>, the range variable will set to all plots in the active layer.

I:0x00200000

Uses the sampling interval as output X.

I:0x00400000

I:0x00800000

Makes the existing columns or plots show in the interactive pop-up menu.

I:0x02000000

If the output XYRange is set by using <auto>, this option creates a new X column.

I:0x04000000

The row range will be ignored, and only the single block range is valid. If there is no selection or the selection only includes one single cell, the selection will be considered to be the whole worksheet.

I:0x08000000

Creates the range string by using the first and last X values instead of the indices. The syntax is [BookName]SheetName!ColName[xFirstValue:LastValue]. It is very useful for monotonous data.

I:0x10000000

The Range variable will have no factor and no weight.

M - Support Multi-line StringX-Function, Multi-lines Text Control

M:m-n

Makes a string variable support multi-line text. If the string variable is hidden, m lines of text are supported, if expanded, n lines are supported. Add * to the row range string to resize on the bottom right corner of the edit control.

N - Setting the Default Name of Output ObjectsX-Function, Set the Default Name for Output Object

Specifies the default name of an output object.

• ReportTree and ReportData

N: Book:="Book Name" Sheet:="Sheet Name"

• MatrixObject

N: Book:="Book Name" Sheet:="Sheet Name" X:="Object Name"

• MatrixLayer, Image, vector, Column

N: "Name"

• XYRange

N: X:="X Name" Y:="Y Name"

• XYZRange

N: X:="X Name" Y:="Y Name" Z:="Z Name"

• Worksheet

N: Book:="Book Name" Sheet:="Sheet Name"

Beginning with version 2021b, Origin supports substitution notation for the output name, for example, N:"Stats of %W". Variables are documented in the [OutputLongName] section in User Files\Origin.ini, as follows:

• %A = analysis tool (e.g. FitNL) or X-Function name
• %W = input sheet name
• %N = input column Long Name, or Short Name if no Long Name
• %B = input book Long Name
• %S = input book Short Name

O - Setting Output Object Action after Running X-FunctionX-Function, Set Output Object Action

Specifies the action of the output variable after running successfully.

O:A

Activates the corresponding Origin object, no matter if the object is hidden or in a different folder.

O:C

Activates the corresponding Origin object only when the workbook is the active window.

O:N

Does not activate the corresponding Origin object.

X-Function, Editable/Disable ControlP - Setting Control Editable on GUI

Specifies whether a variable is editable in the X-Function dialog.

P:0 or P:1

P:1 is the default Option String. Using this Option String, the output variable, which is of an Origin object type, such as column, worksheet, etc., will be non-editable when bringing up the X-Function dialog again via Change Parameters. The variables with other types need to specify the Option String as P:0 to do so.

P:2

Only shows the label, and the editable field is invisible. Usually it is used to show the hint text.

P:4

Shows the variable as a separator in the X-Function dialog; valid for string type only.

Example

1. Press F10 to open X-Function Builder, and create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Click the Edit X-Function in Code Builder button to open this X-Function in Code Builder. Type the code out = in + var; into the body of the main function, OptionStringP, and then click the Compile button .
3. Create a new worksheet and fill some data into column A. Run OptionStringP -d; in the Command window. In the dialog that opens, select column A as Input Column and column B as Output Column. Click the OK button, and the result is generated and stored in column B.
4. Click the lock icon on the header of column B and choose Change Parameters from the context menu. The difference between the dialog opened by Change Parameters and the one opened by OptionStringP -d; is shown in the following image.
   

R - Restrict the Behavior of Dialog Combo BoxX-Function, Dialog Combo Box

Used to control the value of the combo box in the X-Function when calling it via LabTalk script. It will not affect the dialog.

R:0

No restriction. Besides the values defined in the list in the combo box, other values can also be assigned to the combo box variable by using LabTalk script.

R:1

Default Option String. Only the values defined in the list in the combo box can be assigned to the combo box variable by using LabTalk script.

Example

1. Create a new X-Function (named OptionStringR) with a variable (named x1) of int type. In the Control column, set AA|BB|CC for this variable.
2. Run OptionStringR x1:=5; in the Command window, and you will get an error: #Command Error!.
3. Open this X-Function in X-Function Builder again, set R:0 for the int variable in the Option String column and save this X-Function.
4. Run OptionStringR x1:=5; in the Command window again, and you will get no error.

S - Defining Default Data Selection for Input VariableX-Function, Data Selector Default Selection

Defines the default data object for input variable. This Option String is only for variables of Range type.

S:0

All columns in the active worksheet are selected as the data range.

S:0x01

The first matrix object of the active matrix sheet, or the first column of the active worksheet, is selected as the data range.

S:0x10

Makes it so the <active> option gets nothing but the matrix object. For the output variables, the <active> option will be replaced with <new>, which will create a matrix page.

SV - Support String Item in X-Function Dialog Combo Box

Replaces the item values in a combo box with special values. For example, if a variable of int type is set as a combo box via the Begin|Mid|End string in the Control column, then the default item values for the combo box items are 0, 1, and 2, respectively. If the Option String SV:1|5|-1 is used for this variable, the return values of the items in the combo box are 1, 5, and -1, respectively.

X-Function, Dialog ThemeT - Skipping the Variable from Theme

Controls whether a variable is remembered in the X-Function dialog theme file. This Option String is only valid during theme selection in Tree View, which is the default setting.

T:0

If the specified theme is selected, the theme value will be used as the variable value.

T:1

Does not use the theme value as the variable value, even if a theme is selected.

T:4

If the specified theme is selected, both the theme value and the attribute will be used by the variable. This option is mainly used on Origin internal objects, such as XYRange, Image, etc.

X-Function, Set Output as OptionalU - Specifying Output as Optional

Specifies whether the output variable is needed. This option string is only available for X-Functions with multiple output variables.

U:1

Adds a selected check box for the output variable. This is the default option.

U:0

Adds an unselected check box for the output variable.

U:n

Adds no check box for the output variable.

Example

1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Click the Edit X-Function in Code Builder button to open this X-Function in Code Builder. Copy the following code into the body of the main function, OptionStringU.

   vector vv;
   vv.Data(1,10,1);
   
   if( xx ) // to check if output xx variable
   {
   	xx = vv;		
   }
   
   if( yy ) // to check if output yy variable
   {
   	yy = vv;
   }
   
   zz = vv;

3. Put the following code into the OptionStringU_event1 function, which will get the check box status of the output variables. Then click the Compile button .

   foreach(TreeNode subnode in trGetN.Children)
   {
   	string strVarName = subnode.tagName;
   	int nUStatus, nOutput;
   	
   	// to check if is output variable
   	if((subnode.GetAttribute(STR_XF_VAR_IO_ATTRIB, nOutput) 
   		&& IO_OUTPUT == nOutput)) 
   	{
   		// check Output check box status
   		if(subnode.GetAttribute(STR_ATTRIB_DYNACONTROL_USE_CHECK, nUStatus))
   		{
   			switch(nUStatus)
   			{
   			case 1:
   				printf("%s variable has Output checked check box.\n"
   		, strVarName);
   				break;
   			case 0:
   				printf("%s variable has Output unchecked check box.\n"
   		, strVarName);
   				break;
   			}
   		}	
   		else
   		{
   			printf("%s variable NOT Output check box.\n", strVarName);
   		}	
   	}
   }

4. Run OptionStringU -d; in the Command window, keep the default settings of the dialog, and click the OK button. This will create a new worksheet with two columns, and the check box status of each output variable will be printed in the Command window.

X-Function, Set Control as InvisibleV - Specifying Control to be Invisible

Specifies whether a variable is visible or not in the X-Function dialog.

V:0

The variable will be invisible in the dialog.

V:1

The variable will be visible in the dialog.

V:2

The variable will be invisible when using Labtalk script.

X-Function, Editable/Disable ControlX-Function, Branch Check BoxZ - Adding Check Box to Set Editable or Disable for Variable Control

Adds a check box beside an input variable to specify whether it is editable or not. The syntax is Z:State|Label|Behavior.

• State: 0 or 1, to specify the status of the check box.
• Label: label for the check box. If both Label and Behavior are unspecified, the label is Auto by default.
• Behavior:

  0, the variable is always editable, no matter whether the check box is checked or not.

  1, if checked, the input variable is disabled.

  2, if unchecked, the input variable is disabled.

Example

1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
   
2. Click the Edit X-Function in Code Builder button to open this X-Function in Code Builder. Copy the following code into the OptionStringZ_event1 function, which will get the check box status of the int Type variable. Then click the Compile button .

   TreeNode trInt = trGetN.nn;		
   int nAutoType = octree_get_auto_support(&trInt);
   switch(nAutoType)
   {
   case -1:
   	out_str("Auto check box of int Type control is unchecked");
   	break;
   case 0:
   	out_str("No auto check box for int Type control");
   	break;
   case 1:
   	out_str("Auto check box of int Type control is checked");
   	break;
   }

3. Run OptionString -d; in the Command window, and a dialog like the one in the image below will open. Change the status of the TestOK check box, and a message about the status of this check box will output in the Command window.