3.7.3.2 Graphic Objects

Graphic objects can be created by the Origin user and placed in an Origin child window. These objects include labels, arrows, lines, and other user-created graphic elements. These objects are accessed from script by their name, as defined on Programming tab of Object Properties dialog. In versions before Origin 2017, it's called Programming Control dialog box.

To open the dialog box, use one of these methods:

  • Click on the object to select it, then choose Format: Object Properties... menu. In versions before Origin 2017, it's called Format: Programming Control.
  • Right Click on the Object and select Properties.... Then go to Programming tab. In versions before Origin 2017, there is Programming Control context menu.
  • Alt+DoubleClick on the object.
Note: Objects can be set as not selectable. To access such objects you need to first check Edit: Edit Mode menu. In versions before Origin 2017, it was called Button Edit Mode.

Scripts can be attached to these labels by typing the script into the text box of the Programming tab of the dialog box. The Script execution trigger is set from the Script, Run After drop-down list.

In general, only named objects can be accessed from LabTalk script. However, an unnamed object can be accessed by a script from Programming tab of the dialog using this. notation, as described below.

GObject Variable Type

GObject is a LabTalk variable type to represent graphic objects in a layer. You can use Label -r objectName command to delete it.

The general syntax is:

GObject name = [GraphPageName]LayerName!ObjectName; // Use page name, layer name, object name

GObject name = [GraphPageName]LayerIndex!ObjectName; // Use page name, layer number, object name

GObject name = LayerName!ObjectName; // Active page, use layer name, object name

GObject name = LayerIndex!ObjectName; // Active page, use layer number, object name

GObject name = ObjectName; // Active page, active layer, use object name

You can declare GObject variables for both existing objects as well as for not-yet created object.

For example:

// Here we declare a GObject then create its Graphic Object.
win -t plot;          // Create a graph window

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

// Even though myLine is in a different graph that is not active, 
// You can still control it with the GObject name ...
myLine.X += 2; // Move the line

label -r myLine; //Delete the object 

// More often the Graphic Object exists already
GObject leg = legend; // Attach to the legend object
leg.fsize = 28; // Set font size to 28
leg.color = color(blue); // Set text color to blue
leg.background = 0; // Turn off the surrounding box

Note: A list o with the original graph active will show line1 which is the physical object name, but will not show myLine which is a programming construct.

Properties

The generic properties of these objects are listed below. Not all properties apply to all objects. For example, the text property does not apply to a Line object.

Syntax

[winName!]objName.property = value;

or

this.property = value;

  • WinName! is required if a Graphic Object exists in a non-active page. It specifies the window that the named object resides in. The layer the object resides in must be the active layer of that page. When using a declared GObject, WinName is never needed.
  • objName is the object's name, as shown in the Object Name text box in the Object Properties dialog box or the name of a declared GObject variable.
  • Property is one of the available objName properties.
Run objectName.= to see almost all properties of the object.

General Properties

Property Access Description
align Read/Write
Numeric
Only applicable for 2D graph legend object (Object name = Legend). It controls whether to align each column when dragging legend entries into multiple columns. 0 = Do not align, 1 = Align legend entries for each column. (Origin 2015 SR0)
ANCHOR Read/Write
Numeric
Text Anchor option in Position tab of Annotation properties dialog. 0 = auto, 1 = Left-Top,..etc
ANCHORONTEXTFRAME Read/Write
Numeric
Anchor on Text Frame checkbox in Position tab of Annotation properties dialog.
ANCHORX Read/Write
Numeric
Access Annotations Dataplot Anchor X Coord
ANCHORY Read/Write
Numeric
Access Annotations Dataplot Anchor Y Coord
arrowBeginLength Read/Write
Numeric
Length of beginning arrow heads in point size.
arrowBeginShape Read/Write
Numeric
Shape of beginning arrow heads by position in drop down list, Object Control dialog box: 0 = none, 1 = filled, 2 = chevron, etc.
arrowBeginWidth Read/Write
Numeric
Width of beginning arrow heads in point size.
arrowEndLength Read/Write
Numeric
Length of end arrow heads in point size.
arrowEndShape Read/Write
Numeric
Shape of end arrow heads by position in drop down list, Object Control dialog box: 0 = none, 1 = filled, 2 = chevron, etc.
arrowEndWidth Read/Write
Numeric
Width of end arrow heads in point size.
arrowPosition Read/Write
Numeric
Controls the display of arrow heads for each line segment of polyline and freehand objects:

