2.9.4 Creating and Accessing Graphical Objects

Creating-and-Accessing-Graphical-objs

Graphical Objects could be many types, Line, Polyline, Rectangle, Cycle, Polygon, Arrow, Text, Image, etc. Once an object is created and attached to a layer, you can see it by invoking the list -o command option. The following section shows you how to create, change, and delete an object by LabTalk.

Creating Objects

Creating Labels

A label is one type of graphic object and can be created using the Label command. If no name is specified when creating labels by the label -n command, Origin will name the labels automatically with "Textn", where n is the creation index.

When creating labels, you can use escape sequences in a string to customize the text display. These sequences begin with the backslash character (\). Enter the following script to see how these escape sequences work. When there are spaces or multiple lines in your label text, quote the text with a double quote mark.

label "You can use \b(Bold Text)
Subscripts and Superscripts like X\=(\i(i), 2) 
\i(Italic Text) 
\ab(Text with Overbar) 
or \c4(Color Text) in your Labels";

The following script creates a new text label on your active graph window with the value from column 1, row 5 of sheet1 in book3. It works for both string and numeric.

label -s %([book3]Sheet1,1,5);

The following script creates a new text label on your active graph window from the value in row 1 of column 2 of sheet2 in book1. Note the difference from the above example - the cell(i,j) function takes row number as first argument. It works for a numeric cell only.

label -s $([book1]Sheet2!cell(1,2));

Besides, you can address worksheet cell values as your label contents. The following script creates a new text label on your active graph window from the value in row 1 of column 2 of sheet2 in book1. The value is displayed with 4 significant digits.

label -s $([book1]Sheet2!cell(1,2), *4);

The %( ) notation does not allow formatting and displays the value with full precision. You need to use $( ) notation if you wish to format the numeric value.

Creating Legends

A graph legendGraph Legend is just a text label with the object name Legend. It has properties common to all graphical objects. To output a list of all properties of the legend, type the following into the Script Window and press Enter:

legend.=

To view the object name of any graphical object right-click on it and select Properties from the context menu; then click on the Programming tab and look to the Name field.

To update or reconstruct the graph legend, use the legendupdate X-function, which has the following syntax:

legendupdate [mode:=optionName]

The square brackets indicate that mode is optional, such that legendupdate may be used on its own, as in:

legendupdate;

which will use the default legend setting (short name) or use mode to specify what you would like displayed:

legendupdate mode:=0;

which will display the Comment field in the regenerated legend for the column of data plotted. All possible modes can be found in Help: X-Functions: legendupdate:

Note that either the index or the name of the mode may be used in the X-function call, such that the script lines,

legendupdate mode:=comment;
legendupdate mode:=0;

are equivalent and produce the same result.

The custom legend option requires an additional argument, demonstrated here:

legendupdate mode:=custom custom:=@WS;

All available custom legend options are given in the Legend_Text_Customization.

The following example shows how to use these functions and commands to update legends.

// Import sample data;
newbook;
string fn$ = system.path.program$ +
	"Samples\Curve Fitting\Enzyme.dat";
impasc fname:=fn$;
string bn$ = %H;
// Create a two panels graph
newpanel 1 2;
// Add dataplot to layers
for (ii=1; ii<=2; ii++)
{
	plotxy iy:=[bn$]1!wcol(ii+1) plot:=201 ogl:=$(ii);
}
// Upate whole page legends by worksheet comment + unit
legendupdate dest:=0 update:=0 mode:=custom custom:=@ln;
// Modify the legend settings for each layers
doc -e LW {
	// Set legend font size
	legend.fsize = 28;
	// Set legend font color
	legend.color = color(blue);
	// Move legend to upper-left of the layer
	legend.x = layer.x.from + legend.dx / 2;
	legend.y = layer.y.to - legend.dy / 2;
};

Note: To modify the text of the legend, you can also use the label command. One reason to use this would be if you wanted to display more than one text entry for each dataplot. The script below will update the legend text to display both the worksheet name and the X column's Comment:

label -sl -n legend "\l(1) %(1, @WS) %(1X, @LC)";

Creating Lines

Objects like lines, rectangles, are graphic objects, and you can use draw command to create them.

In the example below, you can see how to use the -l and -v switches to draw a Vertical Line. The line will be drawn at the midpoint of the X axis, where X1 and X2 are system variables that store the X From and X To scale values respectively.

draw -l -v (X1+(X2-X1)/2);

To make the line movable, use the -lm switch.

draw -lm -v (X1+(X2-X1)/2);

Working on Objects

Position of Objects

Object position can either be controlled when creating it, or changed by object properties. The following table lists how these properties and commmands works:

For example:

win -T Plot; // Create an empty graph
// Create a text object at the layer center,
//  named as "MyText", and the context is "Hello World"
label -p 50 50 -n MyText Hello World;
sec -p 1;
// Place the label at (1, 5)
MyText.x1 = 1;
MyText.y1 = 5;

Change Object Properties

All graphical objects can use objectName.property= to get or set object properties. Take label as example, the object.x and object.y properties specify the x and y position of the center of an object, and object.dx and object.dy specify the object width and height. These four properties are all using axis units, so we can combine these four properties with layer.axis.from and layer.axis.to to place the label in the proper position on a layer.

The following script example shows how to use label properties to place labels.

// Import sample data
newbook;
string fname$ = system.path.program$ +
	"Samples\Curve Fitting\Enzyme.dat";
impasc;
string bn$ = %H;
plotxy ((,2), (,3));
// Create a label and name it "title"
// Be note the sequence of option list, -n should be the last option
// -j is used to center the text
// -s enables the substitution notation
// -sa enables conversion of \n (new line)
// Subsitution is used to get text from column comments
label -j 1 -s -sa -n title
  Enzyme Reaction Velocity\n%([bn$]1!col(2)[c]$) vs. %([bn$]1!col(3)[c]$);
// Set font
title.font=font(Times New Roman);
// Set label font size
title.fsize = 28;
// Set label font color
title.color = color(blue);
// Placing label
title.x = layer.x.from + (layer.x.to - layer.x.from) / 2;
title.y = layer.y.to + title.dy / 2;
// Placing legend
legend.y = layer.y.from + (layer.y.to - layer.y.from) / 2;
legend.x = layer.x.to - legend.dx / 2;

Customize special text objects

Origin has some special text objects, the name of which have already been pre-specified in system, are also positioned on a graph layer, such as axis titles below:

For these special objects, you can also run objectName.property= to get or set its property.

xb.fsize = 20; //set the font size of bottom X axis title.

yl.fillcolor=2; //Add a box frame to left Y axis title and set the fill color to red.
yl.transparency=50;//set the transparency to 50%.

You can set a proper integer value to fill the axis title frame with a different built-in color.

Deleting an Object

To delete objects, use the label command with -r, -ra, and -rc switches: