5.4 Objects in LabTalk

Tutorial-objs

Summary

LabTalk script programming provides access to various object properties and methods.

The syntax to access an object property is:

objName.property(for numeric properties)

or

objName.property$(for text properties)

While the syntax to operate a method is:

objName.method(arguments)

Objects may share some general properties or methods, but each object usually has its own unique properties and methods. Refer to the complete list of objects for details about a specific object.

Many objects are visible components of an Origin project such as Workbooks, Worksheets, Worksheet Column or a Dataplot in a graph. The correspondence between some Origin object and their OPJ component is listed below:

Other objects are not visible in the interface, such as the INI object or the System object.

What Will You Learn

This tutorial will show you how to:

• Get a property value from an object
• Change the property value for an object
• Use a method to operate an object
• Create and manipulate a Graphic Object

Steps

Read and Write Object Properties

Returning a Property Value

1. Open Origin and make sure the Script Window is open. (If not, click Window:Script Window or Shift + Alt + 3 to open)
2. Click the button in the Standard toolbar to create a new workbook, right click its title bar and choose Properties to open the Window Properties window.
3. Change its Long Name to be For Testing and Short Name to be Test, click OK to apply setting and close this dialog.
4. Make sure the workbook window of Test is active, and run the following script in the script window:

//Read the property value(short name) in script window
page.name$ = ;
//Assign the text property value(long name) to a string variable
string str1$ = page.longname$ ;
//Assign the numeric property value(page width) to a double variable
double width = page.width;

5. You can see that the workbook short name - Test - is output to the Script Window. The remaining properties have been read into variables and may be output by executing the following script:

str1$ = ;//It should return "For Testing" in Script Window
width = ;//It should return the numeric value of page width

Set a Property Value

1. Activate the workbook Test, we will use the wks object to modify the worksheet name by passing a string to the property:

wks.name$ = "Test1";//The worksheet name will be changed to Test1

Note: in this case, you can also use the layer object to change the worksheet name.

2. Set the number of columns in this worksheet to be 5.

wks.nCols = 5;

3. Use the wks.col object to modify the worksheet column properties.

// Set the Column 2 Long Name using page Long Name
wks.col2.lname$ = page.longname$;
// Make column 2 wider
wks.col2.width = 12;
// Set Column 3 to be an Error Bar column
wks.col3.type = 3;

Define a Range as an Object and Use its Properties

As mentioned in the summary section, Origin Objects are visible in the graphical interface and primary components of the Origin project file (OPJ).

Generally, the active component will be used by default if nothing is specified, if you want to manipulate an inactive component, either specify their name/index, or define a range and map the range to this component.

1. Click File:Open Sample Projects:2D and Contour Graphs to open the sample project and in Project Explorer navigate to the /Multi Axis and Multi Panel/3Ys Y-YY/ folder, activate the 3Ys Y-YY graph window, make sure layer 3 is active (by default).
2. Run the following script to change the dimension unit for active layer (layer3) to be Inch, instead of % of page.

layer.unit = 2;

3. Change the dimension unit for layer 2 to be inch as well, by specifying the graph window name (optional in this case as the graph window is activated) and layer index.

%(page.name$)!layer2.unit = 2;

Note: You can check whether the unit setting is correct by clicking Format:Layer to open the Plot Details - Layer Properties dialog, go to Size/Speed tab, the option of Units should be changed to Inch for both Layer 2 and Layer 3.

4. Define a range variable lay2 and map it to Layer 2.

range lay2 = [%(page.name$)]layer2!;

5. This range variable lay2 then holds all properties of Layer 2, run the following script to change its width to 5 inches, and fill its background with LT Gray:

lay2.width = 5;
lay2.color = color(LT Gray);
//or you can use color index to define the fill color
//for example the script below works the same as the previous one
//lay2.color = 19;

6. Use the property of page object to activate Layer 1

page.active = 1;

7. Map the current active layer (Layer 1) to another range variable lay1

range lay1 = !;

8. Use the layer.axis sub-object to change the y axis type of layer 1 to Linear

lay1.y.type = 1;

Use Method to Operate Object

1. In an empty Origin project file, click the button to create a new workbook.
2. Click the button to import the file Categorical_Data_1.dat under <Origin EXE Folder>\Samples\Graphing\ path.