0 = no arrow heads.
1 = arrow at beginning of each segment.
2 = arrow at end of each segment.
3 = arrow at both ends of each segment.

Note: arrowBeginShape and arrowEndShape must also be set.

attach Read/Write
Numeric
Attach to method:

0 = layer
1 = page
2 = axes scales

attach$ Read Only
String
Page name if the object attaches to page. Otherwise, returns layer name in format [PageName]LayerName!
Origin 8.5 SR0
auto Read/Write
Numeric
Redraw automatically after property changes: 0 = disable, 1 = enable.
background Read/Write
Numeric
Control the background of an object as follows: 0 = no background, 1 = black line, 2 = shadow, 3 = dark marble, 4 = white out, and 5 = black out.
borderColor Read/Write
Numeric
Object border color which be written or read as the color index from LabTalk List of Colors. Alternately, use the Color function to assign color to the object (e.g. text.bordercolor=color("#2F1BE3")) using names (LT List of Colors only), HTML color codes or RGB values.
box Read/Write
Numeric
Wrapped text box width. This is only available when the graphic object is a text object.
_title.box=80 //set title box width to 80% of layer width. 
_title.box=1 //Powerpoint/Word like text box but can drag the handles around box to resize it.  
_title.box=0 //old text object. The size of text box can’t be very precise, It will be decided by wrap result.
clip Read/Write
Numeric
Determine whether display of graphic objects associated with the layer should follow the layer's Clip Data to Frame setting: 0 (default) = do not clip objects to layer frame, 1 = follow layer Clip Data to Frame setting and clip (hide) objects that lie outside the layer frame if data clipping is enabled.
color Read/Write
Numeric
Line, text, or outline color index number. Use the Color function, as in name.color=color(red);'
crop$ Read/Write
String
clip Image object on graph

gr.Crop$=left top right bottom

dx
dy
Read/Write
Numeric
Width and height in axes units.
direction Read/Write
Numeric
Control how to stretch/span the graphic object line in horizontal/vertical direction:

0 = None
1 = Horizontal
2 = Vertical
3 = No corners
4 = Corners only
5 = Horizontal Span All Layers
6 = Vertical Span All Layers
7 = Horizontal Span Whole Page
8 = Vertical Span Whole Page
9 = Horizontal Span Whole Layer
10 = Vertical Span Whole Layer

enable Read/Write
Numeric
Enable hotspots on the object: 0 = disable, 1 = enable.
event Read Only
Numeric
Actions that trigger an object's script execution: 0 = None; 1 = Button Up; 2 = Moved; 3 = Sized; 4 = Moved or Sized; 5 = Redrawn, 6 = Real-Time; 7 = Window Create; 8 = Window Close; 9 = Window Activate; 10 = Window Deactivate; 11 = New Selection; 12 = Before Save; 13 = Axes Rescale; 14 = All Events; 15 = Mask Change; 16 = Data Change.
fillColor Read/Write
Numeric
Object fill color which be written or read as the color index from LabTalk List of Colors. Alternately, use the Color function to assign color to the object (e.g. text.bordercolor=color("#2F1BE3")) using names (LT List of Colors only), HTML color codes or RGB values.
font Read/Write
Numeric
Text label font index number. Use the Font function, as in name.font = font(arial);'
fSize Read/Write
Numeric
Text label font size.
getXY Read only
Numeric
Copy xy values from object to dataset.
height Read Only
Numeric
Height in layer coordinate units.
hGap Read/Write
Numeric
Only applicable to 2D graph legend object (Object name = Legend). It specifies the horizontal gap between each legend entry column in percentage of font height. (Origin 2015 SR0)
hMove Read/Write
Numeric
Horizontal movement: 0 = disable, 1 = enable.
index Read Only
Numeric
Only applicable for objects composed of multiple items, such as the UIM objects. Indicates which item in an object has been affected by a Windows action.
keepInside Read/Write
Numeric
Restrict object's movement to within the layer frame: 0 = disable, 1 = enable.
left Read/Write
Numeric
Left location of the object in physical coordinates.
lineType Read/Write
Numeric
Line and arrow object line type: 1 = solid, 2 = dash, and 3 = dot.
lineWidth Read/Write
Numeric
Line or arrow object line width.
link Read/Write
Numeric
The substitution level: 0 = no link, 1 = Link and resolve recursively, 2 = Link and resolve only first level and 3 = Link and resolve up to two levels. (Origin 2015 SR1)
margin.unit Read/Write
Numeric
This is only available when the graphic object is a text object. It specifies the unit to define the margin between the text and its borders: 1 = in percent of font height (Default); 0 = in percent of whole text height.(Origin 2015 SR0)
margin.left
margin.right
margin.top
margin.bottom
Read/Write
Numeric
These are only available when the graphic object is a text object. It specifies the left/right/top/bottom margin between the text and its borders. The value is in percentage of the text margin unit, and the unit is defined by margin.unit property. (Origin 2015 SR0)
mouse Read/Write
Numeric
Mouse access to the object: 0 = disable, 1 = enable.
name$ Write Only
String
Object name.
order Read/Write
Numeric

