2.1 Getting Started with LabTalk

Contents

Hello World

We begin with a classic example to show you how to execute LabTalk script. We use LabTalk command type in the example. Please note that Origin's LabTalk commands are case insensitive.

  1. Open Origin, and from the Window menu, select the Script Window option. The Script Window will open.
  2. In this window, type the following text and then press Enter: 
    type "Hello World"
  3. Origin adds a semicolon, ;, at the end of the line and also executes that line of script.
  4. This line of script outputs Hello World directly beneath your command.
  5. To run this line of script again, place the cursor anywhere before ; on the line and press Enter.


Commands can be abbreviated as long as it's unique. Both the following work. 

typ "Hello Word"
ty "Hello World"


Now let us see how to execute multiple lines of script from the script window:

  1. Make a workbook window active since the following script outputs workbook information.
  2. In Script Window window, paste the following lines of script separated by ; 
    type "The current workbook is %h";
type "This book has $(page.nlayers) sheet(s)";
type "There are $(wks.ncols) columns in the active sheet";
  3. Highlight all lines (if using mouse, drag and select all lines of script, or if using keyboard, put cursor at either the beginning or the end of the script, hold Shift key and press up/down arrow keys to select all lines of script).
  4. Press Enter to execute all selected lines of script.
  5. It will output the current workbook name, how many number of sheets in book, and how many columns in active sheet similar to the following text: 
    The current workbook is Book1
This book has 1 sheet(s)
There are 2 columns in the active sheet

In the above example, we used the %H String Register that holds the currently active window name (which could be a workbook, a matrix, or a graph). We then used the page and wks LabTalk Objects to get the number of sheets in the book and the number of columns in the sheet. The $() is a substitution notations which tells Origin to evaluate the expression within the () and return its value.

When typing multiple lines of script in the Script Window yourself,

  1. Add ; and then press Enter key to avoid execution of the line. Origin will just start a new line for you to continue the typing. At the end, select all lines and press Enter to execute them together.
  2. Or uncheck Edit: Script Execution. Type in the lines to avoid executing any lines by mistake. At the end, check Edit: Script Execution. Select all lines and press Enter to execute them together.

Using = to Get Quick Output

The = character is typically used as an assignment operator, with a left- and right-hand side. When the right-hand side is missing, the interpreter will evaluate the expression on the left of the = character and print the result in the script window.

Evaluation math expression on left and print result interactively. 

3 + 5 =

Origin computes the result and displays it in the next line: 

3 + 5 = 8

Output string register and Origin object properties 

 
%H =; //current window name
wks.ncols=; //number of columns
wks.col1.name$=; //1st column's short name

Suppose the current window is Book1 with 1 sheet and 2 columns, executing the above script will output 

Book1
wks.ncols=2
A

In the following example, we introduce the concept of variables in LabTalk. Variable names are case insensitive. Entering the following assignment statement in the script window: 

double A = 2

creates a variable A and initializes its value to 2. Then you can perform some arithmetic on variable A, such as multiplying by PI (a constant defined in Origin, \;\pi) and assign the result back to A: 

A = A*PI

To display the current value of A, type: 

A =

Press Enter and Origin responds with: 

A = 6.2831853071796

There is List command to view a list of variables and their values. Type the following command and press Enter: 

list

Origin will open the LabTalk Variables and Functions dialog that lists all variables.

You can also get a dump of a specific type of variables, for example 

list v

to list the numeric variables.

Simple Useful Commands

Worksheet

newbook; //create a workbook
wks.ncols=3; //set worksheet has 3 columns
col(B)=2*col(A); //set col(B)'s value by col(A)

Graph

//select a Y column firstly
plotxy; //use the selected Y column and its X column to plot
layer.x.from=5; //set X axis from value

Other Ways to Execute Script

In previous examples, you saw how to execute script from the Script Window. Origin provides several other ways to organize and execute LabTalk script. These are outlined in detail in the Running and Debugging LabTalk Scripts chapter. Here we take a quick look at a few of the methods to execute script: (1) from the Custom Routine toolbar button, (2) from a custom menu item, and (3) from a button in a graph page.

Custom Routine Button

Origin provides a convenient way to save script and run it with the push of a toolbar button.

  1. While holding down Ctrl+Shift on your keyboard, press the Custom Routine button ( Button Custom Routine.png ) located in the Standard Toolbar.
  2. This opens Code Builder, Origin's native script editor. The file being edited is called Custom.ogs. The code has one section, [Main], and contains one line of script: 
    [Main]
type -b $General.Userbutton;

    Replace that line with the following: 

    [Main]
type -b "Hello World";
    Then press the Save ( Button Save Project.png ) button in the Code Builder window.
  3. Now go back to the Origin application window and click the Button Custom Routine.png button (keyboard shortcut: ALT + F5).

Origin will again output the text Hello World, but this time, because of the -b switch used with the type command, the text will be presented in a pop-up window.

Custom Menu Item

LabTalk script can be executed from a custom menu item.

  1. Select the menu item Preferences: Custom Menu Organizer... to open the Custom Menu Organizer dialog.
  2. Make the Add Custom Menu tab active. Then right-click inside the left panel and select New Main Popup from the context menu.
  3. In the right panel, enter a name for Popup Text, such as My Menu. then click outside of the edit box.
  4. Select My Menu from the left panel, and then right click on it, and select Add Item from the context menu.
  5. In the right panel, change the Item Text to Hello World, then add the following script to the LabTalk Script text box: 
    6. type -b "Hello World";
  6. Click the Close button, and in the window that pops up, press Yes to save the menu changes as Default menu. In the file dialog that opens, press Save to save the file with the default name to the default folder (User Files Folder).
  7. A new menu named My Menu should now appear in the menu bar, to the left of the Window menu. Click on this new menu item, and then click on the Hello World entry in the drop-down. A Hello World dialog will pop up.

