2.3.2.3 LabTalk ObjectsLT-objs
LabTalk ObjectLabTalk script programming provides access to various objects and their properties & methods. These objects include components of the Origin project that are visible in the graphical interface, such as worksheets columns and data plots in graphs. Such objects are referred to as Origin Objects, and are the subject of the next section, Origin Objects.
The collection of objects also includes other objects that are not visible in the interface, such as the INI object or the System object. The entire set of objects accessible from LabTalk script is found in Alphabetical Listing of Objects.
In general, every object has properties that describe it, and methods that operate on it. What those properties and methods are depend on the particular object. For instance, a data column will have different properties than a graph, and the operations you perform on each will be different as well. In either case, we need a general syntax for accessing an object's properties and calling it's methods. These are summarized below.
Also, because objects can be renamed, and objects of different scope may even share a name, object names can at times be ambiguous identifiers. For that reason, each object is assigned a unique universal identifier (UID) by Origin and functions are provided to go back and forth between an object's name and it's UID.
Properties
A propertyObject Property either sets or returns a number or a text string associated with an object with the following syntax:
- objName.property (For numeric properties)
objName.property$ (For text properties)
Where objName is the name of the object; property is a valid property for the type of object. When accessing text objects, you should add the $ symbol after property.
For example, you can set object properties in the following way:
// Set the number of columns on the active worksheet to 10
wks.ncols = 10;
// Rename the active worksheet 'MySheet'
wks.name$ = MySheet;
Or you can get property values:
pn$ = page.name$; // Get that active page name
layer.x.from = ; // Get and display the start value of the x-axis
Methods
MethodObject Methods are a form of immediate command. When executed, they carry out a function related to the object and return a value. Object methods use the following syntax:
- objName.method(arguments)
Where objName is the name of the object; method is a valid method for the type of object; and arguments determine how the method functions. Some arguments are optional and some methods do not require any arguments. However, the parentheses "()" must be included in every object method statement, even if their contents are empty.
For example, the following code uses the section method of the run object to call the Main section within a script named computeCircle, and passes it three arguments:
double RR = 4.5;
string PA$ = "Perimeter and Area";
run.section(computeCircle, Main, PA$ 3.14 R);
Object Name and Universal Identifier (UID)
Each object has a short name, a long name, and most objects also have a universal identifier (UID). Both the short name and long name can be changed, but an object's UID will stay the same within a project (also known as an OPJ file). An object's UID can change if you append one project to another one, at which time all object UID's will go through a refresh process to ensure the uniquness of each object in the newly combined project.
Since many LabTalk functions require the name of an object as argument, and since an object can be renamed, the following functions are provided to convert between the two:
- nVal = range2uid(rangeName$)
- str$ = uid2name(nVal)$
- str$ = uid2range(nVal)$
A related function is NameOf(range$) with the general syntax:
- str$ = nameof(rangeName$)
Its use is demonstrated in the following example:
// Establish a range variable for column 1 (in Book1, Sheet1)
range ra=[Book1]1!1;
// Get the internal name associated with that range
string na$ = NameOf(ra)$;
// na$ will be 'Book1_A'
na$ =;
// Get the UID given the internal name
int nDataSetUID = range2uid(na$);
Besides a range name, the UID can be recovered from the names of columns, sheets, or books themselves:
// Return the UID of column 2
int nColUID = range2uid(col(2));
// Return the UID of a sheet or layer
int nLayerUID = range2uid([book2]Sheet3!);
// Return the UID of the active sheet or layer
nLayerUID =range2uid(!);
// Return the UID of sheet3 of the active workbook
nLayerUID =range2uid(sheet3!);
// Return the UID of the column with index 'jj' within a specific sheet
nColUID = range2uid([Book1]sheet2!wcol(jj));
Additionally, the range2uid function works with the system variable %C, which holds the name of the active data plot or data column:
// Return the UID of the active data plot or selected column
nDataSetUID = range2uid(%C);
Getting Page and Layer from a Range Variable
Given a range variable, you can get its corresponding Page and Layer UID. The following code shows how to make a hidden plot from XY data in the current sheet and to obtain the hidden plot's graph page name:
plotxy (1,2) hide:=1; // plot A(x)B(y) to a new hidden plot
range aa=plotxy.ogl$;
int uid=aa.GetPage();
string str$=uid2Name(uid)$;
type "Resulting graph name is %(str$)";
Getting Book And Sheet from a Plot
You can also get a data plot's related workbook and worksheet as range variables. The following code (requires Origin 8 SR2) shows how to get the Active plot (%C) as a column range and then retrieve from it the corresponding worksheet and book variables allowing complete access to the plot data:
// col range for active plot, -w switch default to get the Y column
range -w aa=%C;
// wks range for the sheet the column belongs to
range ss = uid2range(aa.GetLayer())$;
// show sheet name
ss.name$=;
// book range from that col
range bb = uid2range(aa.GetPage())$;
// show book name
bb.name$=;
There is also a simpler way to directly use the range string return from GetLayer and GetPage in string form:
// col range for active plot, -w switch default to get the Y column
range -w aa=%C;
// sheet range string for the sheet the column belongs to
range ss = aa.GetLayer()$;
// show sheet name
ss.name$=;
// book range string from that col
range bb = aa.GetPage()$;
// show book name
bb.name$=;
When you create a range mapped to a page, the range variable has the properties of a PAGE (Object).
When you create a range mapped to a graph layer, the range variable has the properties of a LAYER (Object).
When you create a range mapped to a workbook layer (a worksheet or matrixsheet), the range variable has the properties of a WKS (Object).
|