Note: You can also run the following script to import the file.

//Create a new workbook
newbook;
//Import the file
string fn$=system.path.program$ + "Samples\Graphing\Categorical_Data_1.dat";
impASC fname:=fn$; 
//system.path.program$ is the property of a non-visible object.

3. Add a single column to the end of the worksheet with the name B2.

   page.xlcolname = 0; // Turn off Spreadsheet Cell Notation firstly
   wks.addcol(B2);

   For the Spreadsheet Cell Notation in the workbook, please see FAQ-849 for more information.

4. Insert a column A1 before column B.

   //Select column B as current column
   wks.col = 2;
   //Insert column A2 before current column
   wks.insert(A2);

5. Control the display of column label rows with the wks.labels( ) method.

//Remove row of Sparklines and Comments, only keep Long Name and Units
wks.labels(-CS);
//Or you can run the script below instead to get the same result
//wks.labels(LU);

6. Set the column long names and units if necessary.

//Set long name for column A2 and B2(the 4th column)
col(A2)[L]$ = "Abb. Direction";
col(4)[L]$ = "Description";
//Set units for column B
col(B)[U]$ = "km/h";

7. Adjust column width in order to display all texts in one row.

wks.col2.width = 10;
wks.col4.width = 17;

8. Use the methods for string array and put the strings of wind description into it.

//Define string arrays
StringArray aa, bb;
//Add a string to the string array aa
aa.Add("Strong gale");
//Copy the string array aa to bb
bb.Copy(aa);
//Append bb to aa
aa.Append(bb);
//Append the other four strings as dataset, use , as delimiter.
aa.Append("Strong breeze,Fresh breeze,Moderate gale,Moderate breeze", ",");

9. Copy the contents in the string array aa to column D

aa.CopyTo(col(4));

10. Use the method to manipulate strings in the first column and put the abbreviation to the second column. A for loop is used to simplify script.

for(int ii=1; ii<=wks.maxRows; ii++)
{
   string str1$ = col(1)[$(ii)]$;
   //Get the first letter from the left
   string str2$ = str1.Left(1)$;
   //Make str2 to be upper case
   str2.MakeUpper();
   col(2)[$(ii)]$ = str2$;
}

Note:You can also use the csetvalues x-function, or "Set Column Values" dialog to call the built-in string functions to achieve the same effect.

Create and Manipulate Graphic Objects

1. Create a new graph window and draw a line object.

//Create a graph window
win -t plot; 
//Declare a GObject named myLine attached to 'line1'
GObject myLine = line1;
//Now create the object (list -o shows 'line1') 
draw -n myLine -l {1,2,6,4};

2. Now you can use either myLine or line1 to control the object properties.

//Change the line color to be red
myLine.color = color(red);
//Change the arrow end shape
line1.arrowEndShape = 2;
//Enable move in both horizontal and vertical directions
line1.hMove = 1;
line1.vMove = 1;

3. Add a text label named as "myText" to the graph, displaying text "Distance". The label will be put to a specified position.

label -p 20 50 -n myText Distance;

4. Change the properties of the text label.

//Set the text label background to be Shadow
myText.background = 2;

5. Add a script to the text object, and let it run after redrawn.This script will update the text in label according to the calculated line length of the line1 object, and keep the offset with the line object.

//Pre-define a string in order not to use substitution notation
string str1$ = "$" + "(sqrt((line1.y2-line1.y)^2+(line1.x2-line1.x)^2), .2)";
//Make sure the script will run after all event
myText.script = 5;
//Add the script text to the object
myText.script$="myText.text$ = "Line Length = %(str1$)"; doc -uw;";

6. Right click on the line object and choose Programming Control, set Script, Run After to be Sized and type in the following script in the script edit box, so that every time the line object is re-sized(i.e. length changed), the text label will be redrawn:

myText.draw(global);

Note: similarly, you can run script to do this instead of using the Programming Control dialog, the script would be:

line1.script = 3;
line1.script$ = "myText.draw(global);";

7. Connect the myLine object and myText object:

line1.Connect(myText, 0, 1, 2, 6);

8. If you move the line object in the graph, the text label will move together and if you resize it, the text will also automatically update according to the new line length.