Button in a Graph

Origin also provides the ability to add a button to a graph or worksheet, and then execute LabTalk script by pushing that button. This allows for script to be saved with a specific project or window.

  1. Press the New Graph button ( Button New Graph.png ) located in the Standard Toolbar to create a new graph.
  2. Press the Text Tool button ( Button Text Tool.png ) in the Tools Toolbar, and then click on the newly created graph and type the text My Button. Then click outside the text to finish editing the text.
  3. Right click on the text to bring up the context menu, and then select Programming Control to open the Programming Control dialog.
  4. In the dialog, select Button Up from the Script, Run After: drop-down list, and then type the following script in the edit box: 
    5. type -b "Hello World";
  5. Click OK to close the dialog. Now the text label becomes a button. Click the button. A Hello World dialog will pop up.

Script Example

We now present a script example that walks you through a particular scenario of importing and processing data, and then saving the project. This example uses several LabTalk language features such as Commands, Objects, and X-Functions. You will learn more details about these language features in subsequent chapters.

NOTE: We will use the Script Window to execute these statements. To execute a single line of code, make sure that you leave out the ; at the end before pressing Enter. For multiple lines of code, at the end of each line, press Enter after the ; to continue entering the next line. After you have typed in all lines, select them all and then press Enter to execute.

Let's start with a new project using the doc command and the -n switch. If the current project needs saving, this command will prompt user to save. 

doc -n

Now let's import a data file from the Samples folder. We will first use the dlgfile X-function to locate the desired file: 

dlgfile gr:=ASCII

Then select the file S15-125-03.dat from the \Samples\Import and Export sub folder located in your Origin installation folder, and click Open.

The above process will load the file path and name into a variable named fname$. You can examine the value of this variable by typing: 

fname$=

Now let's import this files into the active workbook. We will use the impasc X-Function with options to control naming, so that the file name does not get assigned to the workbook: 

impasc Options.Names.FNameToBk:=0

Now we want to perform some data processing of the Position column. We first define a range variable to point to this column.: 

range rpos = "Position"

Since the column we select is also the 4th column in the current worksheet, we can also use index number to specify it. 

range rpos = 4

You can check what range variables are currently defined, using this command: 

list a

We now normalize the column so that the values go from 0 to 100. To check what X-Functions are available for normalization, we can use the command: 

lx *norm*

The above command will dump X-Functions where the name contains norm. There are several X-Functions for normalizing data. For our current purpose we will use the rnormalize X-Function.

To get help on the syntax for this particular X-Function, you can type: 

rnormalize -h

to dump the information, or type: 

help rnormalize

to open the help file.

Let us now normalize the position column: 

rnormalize irng:=rpos method:=range100 orng:=<input>

The normalized data will be placed in the same column, replacing the original data, as we set the output range variable orng to be <input>.

When using X-Functions, you can leave out the variable names, if they are specified in the correct order. The above line of code can therefore be written as: 

rnormalize rpos range100 orng:=<input>

The reason we still specified the name orng is because there are other variables that precede this particular variable, which are not relevant to our current calculation and were therefore not included in the command.


Now let's do some changes to the folder in the project. There are several X-Functions for managing project folders, and we will use some of them: 

// Get the name of the current worksheet
string name$ = wks.name$;
// go to root folder
pe_cd ..;
// rename Folder1 to be the same as worksheet
pe_rename Folder1 name$;

Now let's list all the sub folders and workbooks under the root folder: 

pe_dir

Finally, let's save the Origin Project to the User Files Folder. The location of the user files folder is stored in the string register %Y. You can examine where your User Files Folder is by checking this variable: 

%Y =

Now let's use the save command to save our project to User Files Folder, with the name MyProject.opj. 

save %yMyProject

In the above command %Y will be replaced with the User Files Folder path, and thus our project will be saved in the correct location.

Using CTRL + SHIFT to capture Menu Command and Toolbar Button Script

Many of the actions of menu commands and toolbar buttons in Origin's graphical user interface (GUI) are implemented in LabTalk script. When this is the case, you can locate and view this script in the following way:

  1. Press CTRL + SHIFT on your keyboard and hold.
  2. Click on the menu command or toolbar button.

This, then, becomes a source of usable LabTalk Script that you can incorporate into your custom routines.

Origin 2024b support CTRL + SHIFT to capture Mini Toolbar Button Script

Example

  1. Open a new workbook, select columns A and B, then right-click and choose Fill Columns With: Row Numbers.
  2. With your worksheet active, press CTRL + SHIFT and click the Scatter toolbar button Button Scatter.png (or choose Plot > 2D: Scatter: Scatter).

This does two things: 

Menu id=33248 (0x81e0)
run.section(Plot,Scatter)

Information from both of these lines of script can be reused in your own scripts, to create a line plot. To see this at work, make sure that the workbook with your two columns of highlighted row numbers is still active, then go to the Script Window (Window: Script Window), type either of the following, then press Enter: 

menu -e 33248
run.section(Plot, Scatter)


For more information, see these topics:

Where to Go from Here?

The answer to this question is the subject of the rest of the LabTalk Scripting Guide. The examples above only scratch the surface, but have hopefully provided enough information for you to get a quick start and excited to learn more. The next chapter lists various resources available for learning LabTalk.