Graphic object drawing order.

0x000F mask: 0 = all plots, 1 = plot group, 2 = individual plot, 3 = ref lines
0x00F0 mask: index (0-offset), only for plot group and individual plots cases
0x0100 = before, if not set, then it is after

Example:

Rect.order=hex(42)

The rectangle will be drawn after the fifth dataplot: digit 4 is 0-offset dataplot index (which means it is the 5th dataplot), digit 2 at the end means individual dataplots.

Rect.order=hex(111)

The rectangle will be drawn before the second group plot: first digit 1 means before, second digit 1 is 0-offset index, the third digit 1 means plot group (which gives the meaning to the index: it is the index of the group).

Rect.order=hex(003)

The rectangle will be drawn after the reference lines. The first digit 0 (can be omitted) means after, the second digit 0 is not used (because the third digit is 3), the digit 3 at the end means reference lines.

pageRect$ Read/Write
String
Get/set RECT position in Units (e.g. pixel).
path$ Read/Write
String
Available for Image object inserted to graph layer only. Return the path of the image source, no matter inserted from local disk or web.

e.g. svg.path$=; to get the SVG image object's path.

pointCount Read/Write
Numeric
Number of points of a poly object (polygon, polyline).
realTime Read/Write
Numeric
Real-time update of substitution notation in a text label message: 0 = disable, 1 = enable.
revVideo Read/Write
Numeric
Reverse video display: 0 = disable, 1 = enable.
roi Read/Write
Numeric
Whether the object is ROI or not: 0 = not ROI, 1 = ROI. (Origin 2022)
rotate Read/Write
Numeric
Text label and SVG image object rotation in degrees.
savedata Read/Write
Numeric
Available for image object inserted to graph layer only. Get/Set the image object to be "linked".

0 = Link file
1 = Image is saved to the project.

script Read/Write
Numeric
Script, Run After mode index number, from the drop-down list in the Label Control dialog box.
setXY Write only
Numeric
Copy xy values from dataset to object.
show Read/Write
Numeric
Object display: 1 = visible, 0 = hidden. Hidden objects are not selectable
shadowColor Read/Write
Numeric
Text object shadow color which be written or read as the color index from LabTalk List of Colors. Alternately, use the Color function to assign color to the object (e.g. text.bordercolor=color("#2F1BE3")) using names (LT List of Colors only), HTML color codes or RGB values.
shadowWidth Read/Write
Numeric
Text object shadow width in point size.
smartpos Read/Write
Numeric
For legend only. legend.smartpos = 1 to move the Legend to a best position, legend.smartpos will be reset to 0 after smart reposition.
states Read/Write
Numeric
Controls object edit states. The property is bit-oriented so that values can be added.

Example: polygon.states = 3, disables resizing and rotating for the object named polygon.

0 = all controls are enabled.
1 = resizing is disabled.
2 = rotating is disabled.
4 = skewing is disabled.
8 = moving individual points is disabled.
16 = in place editing is disabled.
32 = resize text label border disabled.
64 = horizontal movement is disabled.
128 = vertical movement is disabled.

