GetPts
GetPts-cmd
This command uses a Tools toolbar tool to get dataset values of the active dataset from the current graph window.
Syntax:
getpts [options] npts [(message)]
The option determines which tool is used. Variables are stored in properties of the getpts object. Once a tool is selected, the PointProc macro is executed when the user double-clicks or presses ENTER.When npts is reached, the EndToolbox macro is executed.If another Tools toolbar tool is selected before npts is reached, the QuitToolbox macro is executed.
The message help text appears in the status bar.Message is not sent to the substitution processor for string substitution until PointProc is executed. This means that your message text can contain real-time information.
For a detailed discussion of the getpts command, see the Notes and Examples sections that follow.
Note on the getpts command
The getpts command behaves differently than the other 'get' commands. For example, with the getnumber command, first a dialog box opens and then the user makes a selection in that dialog box. Any script after the getnumber command is not executed until the user makes a selection. This allows your script to take different routes depending on the user's selection. However, after the getpts command is executed, the next LabTalk statements are executed without waiting for any user input.
The getpts command can be used in script when it is necessary for the user to pick points on their graph, and then perform some custom analysis. If you use the getpts command incorrectly, your script could complete before the user actually picks a point on their graph. To avoid this problem and to help you understand the getpts command, review the following information.
When using the getpts command, data is entered by:
- Double-clicking on a data point in the graph.
- Clicking on a data point in the graph and then pressing ENTER.
Options:
no option; Get npts by Data Reader tool
Syntax: getpts no option
Use the Data Reader tool to get npts from the dataset the user clicks on.Values are read into the following getpts object properties:
getpts.count -- Contains the number of selected points.
getpts.data$ -- Dataset name.
getpts.xdata -- Dataset that holds each successive X position value.
getpts.indexdata -- Dataset that holds the index value of each successive data point that is double-clicked.
-a npts [message]; Get the XY coordinate value by Screen Reader
Syntax: getpts -a npts [message]
Use the Screen Reader tool to get the XY coordinate value of points in a graph window.Values are read into the getpts object properties.
-n dataset npts [message]; Plot each point up and including npts,and put successive XY value
Syntax: getpts -n dataset npts [message]
Plot each point up to and including npts, and put each successive XY value into dataset.Dataset must already exist before you can use this option.
-x npts [message]; Get the XY coordinate value of points
Syntax: getpts -x npts [message]
Use the Screen Reader tool to get the XY coordinate value of points in a graph window. Restrict cursor movement to horizontal.Values are read into the getpts object properties.
-Y npts [message]; Get the XY coordinate value of points
Syntax: getpts -y npts [message]
Use the Screen Reader tool to get the XY coordinate value of points in a graph window. Restrict cursor movement to vertical.Values are read into the getpts object properties.
Examples:
The getpts command works as follows:
First, the getpts.count object property is set to zero. Next, the getpts.max object property is set to the number of requested points. Lastly, the getpts command runs the script in the [GetPtsNoDraw] section of the ORIGIN.OGS file.
The [GetPtsNoDraw] section of the file performs the following:
- Sets the dataset name for X position to _xpos.
- Sets the dataset name for row index to _indx.
- Sets the dataset name for reading points to the active dataset.
- Creates the datasets (if needed) for X position and row index.
- Defines the pointproc macro as follows:
def PointProc
{
#!type click;
%B = getpts.xData$;
%B[getpts.count] = x;
%B = getpts.indexData$;
%B[getpts.count] = index;
if (getpts.count >= getpts.max)
{
type end toolbox;
{EndToolbox};
doTool 0;
}
else
doTool -next;
};
The pointproc macro executes each time the user selects a data point - either by double-clicking on the point, or single-clicking and pressing ENTER. Once the points are selected, Origin internally traps the selection, sets X to the selected X position and index to the row for this X value, and increments the getpts.count object property. Then, the pointproc macro executes. In this case, this causes the X value and row index to be added to the appropriate datasets. The macro then tests to see if the getpts.count object value is greater than or equal to getpts.max. If getpts.count is greater than getpts.max, then the endtoolbox macro executes and the cursor is switched back to a pointer (dotool 0).
The endtoolbox macro is normally not defined by Origin. It is available so that you can define it to perform a custom routine. For example, if your script prompts the user to pick points on the graph, and then the script performs some custom analysis, you could define the endtoolbox macro to set a data range for analysis using the Data Selector tool. This tool sets the mks1 and mks2 variables to a row index which defines a region for analysis routines. In such an example, you can define the endtoolbox macro to set these markers based on the information gathered by the getpts command, and then execute a command that both carries out an integration (or other analysis) and types the results to the Script window:
def EndToolBox {
mks1 = _indx[1];
mks2 = _indx[2];
integrate %C;
type -a "The Area under %C from $(_xpos[1])-$(_xpos[2]) is $(INTEG.AREA).";
};
In this macro definition, the integrate command puts its results in the integ object. In particular, the calculated area is in the integ.area property. Note that %C contains the active dataset name and the $() notation is used to evaluate a variable or expression and interpret the result as a string.
To test the getpts command with the endtoolbox macro, perform the following:
- Plot some sample data.
- Open the Script window and turn off script execution (Edit:Script Execution).
- Type the endtoolbox macro definition into the Script window.
- Type the following in the Script window:
getpts 2;
- Turn script execution back on by reselecting Edit:Script Execution.
- Highlight all the lines of script and press ENTER to execute the entire script.
The endtoolbox macro gets defined and getpts begins - allowing you (or the user) to select two points on the graph to mark a particular region. The actual analysis is held off until getpts is done - which triggers the endtoolbox routine embedded in the pointproc macro. When the last point is selected, the endtoolbox macro finally runs and the area is calculated with the results typed to the Script window.
Redefining the Pointproc Macro
Because the pointproc macro executes whenever the user selects a data point or a screen location, you can customize the pointproc macro to meet your specific application needs. In the following script example, the user selects a data point on a graph, and then selects a location to display the X and Y coordinates of the selected data point. For this example, you must first plot some data. Then, with the graph window active, run the following script from the Script window:
def pointproc {
xx1=x;
yy1=y;
dotool 0;
def pointproc {
label -s -j 1 -a x y "($(xx1),$(yy1))";
dotool 0;
};
dotool 2;
};
dotool 3;
This script works as follows:
- First the pointproc macro is defined.
- After the macro definition (which includes a redefinition of pointproc), the Data Selector tool is activated (dotool 3).
- When the Data Selector tool is active, the user selects a data point (for example, a peak position).
- After selecting the data point, the pointproc macro runs (by default).
- The pointproc macro assigns the X and Y values of the selected data point to the two variables (xx1 and yy1).
- The pointproc macro temporarily makes the Pointer tool active, and then redefines the pointproc macro.
- The Screen Reader tool is activated (dotool 2).
- While the Screen Reader tool is active, the user selects a screen location for the data point label.
- After selecting the location, by default the pointproc macro runs again (the second definition of it). This results in a label displaying on the graph at the specified location.
- The Pointer tool is reactivated.
|