tableStyle Read/Write*
Numeric
Control display of table header, frame and grids. Each can have only one selection (i.e you cannot set both = 0 and = 1; instead set = 2).

0 = Column Header
1 = Row Header
2 = Column and Row Header
3 = No Header

5 = Top&Bottom Frame
6 = Left&Right Frame
7 = Full Frame
8 = No Frame

10 = Header Separator
11 = All Grids
12 = No Grids

* Note that only header styles can be read. All (header, frame, grid) can be written. Values are not additive.

text$ Read/Write
String
Message displayed by a text label.
top Read/Write
Numeric
Top of the object in physical coordinates.
transparency Read/Write
Numeric
Set transparency of the object. Only available for rectangle, circle, polygon and region objects. (Origin 9.0 SR0)

rect.transparency = 50; // Set transparency to 50%

type Read Only
Numeric
Return the type of graphic object.(Origin 9.0 SR1)

0 = text
1 = rectangle
2 = arrow or line
3 = handle
5 = group
6 = string
7 = data

type$ Read Only
String
Return the type strings of graphic object.(Origin 2015 SR0)
vgap Read/Write
Numeric
Only applicable to 2D graph legend object (Object name = Legend). It specifies the vertical gap between each legend entry row in percentage of font height. (Origin 2015 SR0)
vMove Read/Write
Numeric
Vertical movement: 0 = disable, 1 = enable.
whiteout Read/Write
Numeric
Enable White Out for text objects: 0 = disable, 1 = enable.
width Read Only
Numeric
Width in layer coordinate units.
wrap Read/Write
Numeric
Enable wrapping of text upon resizing object: 0 = disable, 1 = enable (Origin 2015 SR0)
wrapwidth Read/Write
Numeric
Specify the wrapping width of text in object. Enabled only when wrap is set to be 1. (Origin 2015 SR0)
x
y
Read/Write
Numeric
Axes X Y coordinates of the center of the object.

Notes:

  1. To align another object with the current object, you can use the dx, dy, x and y of the current object to calculate the x and y of the object to be moved. (See an example below.)
  2. In fact, any graphic object has an invisible rectangle associated with it. X and Y are actually the center of the rectangle. In addition, they are in pixel units, so there might be some loss of precision when converted to scale units. If you want to know the axis position of a line object, it is better to use x#, y# instead of x, y.
x#
y#
Read/Write
Numeric
x# and y# are the axes position of the #th point of an object. Straight lines and Arrows have 2 points, rectangles and circles have 4 points and other objects may have many points.


loop(ii,1,4) {circle.x$(ii)=;circle.y$(ii)=;}

Examples

  • Position the legend in the upper left of a layer
legend.background = 1;
legend.y = layer1.y.to - legend.dy / 2;
legend.x = layer1.x.from + legend.dx / 2;
  • Change colors of a circle object named circle1
// First of all, create a circle object on a graph
// then rename it to "circle1" for the two lines script below
circle1.color = 1; // Black border
circle1.fillcolor = color(yellow); // Yellow fill
  • Obtain the source graph name of the floating graph object, this assumes the floating graph object is named as "bmp" and is in the active worksheet.
// bmp.type$ returns "Embedded Graph: [GraphName]"
// GraphName is the actual name of the source graph
// the following script can be used to retrieve GraphName from bmp.type$  
%A = %[%(bmp.type$), >18];
ty %[%A, %[%A]];//Should print out the value of GraphName

Note: Substring Notation is used to retrieve GraphName.

  • Copy xy coordinates of object "polyline" to worksheet.
polyline.getXY([Book1]1!A, [Book1]1!B);
  • Position object "Rect1" using coordinates from XY worksheet columns.
draw -n Rect1 -b; // draw object Rect1
Rect1.setXY(Book1_A, Book1_B); // assign coordinates in Book1_A(X), Book1_B(Y)
  • Clip image
win -t plot;
string strInitPath$=system.path.program$+"Samples\Image Processing and Analysis";
dlgfile g:="*.jpg" m:=1 init:=strInitPath$;
int nn=fname.GetNumTokens(CRLF);
int cleft=50, ctop=30, cright=150, cbottom=130;
for(int ii = 1; ii <= nn; ii++) {
	string strf$ = fname.GetToken(ii, CRLF)$;
	string strGr$;
	insertImg2g fname:= strf$ type:=IMG xyp:=page oname:=strGr$;
	GObject gr = strGr$;
	gr.Crop$="$(cleft) $(ctop) $(cright) $(cbottom)"; //Clipping
	int nx = ii*page.width/5;
	int ny = 1000;
	gr.PageRect$="$(nx) $(ny) $(nx+600) $(ny + 600)";
}

Selected Object Properties

The basic properties of the selected graphic object can be controlled using the syntax:

s.property = value;

The available properties are listed below.

Properties

Property Access Description
FONT Read/Write
Numeric
Font size of the selected text object. Use the Font function, as in name.font = font(arial);
SIZE Read/Write
Numeric
Size of the selected object.
BOLD Read/Write
Numeric
Set Bold to the selected text object.
ANGLE Read/Write
Numeric
Rotation angle of the selected object.

For example, you can use

s.size = 50;

to control the size of a text object if it is selected. .

Methods

The generic methods of these objects are listed below. Not all methods apply to all objects. For example, the addtext method does not apply to a Line object.

Syntax

[winName!]objName.Method(arguments)

or

this.Method(argument)

  • WinName! is required if a Graphic Object exists in a non-active page. It specifies the window that the named object resides in. The layer the object resides in must be the active layer of that page. When using a declared GObject, WinName is never needed.
  • objName is the object's name, as shown in the Object Name text box in the Programming Control dialog box or the name of a declared GObject variable.
  • Method is one of the available objName methods.
  • arguments are specific to the method.
Run objectName.()= to see all methods of the object.

General Methods

Method Description
addText(string) Append the string to a text label. Requires a screen refresh to view the change.
click(n) Simulate a click on the nth hot spot of the object. Multiple hot spots are a feature of UIM objects.
crop(left top right bottom) crop Image object on graph.
draw(option) Redraw the object.

option = local : Redraw the hot spots of an object
option = global : Redraw the entire object

run() Run the script contained in an object.

Examples

  • Append text.
// Declare a string variable and assign a value
string stringVariable$ = " (modified)";
// Assign a value to a string register (A)
// Note how new line is contained in the value
%A = "
Final";
// Now add various text to an existing object named 'text'
text.addtext("%(stringVariable$)");
text.addtext("%(CRLF)Data passes all tests");
text.addtext(A); // No quotes and no % needed for string register
// And force it to refresh
text.draw();

Note : %(CRLF) is a substitution notation that adds a DOS new line (Carriage Return, Line Feed) to a declared or literal string.

  • Simulate a click on the nth hot spot of the object. Multiple hot spots are a feature of UIM objects.
object.click(n);
  • Redraw the object. Option = local to redraw hot spots. Option = global to redraw the entire object.
object.draw(option);
  • Run the script of the object.
object.run();
  • crop the image
string strInitPath$=system.path.program$+"Samples\Image Processing and Analysis";
dlgfile g:="*.jpg" m:=1 init:=strInitPath$;
int nn=fname.GetNumTokens(CRLF);
int cleft=50, ctop=30, cright=150, cbottom=130;
for(int ii = 1; ii <= nn; ii++) {
	string strf$ = fname.GetToken(ii, CRLF)$;
	string strGr$;
	insertImg2g fname:= strf$ type:=IMG xyp:=page oname:=strGr$;
	GObject gr = strGr$;
	if(gr.Crop($(cleft) $(ctop) $(cright) $(cbottom)) == 0) {
		int nx = ii*page.width/5;
		int ny = 1000;
		gr.PageRect$="$(nx) $(ny) $(nx+600) $(ny + 600)";
	}
}

Connect Method

Graphic Objects may be connected using the connect method with various options controlling the connection behavior and displaying an optional connection line.

Note that a "relative position" method was added for Origin 2022b, for connecting a target text object with a source drawn object. This method adds to the previous "connect" method but note that "relative position" requires certain values of dwRigid (>= 17), nTargetRefPt (= 0), and nSourceRefPt (>= 26). The GUI objects Distance Annotation and Asterisk Bracket (Tools toolbar) are added by this method when @URPC = 1 (default).

Syntax

sourceObject.Connect(targetObject, bVisible, dwRigid, nTargetRefPt, nSourceRefPt)

  • sourceObject can be an object name or a GObject variable.
  • sourceObject.Connect(targetObject) returns the UID of the connector.


Parameters

Name Description

targetObject

The object to connect to. This can be an object name, a GObject variable or dataset name/range of plot.
If not specified then all connections to source object will be deleted and other parameters are ignored.

bVisible

If non-zero the connector is visible, else the variable is hidden.
If not specified then connector will be hidden.

dwRigid

Connector rigidity. Set to one of the following values:

1 = targetObject will follow sourceObject when sourceObject is moved
2 = sourceObject will follow targetObject when targetObject is moved
3 = each object follows the other when either is moved
17 = use relative position connector and targetObject will follow sourceObject when sourceObject is moved
18 = use relative position connector and sourceObject will follow targetObject when targetObject is moved
19 = use relative position connector and each object follows the other when either is moved

If this parameter is not specified then the default 1 is used.

nTargetRefPt

Reference point on target object. Value is one of the following.

0 = auto (required by relative position method as it uses text object's anchor to set position)
1 = left bottom
2 = left
3 = left top
4 = top
5 = right top
6 = right
7 = right bottom
8 = bottom
9 = free 1
10 = free 2
11 = free 3
12 = size

nSourceRefPt

Reference point on object being connected. For standard connect method, see nTargetRefPt parameter for allowed values. For relative position method, value is one of following.

26 = Left - Bottom
27 = Left
28 = Left - Top
29 = Top
30 = Right - Top
31 = Right
32 = Right - Bottom
33 = Bottom
34 = Center
35 = Begin
36 = Middle
37 = End
  • For line/arrow/curved arrow, we suggest nSourceRefPt should be 35, 36, 37
  • For rectangle/circle/polygon/region, we suggest nSourceRefPt should be 26 to 34
  • For polyline/curve/free hand draw, decide nSourceRefPt by object shape and preferred label position

Examples

// using GObject variables
// activate a graph with two layers
// each layer has one text object with the same name
GObject aa = [Graph1]1!text;
GObject bb = [Graph1]2!text;
bb.Connect(aa,1);
// using object names
// on a graph, create a text object named "myTextLabel"
// and a line object named "myLine"
myTextLabel.Connect(myLine,0);
// using GObject variable and object name
// on layer 1 of graph, create a text object named "myTextLabel"
// and a line object named "myLine"
GObject aa = [Graph1]1!myTextLabel;
aa.Connect(myLine,0);
// create a line plot on layer 1 of the active graph, 
//and add a text object 
GObject aa = 1!text;
range rr = 1!1;
aa.Connect(rr,1,1,3);
// relative position method
// assume two objects named “rect“ and “text“
// attach text to left bottom corner of rectangle
rect.connect(text, 0, 17, 0, 26);

GetConnected method

One graphic object can get all its connected graphic objects by this method.

See also: label command

Syntax

graphicObject.GetConnected(stringArray, option=0)

  • graphicObject can be an object name or a GObject variable.

Return Value

Return the number of connected graphic objects. If there are no connected graphic objects, it will return zero.

Parameters

Name Description

stringArray

The string array used to store the names of all connected graphic objects.

option

If zero, only get the direct connected graphic objects. If one, get graphic objects recursively.

Example

// using GObject variables
GObject go = [Graph1]1!text;
StringArray sa; 
numObjs = go.GetConnected(sa);
// using object names, recursively
StringArray sa;
numObjs = myLine.GetConnected(sa, 1);
// get names of connected graphic objects
StringArray sa;
numObjs = myLine.GetConnected(sa,1);
if(numObjs>0)  // if has connected objects
{
	for(int iObj=1; iObj<=numObjs; iObj++)  // output connected object name
	{
		string str$ = sa.GetAt(iObj)$;  // get name
		type %(str$);  // type name
	}
}

General Examples

  • This script disables horizontal movement for the Arrow object in the Graph2 window.
Graph2!Arrow.hmove = 0;
  • When entered in the Script window, the next script prints the X and Y coordinates of the center of the Button object to the Script window.
Button.x =;
Button.y =;
  • The following script runs the script associated with an object named Mode in the Graph1 window.
Graph1!mode.run();
  • The last script uses the draw() method to redraw the WksData object in the Data2 window.
Data2!WksData.draw(global);