Origin C Programming Guide

Origin C Programming Guide
Copyright 2010 by OriginLab Corporation All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of OriginLab Corporation. OriginLab, Origin, and LabTalk are either registered trademarks or trademarks of OriginLab Corporation. Other product and company names mentioned herein may be the trademarks of their respective owners.
OriginLab Corporation One Roundhouse Plaza Northampton, MA 01060 USA (413) 586-2013 (800) 969-7720 Fax (413) 585-0126 www.OriginLab.com
Table of Contents
1 Introduction to Origin C......................................................................................... 1
1.1 Basic Features................................................................................................................1 1.2 Hello World Tutorial ........................................................................................................1
2 Language Fundamentals....................................................................................... 5
2.1 Data Types and Variables ..............................................................................................5
2.1.1 2.1.2 2.1.3 2.2.1 2.2.2 2.2.3 2.2.4 2.3.1 2.3.2 2.3.3 2.3.4 2.3.5 2.3.6 2.4.1 2.4.2 2.5.1 2.5.2 ANSI C Data Types.........................................................................................................5 Origin C Composite Data Types .....................................................................................5 Color ...............................................................................................................................6 Arithmetic Operators .......................................................................................................8 Comparison Operators....................................................................................................8 Logical Operators............................................................................................................9 Bitwise Operators..........................................................................................................10 The if Statement............................................................................................................11 The switch Statement ...................................................................................................11 The for Statement .........................................................................................................12 The while Statement .....................................................................................................12 Jump Statements ..........................................................................................................12 The foreach Statement..................................................................................................13 Global Functions ...........................................................................................................14 User-Defined Functions ................................................................................................14 Origin Defined Classes .................................................................................................15 User Defined Classes ...................................................................................................15
2.2 Operators........................................................................................................................7
2.3 Statement Flow Control ................................................................................................10
2.4 Functions ......................................................................................................................14
2.5 Classes .........................................................................................................................15
2.6 Error and Exception Handling.......................................................................................16
3 Predefined Classes .............................................................................................. 19

3.1 3.2 3.3 3.4 3.5 3.6 3.7 Analysis Class ..............................................................................................................19 Application Communication Class................................................................................19 Composite Data Types Class .......................................................................................20 Internal Origin Objects Class........................................................................................22 System Class................................................................................................................32 User Interface Controls Class.......................................................................................32 Utility Class ...................................................................................................................36
4 Creating and Using Origin C Code ..................................................................... 37

4.1 Create and Edit an Origin C File...................................................................................37
4.1.1 4.1.2 4.1.3 4.1.4 Overview .......................................................................................................................37 File Types .....................................................................................................................37 The Workspace View ....................................................................................................39 Code Builder Quick Start...............................................................................................40 iii
4.2 Compiling, Linking and Loading................................................................................... 41

4.2.1 4.2.2 4.2.3 4.2.4 4.3.1 4.3.2 4.4.1 4.4.2 4.5.1 4.5.2 Compiling and Linking................................................................................................... 41 Automated Building....................................................................................................... 42 Building by Script .......................................................................................................... 43 Identifying Errors........................................................................................................... 43 Debugging in Code Builder ........................................................................................... 44 Macros for Debugging................................................................................................... 44 Accessing Origin C Functions from LabTalk Script ....................................................... 46 Defining Functions for the Set Values Dialog................................................................ 50 Distributing Source Code .............................................................................................. 50 Distributing Applications................................................................................................ 50
4.3 Debugging.................................................................................................................... 44
4.4 Using Compiled Functions........................................................................................... 46
4.5 Distributing Origin C Code ........................................................................................... 50
5 Workbooks and Matrixbooks.............................................................................. 53

5.1 Worksheets .................................................................................................................. 54
5.1.1 5.1.2 5.1.3 5.1.4 5.1.5 5.1.6 5.2.1 5.2.2 5.2.3 5.2.4 5.2.5 5.3.1 5.3.2 5.3.3 5.4.1 5.4.2 5.4.3 5.4.4 5.4.5 Adding and Deleting Worksheets.................................................................................. 54 Accessing Worksheets in a Workbook.......................................................................... 54 Reorder Worksheets ..................................................................................................... 55 Copying Worksheet....................................................................................................... 55 Formatting a Worksheet................................................................................................ 56 Merge Cells................................................................................................................... 57 Dimensions ................................................................................................................... 58 Data Type, Format, SubFormat .................................................................................... 58 Data Manipulation ......................................................................................................... 59 Column Label................................................................................................................ 60 Setting Value by Formula.............................................................................................. 61 Accessing a Matrix Object ............................................................................................ 61 Adding and Deleting a Matrix Object............................................................................. 62 Setting View as Data or Image ..................................................................................... 62 Dimensions ................................................................................................................... 62 Data Type and Format .................................................................................................. 63 Labels ........................................................................................................................... 63 Data Values .................................................................................................................. 65 Setting Value by Formula.............................................................................................. 66
5.2 Columns....................................................................................................................... 57
5.3 Matrixsheets................................................................................................................. 61
5.4 Matrices ....................................................................................................................... 62
5.5 Virtual Matrix ................................................................................................................ 66 5.6 Data Manipulation ........................................................................................................ 67

5.6.1 5.6.2 5.6.3 5.6.4 5.6.5 iv Getting Worksheet Selection ........................................................................................ 67 Setting Display Range in Worksheet............................................................................. 68 Putting Large Dataset to Worksheet ............................................................................. 68 Accessing Embedded Graph in a Worksheet ............................................................... 69 Sorting Worksheet Data................................................................................................ 69
Table of Contents 5.6.6 5.6.7 5.6.8 5.7.1 Masking Worksheet Data ..............................................................................................70 Extracting Data from Worksheet with LT Condition.......................................................70 Comparing Data in Two Worksheets ............................................................................71 Worksheet Gridding ......................................................................................................72
5.7 Data Transformation.....................................................................................................72
6 Graphs................................................................................................................... 75
6.1 Creating and Customizing Graph .................................................................................75
6.1.1 6.1.2 6.1.3 6.1.4 6.1.5 6.1.6 6.1.7 6.1.8 6.1.9 6.1.10 6.1.11 6.1.12 6.1.13 6.2.1 6.2.2 6.2.3 6.2.4 6.2.5 6.2.6 6.3.1 6.3.2 6.3.3 6.3.4 6.3.5 6.3.6 6.3.7 6.3.8 6.4.1 6.4.2 6.4.3 6.4.4 6.4.5 6.4.6 6.4.7 6.4.8 6.4.9 Creating Graph Window................................................................................................75 Getting Graph Page Format..........................................................................................76 Setting Graph Page Format ..........................................................................................76 Getting Graph Layer Format .........................................................................................76 Setting Graph Layer Format..........................................................................................76 Show Additional Lines...................................................................................................76 Show Grid Lines............................................................................................................77 Setting Axis Scale .........................................................................................................77 Getting Axis Format ......................................................................................................77 Setting Axis Label .........................................................................................................78 Show Top Axis ..............................................................................................................78 Customizing Axis Ticks .................................................................................................79 Customizing Tick Labels ...............................................................................................79 2D Plot (XY, YErr, Bar/Column) ....................................................................................80 3D Plot ..........................................................................................................................81 Contour Plot ..................................................................................................................81 Image Plot.....................................................................................................................82 Multi-Axes .....................................................................................................................82 Multi-Panels (Multi-Layer, with Shared X-Axis) .............................................................83 Adding Data Marker ......................................................................................................84 Setting Color .................................................................................................................85 Getting Format Tree......................................................................................................85 Setting Format on Line Plot...........................................................................................86 Copying Format from One Data Plot to Another ...........................................................86 Setting Format on Scatter Plot ......................................................................................87 Setting Format on Grouped Line + Symbol Plots ..........................................................87 Setting Colormap Settings ............................................................................................88 Creating a Panel Plot ....................................................................................................90 Adding Layers to a Graph Window ...............................................................................91 Arranging the Layers.....................................................................................................91 Moving a Layer .............................................................................................................91 Resizing a Layer ...........................................................................................................92 Swap two Layers...........................................................................................................92 Aligning Layers .............................................................................................................92 Linking Layers...............................................................................................................93 Setting Layer Unit .........................................................................................................93
6.2 Adding Data Plots.........................................................................................................79
6.3 Customizing Data Plots ................................................................................................84
6.4 Managing Layers ..........................................................................................................90
6.5 Creating and Accessing Graphical Objects ................................................................. 93

6.5.1 6.5.2 6.5.3 6.5.4 6.5.5 6.5.6 6.5.7 6.5.8 Creating Graphical Object............................................................................................. 93 Setting Properties ......................................................................................................... 95 Setting Position and Size .............................................................................................. 95 Updating Attach Property.............................................................................................. 95 Getting and Setting Disable Property............................................................................ 96 Programming Control.................................................................................................... 96 Updating Legend .......................................................................................................... 97 Adding Table Object on Graph ..................................................................................... 97
7 Working with Data ............................................................................................... 99

7.1 Numeric Data ............................................................................................................... 99
7.1.1 7.1.2 7.1.3 7.1.4 7.1.5 7.1.6 7.1.7 7.1.8 7.2.1 7.2.2 7.2.3 7.2.4 7.2.5 7.2.6 7.3.1 7.3.2 7.3.3 Missing Values.............................................................................................................. 99 Precision and Comparison............................................................................................ 99 Convert Numeric to String........................................................................................... 100 Vector ......................................................................................................................... 100 Matrix .......................................................................................................................... 101 TreeNode.................................................................................................................... 101 Complex...................................................................................................................... 101 DataRange.................................................................................................................. 102 String Variables .......................................................................................................... 103 Convert String to Numeric........................................................................................... 104 Append Numeric/String to another String ................................................................... 104 Find Sub String ........................................................................................................... 104 Replace Sub String ..................................................................................................... 104 Path String Functions.................................................................................................. 105 Get Current Date Time................................................................................................ 105 Convert Julian Date to String ...................................................................................... 106 Convert String to Julian Date ...................................................................................... 106
7.2 String Data ................................................................................................................. 103
7.3 Date and Time Data................................................................................................... 105
8 Projects............................................................................................................... 107
8.1 Managing Projects ..................................................................................................... 107
8.1.1 8.1.2 8.1.3 8.2.1 8.2.2 8.2.3 8.2.4 8.2.5 8.3.1 8.3.2 8.3.3 vi Open and Save a Project............................................................................................ 107 Append One Project to Another .................................................................................. 107 The Modified Flag ....................................................................................................... 107 Create a Folder and Get Its Path ................................................................................ 108 Get the Active Folder .................................................................................................. 108 Activate a Folder ......................................................................................................... 108 Get Path for a Specific Page....................................................................................... 109 Move a Page/Folder to Another Location.................................................................... 109 Access a Page by Name and Index ............................................................................ 109 Get the Active Page and Layer ................................................................................... 109 Using foreach.............................................................................................................. 110
8.2 Managing Folders ...................................................................................................... 108
8.3 Accessing Pages ....................................................................................................... 109
Table of Contents
8.4 Accessing Metadata ...................................................................................................110

8.4.1 8.4.2 8.5.1 8.5.2 8.5.3 Access DataRange .....................................................................................................110 Access Tree ................................................................................................................111 List All Operations .......................................................................................................114 Check Worksheet if Hierarchy.....................................................................................114 Accessing Report Sheet..............................................................................................114
8.5 Accessing Operations.................................................................................................114
9 Importing............................................................................................................. 117
9.1 Importing Data ............................................................................................................117
9.1.1 9.1.2 9.1.3 9.2.1 9.2.2 9.2.3 Import ASCII Data File into Worksheet .......................................................................117 Import ASCII Data File into Matrix Sheet ....................................................................118 Import Data Using an Import Filter ..............................................................................119 Import Image into Matrix .............................................................................................120 Import Image into Worksheet Cell...............................................................................121 Import Image to Graph ................................................................................................121
9.2 Importing Images........................................................................................................120
10 Exporting ............................................................................................................ 123

10.1 Exporting Worksheets ................................................................................................123 10.2 Exporting Graphs........................................................................................................123 10.3 Exporting Matrices......................................................................................................124
10.3.1 Export Matrix to ASCII Data File .................................................................................124 10.3.2 Export Image from Matrix to Image File ......................................................................124
11 Analysis and Applications ................................................................................ 125

11.1 Mathematics ...............................................................................................................125
11.1.1 11.1.2 11.1.3 11.1.4 11.2.1 11.2.2 11.2.3 11.2.4 Normalize....................................................................................................................125 Interpolation/Extrapolation ..........................................................................................126 Integration ...................................................................................................................126 Differentiation..............................................................................................................130 Descriptive Statistics on Columns and Rows ..............................................................130 Frequency Count ........................................................................................................130 Correlation Coefficient.................................................................................................131 Normality Test.............................................................................................................132
11.2 Statistics .....................................................................................................................130
11.3 Curve Fitting ...............................................................................................................132

11.3.1 Nonlinear Fitting..........................................................................................................132 11.3.2 Accessing FDF File .....................................................................................................134
11.4 Signal Processing.......................................................................................................135

11.4.1 11.4.2 11.4.3 11.4.4 Smoothing...................................................................................................................135 FFT .............................................................................................................................135 FFT Filtering................................................................................................................136 Wavelet Analysis.........................................................................................................136
11.5 Peaks and Baseline....................................................................................................137

11.5.1 Creating a Baseline.....................................................................................................137 vii
Origin C Programming Guide 11.5.2 Removing a Baseline .................................................................................................. 137 11.5.3 Finding Peaks ............................................................................................................. 138 11.5.4 Integrating and Fitting Peaks ...................................................................................... 139
11.6 Using NAG Functions ................................................................................................ 139

11.6.1 11.6.2 11.6.3 11.6.4 Header Files ............................................................................................................... 139 Error Structure ............................................................................................................ 140 Callback Functions...................................................................................................... 140 NAG Get Data from Origin .......................................................................................... 141
12 Output Objects................................................................................................... 145

12.1 Results Log ................................................................................................................ 145 12.2 Script Window ............................................................................................................ 145 12.3 Notes Window............................................................................................................ 146 12.4 Report Sheet.............................................................................................................. 146
13 Accessing Database.......................................................................................... 147

13.1 Importing from a Database ........................................................................................ 147 13.2 Exporting into a Database ......................................................................................... 148 13.3 Accessing SQLite Database ...................................................................................... 149
14 Accessing LabTalk ............................................................................................ 151

14.1 Getting and Setting LabTalk Numeric Values............................................................ 151 14.2 Getting and Setting LabTalk String Values................................................................ 152 14.3 Running LabTalk Script ............................................................................................. 152 14.4 Embedding LabTalk Script in Origin C Code............................................................. 152
15 User Interface..................................................................................................... 155

15.1 Wait Cursors .............................................................................................................. 155 15.2 Common Dialog Boxes .............................................................................................. 156
15.2.1 15.2.2 15.2.3 15.2.4 Input Box..................................................................................................................... 156 Message Box .............................................................................................................. 156 Progress Box .............................................................................................................. 156 File Dialogs ................................................................................................................. 157
15.3 GetN Dialogs.............................................................................................................. 158

15.3.1 The GETN Macros ...................................................................................................... 158 15.3.2 Event Handling ........................................................................................................... 160
15.4 Picking Points from a Graph ...................................................................................... 161 15.5 Adding Controls to a Graph ....................................................................................... 162
16 Dialog Builder .................................................................................................... 165

16.1 Simple Hello World Dialog ......................................................................................... 166
16.1.1 Create Resource DLL in VC ....................................................................................... 166 16.1.2 Use Resource DLL in Origin C.................................................................................... 169
16.2 Wizard Dialog............................................................................................................. 169 16.3 Graph Preview Dialog................................................................................................ 171

16.3.1 Prepare Dialog Resource............................................................................................ 171 16.3.2 Prepare Source File .................................................................................................... 171 16.3.3 Including Needed Headers ......................................................................................... 171 viii
Table of Contents 16.3.4 Adding User Defined Preview Class ...........................................................................171 16.3.5 Adding Dialog Class....................................................................................................173 16.3.6 Open the Dialog ..........................................................................................................173
16.4 Splitter Dialog .............................................................................................................173

16.4.1 16.4.2 16.4.3 16.4.4 16.4.5 16.4.6 Prepare Dialog Resource............................................................................................174 Prepare Source File ....................................................................................................174 Including Header Files ................................................................................................174 Adding User Defined Splitter Class .............................................................................174 Adding User Defined Splitter Dialog Class..................................................................177 Open Dialog ................................................................................................................178
17 X-Functions ........................................................................................................ 181

17.1 Creating an X-Function...............................................................................................181
17.1.1 17.1.2 17.1.3 17.1.4 17.1.5 17.1.6 17.1.7 17.1.8 Creating a Simple X-Function .....................................................................................181 X-Function Builder ......................................................................................................183 Programming in Code Builder .....................................................................................187 Creating Graph Preview GetN Dialog .........................................................................194 Creating Image GetN Dialog .......................................................................................198 Creating Custom Dialog ..............................................................................................201 Creating Wizard Dialog ...............................................................................................203 Creating a Gadget Tool with X-Function .....................................................................210
17.2 Customizing an X-Function ........................................................................................220

17.2.1 Putting an X-Function in the Product Menu.................................................................220 17.2.2 Adding Documentation to an X-Function.....................................................................223 17.2.3 Adding Custom Button on Dialog ................................................................................223
17.3 Using X-Functions ......................................................................................................225

17.3.1 Calling X-Functions from Script...................................................................................225 17.3.2 Calling X-Functions in Origin C ...................................................................................226
17.4 X-Function Examples .................................................................................................227

17.4.1 17.4.2 17.4.3 17.4.4 Construct Controls on X-Function GUI........................................................................227 Open Graph Browser Dialog in X-Function .................................................................231 X-Function ReportTree Example.................................................................................233 X-Function ReportData Example ................................................................................238
18 Accessing External Resources......................................................................... 241

18.1 Access an External DLL .............................................................................................241 18.2 Access an External Application ..................................................................................242
19 Reference............................................................................................................ 245
19.1 Class Hierarchy ..........................................................................................................245 19.2 Collections ..................................................................................................................247 19.3 X-Function Option Strings ..........................................................................................249
19.3.1 19.3.2 19.3.3 19.3.4 19.3.5 19.3.6 A - Recalculate Mode..................................................................................................249 B - Browser Dialog Options.........................................................................................252 C - Miscellaneous Options ..........................................................................................252 E - Execution Control ..................................................................................................253 F - Dialog Numeric Display Format .............................................................................253 FT - Data Plot Selection Filter .....................................................................................253 ix
Origin C Programming Guide 19.3.7 19.3.8 19.3.9 19.3.10 19.3.11 19.3.12 19.3.13 19.3.14 19.3.15 19.3.16 19.3.17 19.3.18 19.3.19 19.3.20 19.3.21 FV - Specify the Source of Output Variable ................................................................ 254 G - Grouping Controls on GUI .................................................................................... 255 H - Setting Result Tables Shown Style ....................................................................... 256 I - Restrict the Behavior of Input Range Control ......................................................... 258 M - Support Multi-line String ....................................................................................... 262 N - Setting the Default Name of Output Objects ......................................................... 262 O - Setting Output Object Action after Running X-Function ........................................ 262 P - Setting Control Editable on GUI ............................................................................ 263 R - Restrict the Behavior of Dialog Combo Box .......................................................... 265 S - Defining Default Data Selection for Input Variable ................................................ 265 SV - Support String Item in X-Function Dialog Combo Box ........................................ 266 T - Skipping the Variable from Theme ........................................................................ 266 U - Specifying Output as Optional............................................................................... 266 V - Specifying Control to be Invisible .......................................................................... 268 Z - Adding Check Box to Set Editable or Disable for Variable Control ........................ 269
Index......................................................................................................................... 271
Introduction to Origin C
Origin provides two programming languages: Origin C and LabTalk. This guide covers the Origin C Programming language. It also shows you how to create XFunctions and control Dialog Builder dialogs. X-Functions provide a framework within Origin to create tools. Dialog Builder allows you to create and control custom dialogs such as floating tools, dialog boxes and wizards. This guide should be used in conjunction with the Language Reference help files accessible from the Origin Help menu. The most up-to-date source of documentation including detailed examples can be found at our wiki site: wiki.OriginLab.com.
1.1 Basic Features

Origin C is a high level programming language closely based on the ANSI C programming language. In addition, Origin C supports a number of C++ features including classes, midstream variable declarations, overloaded functions, references, and default function arguments. Origin C also supports collections, and the foreach and using statements from the C# programming language. Origin C programs are developed in Origin's Integrated Development Environment (IDE) named Code Builder. Code Builder includes a source code editor with syntax highlighting, a workspace window, compiler, linker, and a debugger. Refer to Help: Programming: Code Builder for more information about Code Builder. Using Origin C allows developers to take full advantage of Origin's data import and handling, graphing, analysis, image export capabilities, and much more. Applications created with Origin C execute much faster than those created with Origin's LabTalk scripting language.
1.2 Hello World Tutorial

This tutorial will show you how to use Code Builder to create an Origin C function, and then access the function from Origin. Though the function itself is very simple, the steps provided here will help you get started with writing your own Origin C functions.
1. Click the Code Builder button on Origin's Standard toolbar to open Code Builder.

2. 3. In Code Builder, click the New button on Code Builder's Standard toolbar to open the New File dialog. Select C File from the list box of the dialog, and then type HelloWorld in the File Name text box.
4. 5.
Click OK and the new file will be opened in Code Builder's Multiple Document Interface (MDI). Copy or type the following Origin C code beneath the line that reads // Start your functions here. int test() { printf("hello, world\n"); // Call printf function to output our text // \n represents the newline character return 0; // Exit our function, returning zero to the caller }
6.
on Code Builder's Standard toolbar to compile and link the Click the Build button HelloWorld.C source file. The Output window of Code Builder should display as
7. 8.
Now you can use this function in Origin. For example, you can call this function in Origin's Script Window. If the Script Window is not open, select the Window: Script Window menu item from the Origin menu to open it. Type the function name test in the Script Window and then press the ENTER key to execute the command. The Origin C function will be executed and hello, world will be displayed in the next line.
9.
Besides the Script Window, the function can also be called from the LabTalk Console Window in Code Builder. Select View:LabTalk Console in Code Builder if this console window is not open.
Once an Origin C file has been successfully compiled and linked, all functions defined in the file can be called as script commands from anywhere in Origin that supports LabTalk script. The function parameters and return value need to meet certain criteria for the function to be accessible from script. To learn more, please refer to the LabTalk Programming: LabTalk Guide: Calling XFunctions and Origin C Functions: Origin C Functions chapter of the LabTalk help file. This help file is accessible from the Help: Programming: LabTalk main menu in Origin.
Language Fundamentals
Origin C is closely based on the ANSI C/C++ programming languages. This means Origin C supports the same data types, operators, flow control statements, user defined functions, classes and error and exception handling. The next sections will elaborate on these areas of Origin C.
2.1 Data Types and Variables

2.1.1 ANSI C Data Types
Origin C supports all the ANSI C data types: char, short, int, float, double and void. In addition, you can have an array of, and a pointer to, each of these data types.
char name[50]; // Declare an array of characters unsigned char age; // Declare an unsigned 8-bit integer unsigned short year; // Declare an unsigned 16-bit integer
2.1.2
Origin C Composite Data Types
Although the C syntax for declaring an array is supported, Origin C provides string, vector and matrix classes to simplify working with data types in one or two dimensional arrays. These data types include char, byte, short, word, int, uint, complex. A vector can be of type string for a string array, but a matrix cannot. A matrix can be of numerical types only.
string str = "hello, world\n"; // Declare and initialize a string vector<double> vA1 = {1.5, 1.8, 1.1}; // Declare and initialize doubles vector vA2 = {2.5, 2.8, 2.1, 2.4}; vector<string> vs(3); // Declare a string array vs[0] = "This "; // Assign string to each string array item vs[1] = "is "; vs[2] = "test"; matrix<int> mA1; // Declare a matrix of integers matrix mA2; // Declare a matrix of doubles // NOTE: The double data type is implied when a data type is not // specified in the declaration of vector and matrix variables.
Another useful class provided by Origin C is the complex class. The complex class supports numeric data containing both a real and an imaginary component.
complex cc(4.5, 7.8); // // // out_complex("value = ", cc); // Declare a complex value. The real component is set to 4.5 and the imaginary component is set to 7.8 Output the complex value
2.1 Data Types and Variables
2.1.3
Color
Colors in Origin C are represented with a DWORD value. These values can be an index into Origin's internal color palette or an actual color composed of red, green, and blue components.
Palette Index
Origin's internal Palette contains 24 colors. An index into Origin's internal color palette is a zero based value from 0 to 23. Origin C provides named constants for each of these colors. Each name begins with the prefix SYSCOLOR_ followed by the name of the color. The following table lists the 24 color names and their indices.
Index 0 1 2 3 4 5 6 7 8 9 10 11 Name SYSCOLOR_BLACK SYSCOLOR_RED SYSCOLOR_GREEN SYSCOLOR_BLUE SYSCOLOR_CYAN SYSCOLOR_MAGENTA SYSCOLOR_YELLOW SYSCOLOR_DKYELLOW SYSCOLOR_NAVY SYSCOLOR_PURPLE SYSCOLOR_WINE SYSCOLOR_OLIVE Index 12 13 14 15 16 17 18 19 20 21 22 23 Name SYSCOLOR_DKCYAN SYSCOLOR_ROYAL SYSCOLOR_ORANGE SYSCOLOR_VIOLET SYSCOLOR_PINK SYSCOLOR_WHITE SYSCOLOR_LTGRAY SYSCOLOR_GRAY SYSCOLOR_LTYELLOW SYSCOLOR_LTCYAN SYSCOLOR_LTMAGENTA SYSCOLOR_DKGRAY
DWORD dwColor = SYSCOLOR_ORANGE;
2.1.3 Color
Auto Color
There is a special color index referred to as Auto. When this index is used the element will be colored using the same color as its parent. Not all elements support the Auto index. See Origin's graphical user interface for the element to determine if the Auto index is supported. The INDEX_COLOR_AUTOMATIC macro is used when the Auto index value is needed.
DWORD dwColor = INDEX_COLOR_AUTOMATIC;
RGB
An Origin color value can also represent an RGB value. RGB values are made up of 8-bit red, green, and blue components. These values can easily be made using the RGB macro}.
DWORD brown = RGB(139,69,19); // saddle brown
The values returned from the RGB macro cannot be directly used as Origin color values. You will need to use the RGB2OCOLOR macro to convert the RGB values to Origin color values.
DWORD brown = RGB2OCOLOR(RGB(139,69,19)); // saddle brown
If you ever need to know whether an Origin color value represents an RGB value or an index into a palette then you can use the OCOLOR_IS_RGB macro. This macro returns true if the value represents an RGB value and returns false otherwise.
if( OCOLOR_IS_RGB(ocolor) ) out_str("color value represents an RGB color"); else out_str("color value represents a color index");
Once you determine that an Origin color value represents an RGB value, then you can use the GET_CRF_FROM_RGBOCOLOR macro to extract the RGB value from the Origin color value.
if( OCOLOR_IS_RGB(ocolor) ) { DWORD rgb = GET_CRF_FROM_RGBOCOLOR(ocolor); printf("red = %d, green = %d, blue = %d\n", GetRValue(rgb), GetGValue(rgb), GetBValue(rgb)); }
2.2 Operators
Operators support the same arithmetic, logical, comparative, and bitwise operators as ANSI C. The following sections list the four types of operators and show their usage.
2.2 Operators
2.2.1
Arithmetic Operators
Operator * / % + multiplication division modulus (remainder) addition subtraction exponentiate See note below. Purpose
Note: Origin C, by default, treats the caret character(^) as an exponentiate operator. This is done to be consistent with LabTalk. ANSI C uses the caret character as the exclusive OR operator. You can force Origin C to treat the caret character as the exclusive OR operator by using a special pragma statement before your code.
out_int("10 raised to the 3rd is ", 10^3); #pragma xor(push, FALSE) out_int("10 XOR 3 is ", 10^3);
Dividing an integer by another integer will give an integer result.

double a = 100 / 22; out_double("100 / 22 is ", a);
The modulus operator calculates the remainder of the left operand divided by the right operand. This operator can only be applied to integral operands.
out_int("The remainder of 11 divided by 2 is ", 11 % 2);
2.2.2
Comparison Operators
Comparison operators evaluate to true or false with true yielding 1 and false yielding 0.
Operator > >= greater than greater than or equal to Purpose
2.2.3 Logical Operators

< <= == != less than less than or equal to equal to not equal to
if( aa >= 0 ) out_str("aa is greater than or equal to zero"); if( 12 == aa ) out_str("aa is equal to twelve"); if( aa < 99 ) out_str("aa is less than 99");
2.2.3
Logical Operators
Logical operators evaluate to true or false with true yielding 1 and false yielding 0. The operands are evaluated from left to right. Evaluation stops when the entire expression can be determined.
Operator ! && || NOT AND OR Purpose
Consider the following two examples:

expr1A && expr2 expr1B || expr2
expr2 will not be evaluated if expr1A evaluates to false or expr1B evaluates to true. This behavior is to the programmer's advantage and allows efficient code to be written. The following demonstrates the importance of ordering more clearly.
if( NULL != ptr && ptr->dataValue < upperLimit ) process_data(ptr);
In the above example the entire 'if' expression will evaluate to false if ptr is equal to NULL. If ptr is NULL then it is very important that the dataValue not be compared to the upperLimit
Language Fundamentals 9
2.3 Statement Flow Control
because reading the dataValue member from a NULL pointer can cause an application to end abruptly.
2.2.4
Bitwise Operators
Bitwise operators allow you to test and set individual bits. The operator treats the operands as an ordered array of bits. The operands of a bitwise operator must be of integral type.
Operator ~ << >> & complement shift left shift right AND exclusive OR (XOR) See note below. inclusive (normal) OR Purpose
Note: Origin C, by default, treats the caret character as an exponentiate operator. This is done to be consistent with LabTalk. ANSI C uses the caret character as the exclusive OR operator. You can force Origin C to treat the caret character as the exclusive OR operator by using a special pragma statement before your code.
out_int("10 raised to the 3rd is ", 10^3); #pragma xor(push, FALSE) out_int("10 XOR 3 is ", 10^3);

Origin C supports all ANSI C flow control statements including the if, if-else, switch, for, while, do-while, goto, break and continue statements. In addition, Origin C supports the C# foreach for looping through a collection of objects.
10
2.3.1 The if Statement
2.3.1
The if Statement
The if statement is used for testing a condition and then executing a block of statements if the test results are true. The if-else statement is similar to the if statement except the if-else statement will execute an alternative block of statements when the test results are false. The following are examples of if statements in Origin C, using different input types:
bool bb = true; // boolean type if( bb ) { out_str("bb is true"); } int nn = 5; if( nn ) // integer type, 0 = false, non-zero = true { out_str("nn not 0"); } double* pData = NULL; if( NULL == pData ) // check if pointer is NULL { out_str("Pointer pData is NULL"); }
The following is a simple if-else block in Origin C. Note that the if-block and the else-block are enclosed in separate sets of curly braces, {}.
if( bRet ) { out_str("Valid input"); } else { out_str("INVALID input"); } // when bRet is true
// when bRet is false
The curly braces are optional if the block contains only one statement. This means the above code can also be written without the braces.
if( bRet ) out_str("Valid input"); else out_str("INVALID input"); // when bRet is true // when bRet is false
2.3.2
The switch Statement
The switch statement is used when you need to execute a different block of statements dependent on a set of mutually exclusive choices. Cases are executed by ascending integer, starting with the number given in the integer argument to the switch statement. Note that the break command will exit the switch-block from any of the cases.
switch( nType ) // integer type value as condition { case 1:
11

case 2: out_str("Case 1 or 2"); break; case 3: out_str("Case 3"); // no break keyword here, so fall through to case 4 case 4: out_str("Case 4"); break; default: out_str("Other cases"); break; }
2.3.3
The for Statement
The for statement is often used to execute one or more statements a fixed number of times or for stepping through an array of data wherein each element is referenced by an index.
char str[] = "This is a string"; for( int index = 0; index < strlen(str); index++ ) { printf("char at %2d is %c\n", index, str[index]); }
2.3.4
The while Statement
The while and do-while statements execute a block of statements until a condition has been met. The while statement tests the condition at the beginning of the loop and the do-while statement tests the condition at the end of the loop.
int count = 0; while( count < 10 ) // execute statements if condition is true { out_int("count = ", count); count++; } int count = 0; do { out_int("count = ", count); count++; } while( count < 10 ); // execute statements if condition is true
2.3.5
Jump Statements
Jump statements are used to unconditionally jump to another statement within a function. The break, continue, and goto statements are considered jump statements. The following examples demonstrate these jump statements.
12 Language Fundamentals
2.3.6 The foreach Statement
break
for( int index = 0; index < 10; index++ ) { if( pow(index, 2) > 10 ) break; // terminate for loop out_int("index = ", index); }
continue
printf("The odd numbers from 1 to 10 are:"); for( int index = 1; index <= 10; index++ ) { if( mod(index, 2) == 0 ) continue; // next index printf("%d\n", index); }
goto
out_str("Begin"); goto Mark1; out_str("Skipped statement"); Mark1: out_str("First statement after Mark1");
2.3.6
The foreach Statement
The foreach statement is used for looping through a collection of objects. The following code loops through all the pages in the project and outputs their name and type.
foreach(PageBase pg in Project.Pages) { printf("%s is of type %d\n", pg.GetName(), pg.GetType()); }
Refer to the Collections section for a list of all the Collection based classes in Origin C.
13
2.4 Functions
2.4 Functions
2.4.1 Global Functions
Origin C provides many global functions for performing a variety of tasks. These global functions fall into twenty-six categories.
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. Basic IO Character and String Manipulation COM Communications Curve Data Conversion Data Range Date Time File IO File Management Fitting Image Processing Import Export Internal Origin Objects LabTalk Interface Math Functions Mathematics Matrix Conversion and Gridding Memory Management NAG Signal Processing Spectroscopy Statistics System Tree User Interface
Please refer to the Global Functions section on the Origin C Wiki for a complete list of functions with examples.
2.4.2
User-Defined Functions
Origin C supports user-defined functions. A user-defined function allows Origin C programmers to create functions that accept their choice of arguments and return type. Their function will then operate on those arguments to achieve their purpose. The following creates a function named my_function that returns a double value and accepts a double value as its only argument.
double my_function(double dData) { dData += 10; return dData; }
The following code snippet shows how to call the above function.
14 Language Fundamentals
2.5.1 Origin Defined Classes

double d = 3.3; // Declare 'd' as a double value d = my_function(d); // Call the above function out_double("d == ", d); // Output new value of 'd'
Origin C functions can also be called from LabTalk.

d = 3.3; // Assign 3.3 to 'd' d = my_function(d); // Call the above function d=; // Output new value of 'd'
2.5 Classes
Origin C supports many built-in classes, but also allows users to create their own.
2.5.1
Origin Defined Classes
Origin C comes with predefined classes for working with Origin's different data types and user interface objects. These classes will help you quickly write Origin C code to accomplish your tasks. This section will discuss the base classes to give you an overview of the capabilities these classes offer. See the next chapter, Predefined Classes, or the Origin C Wiki for more details and examples of Origin defined classes.
2.5.2
User Defined Classes
Origin C supports user-defined classes. A user-defined class allows Origin C programmers to create objects of their own type with methods (member functions) and data members. The following code creates a class named Book with two methods, GetName and SetName.
class Book { public: string GetName() { return m_strName; } void SetName(LPCSTR lpcszName) { m_strName = lpcszName; } private: string m_strName; };
And below is a simple example using the class and method definitions above to declare an instance of the Book class, give it a name using SetName, and then output the name using GetName.
Language Fundamentals 15
2.6 Error and Exception Handling

void test_class() { Book OneBook; // Declare a Book object // Call public function to Set/Get name for the Book object OneBook.SetName("ABC"); out_str(OneBook.GetName()); }
The above example is very simple. If you want to know more class features, for example, constructors and destructors, or virtual methods, please view the EasyLR.c, EasyLR.h and EasyFit.h files under the \Samples\Origin C Examples\Programming Guide\Extending Origin C subfolder of Origin.
2.6 Error and Exception Handling

Origin C supports C++ exception handling using the try, catch, and throw statements. The try block consists of the try keyword followed by one or more statements enclosed in braces. Immediately after the try block is the catch handler. Origin C supports only a single catch handler that accepts an integer argument. After the catch keyword comes one or more statements enclosed in braces.
try { LPSTR lpdest = NULL; // NULL pointer on purpose strcpy(lpdest, "Test"); // copy to NULL pointer to cause error } catch(int nErr) { out_int("Error = ", nErr); }
The try-catch works by executing the statements in the try block. If an error occurs, the execution will jump to the catch block. If no error occurs then the catch block is ignored. The throw keyword is optional and is used to trigger an error and cause execution to jump to the catch block.
void TryCatchThrowEx() { try { DoSomeWork(4); // pass a valid number to show success DoSomeWork(-1); // pass an invalid number to cause error } catch(int iErr) { printf("Error code = %d\n", iErr); } } void DoSomeWork(double num) { if( num < 0 )
16
2.5.2 User Defined Classes

throw 100; // Force error if( 0 == num ) throw 101; // Force error double result = sqrt(num) / log(num); printf("sqrt(%f) / log(%f) = %g\n", num, num, result); }
17
Predefined Classes
In this section, the predefined classes in Origin C will be described. Please see class hierarchy as a reference for more information about the relationships among Origin C built-in classes.
3.1 Analysis Class

The following classes are used to perform data analysis. For more details, please refer to the Origin C: Origin C Reference: Classes: Analysis chapter in the help document of OriginC.
Class Brief Description
NLFitContext
This class provides a method for accessing the information of the fitting function, as well as the current evaluation state that is generated by implementing the fitting function in Origin C. This class is the higher level Origin class. It wraps the NLFit class with a friendly interface to aid in implementing the fitting evaluation procedure. It is the kernel of the NLFit dialog. This class is recommended for coding in Origin C, because it takes care of all the complexities that arise from the process of interfacing to Origin.
NLFitSession
3.2 Application Communication Class

The following classes are used to enable communication between Origin and other applications. For more details, please refer to the Origin C: Origin C Reference: Classes: Application Communication chapter in the help document of OriginC.
Class Matlab Brief Description Used to enable communication between Origin and MATLAB.
19
3.3 Composite Data Types Class

The following classes are composite data types classes. For more details, please refer to the Origin C: Origin C Reference: Classes: Composite Data Types chapter in the help document of OriginC.
CategoricalData
A data set of CategoricalData type is an array of integers. This array is tied to an internal Origin data set of Text type, and will be allocated and sized dynamically. A data set of this type maps the text values to categories by referring to indices (1 based offset). The text values of mapping indices are stored in the data member of CategoricalMap. A data set of CategoricalMap type is an array of text values. This array will be allocated and sized dynamically, but not tied to any internal Origin data set. This data set contains a set of unique text values, which are sorted alpha-numerically and typically referenced by the elements of the associated object of CategoricalData type. This class is used to handle number data of complex type. It contains both the Real part and Imaginary part of the complex number. This class is derived from the curvebase and vectorbase classes, whose methods and properties it inherits. An object of Curve type can be plotted using methods defined in the GraphLayer class easily, and it is comprised of a Y data set and, typically (but not necessarily), an associated X data set. For example, a data set plotted against row numbers will not contain an associated X data set. This class, which is derived from the vectorbase class, from which it inherits methods and properties, is an abstract base class and is used to handle the classes of Curve type, polymorphically. So objects of curvebase type cannot be constructed, and a derived class, such as Curve, should be used instead. This class is derived from the vector and vectorbase classes, and it inherits their methods and properties. A Dataset is an array, which
Predefined Classes
CategoricalMap
complex
Curve
curvebase
Dataset
20
is allocated and sized dynamically. It can be tied or not tied to an internal Origin data set. By default, the Dataset is of type double, but it can also be of any basic data type, including char, byte, short, word, int, uint and complex (but not string). The syntax Dataset<type> can be used to construct these types of Dataset. This class is derived from the matrix and matrixbase classes, from which it inherits methods and properties. A Matrix (upper case M) is a two-dimensional array, which is allocated and sized dynamically, and tied to an internal Origin matrix window. The default type of a Matrix is double, but any basic data type is allowed as well, including char, byte, short, word, int, uint and complex (but not string). The syntax Matrix<type> is used to construct these types of Matrix. This class is used to access the data in the internal Origin matrix, while the MatrixObject class is used to control the style of the matrix. That is to say, the relationship between the MatrixObject and Matrix classes is the same as the one between the Column and Dataset classes. The data values displayed in the cells of the Origin matrix (referenced by a Matrix object) are typically referred to, in the worksheet, as Z values, whose associated X and Y values are linearly mapped to the columns and rows of the matrix, respectively. This class is derived from the matrixbase class, from which it inherits methods and properties. A matrix (lower case m) is a twodimensional array, which is allocated and sized dynamically, and is not tied to any internal Origin matrix window, which provides more flexibility. The default type of a matrix is double, but any basic data type can be used as well, including char, byte, short, word, int, uint and complex (but not string). The syntax matrix<type> is used to construct these types of matrix. This class is an abstract base class for handling the matrix and Matrix class types polymorphically. Thus, objects of matrixbase type cannot be constructed, and objects of its derived classes, such as matrix and Matrix, should be used instead. This class is only used for including the properties of different data types, such as Bool, int, float, double, string, vector, matrix, and picture, etc.
Matrix
matrix
matrixbase
PropertyNode
Predefined Classes
21
3.4 Internal Origin Objects Class
string
This class is used to construct a null terminated array of characters, which is similar to an MFC CString object. A lot of methods for manipulating strings (text data) are defined in this class. It can also be used together with the vector class by syntax vector<string> to define string arrays. This class is used to save Origin C trees as XML files, as well as to load XML files to Origin C trees. This class provides several methods for constructing multilevel trees, traversing trees and accessing the attributes of tree nodes. This class is used to get a collection of child tree nodes with an enumerative name prefix. This class is an abstract base class used for handling objects of vector and Dataset types polymorphically. Thus, objects of this type cannot be constructed, and objects of its derived classes, such as vector and Dataset, should be used instead. This class is derived from the vectorbase class, from which it inherits methods and properties. A vector is an array, which is allocated and sized dynamically, and not tied to any internal Origin data set, which allows for more flexibility. The default type of vector is double, but other basic data types are also allowed, including char, byte, short, word, int, uint, complex, and string. The syntax vector<type> can be used to construct these types of vector.
Tree
TreeNode
TreeNodeCollection
vectorbase
vector

The following classes are used to handle Origin objects. For more details, please refer to the Origin C: Origin C Reference: Classes: Internal Origin Objects chapter in the help document of OriginC.
Class Axis Brief Description
This class is derived from the OriginObject class, and can be

Predefined Classes
22
used to access Origin axes. Origin axes are contained by layers on an Origin page. This class is derived from the OriginObject class, and can be used to access Origin axis objects, including axis ticks, grids and labels. Origin axis objects are contained by axes on an Origin graph page. This class provides a template for collections of various internal Origin objects, such as Pages (the collection of all PageBase objects in a project file), etc. This class contains an implicit templatized type _TemplType, which is the type of one element of the collection. For example, the templatized type of the Pages collection in the Project class (Collection<PageBase> Pages;) is PageBase. Each collection usually has a parent class, whose data member is the collection. For example, Collection<PageBase> Pages is one member of the Project class, because Project contains all the pages. Therefore, each collection can be attached or unattached to an internal object. All collections can use the methods defined in the Collection class. The foreach loop is the most useful way for looping once for each of the elements in the collection. This class is used to access the pages embedded in a worksheet. This class is derived from the DataObject, DataObjectBase and OriginObject classes, and it inherits their methods and properties. In this class, methods and properties are provided for dealing with Origin worksheet columns. A worksheet object contains a collection of Column objects, and each Column object holds a Dataset. A Column object is mainly used for controlling the style of data in the associated Dataset. A Column object is a wrapper object, which refers to an internal Origin column object, but does not actually exist in Origin. This class is derived from the DataObjectBase class, and is
Predefined Classes 23
AxisObject
Collection
CollectionEmbeddedPages
Column
DataObject
the base class of worksheet columns and matrix objects. Origin data objects are contained in layers on an Origin page. For example, columns (data objects) are contained in a worksheet (layer) on a worksheet window (page). This class is an abstract base class, which provides methods and properties for handling the class types related to DataObject and DataPlot, polymorphically. Thus, objects of this type cannot be constructed, and objects of its derived classes, such as DataObject, Column, MatrixObject and DataPlot, should be used instead. This class is derived from the DataObjectBase and OriginObject classes, from which it inherits methods and properties. In this class, methods and properties are provided for Origin data plots. An internal Origin data plot object is used to store the characteristics of the Origin data plot, and it is contained in a graph layer on a graph page. A DataPlot object is a wrapper object, which refers to an internal Origin data plot object and does not actually exist in Origin. Thus, multiple wrapper objects can refer to the same internal Origin object. Methods and properties are provided in this class for constructing data ranges and accessing data in a Worksheet, Matrix or Graph window. This class does not hold data by itself, it just keeps the data range with the page name, sheet name (layer index for a graph) and row/column indices (data plot indices for a graph). Multiple data ranges can be contained in one DataRange object, and the sub data range can be the whole data sheet, one column, one row, multiple continuous columns, or multiple continuous rows. This class is the extensional class of DataRange. This class is used to access non-numeric data sets, which are usually members of Column objects. This class is derived from the Layer and OriginObject classes, and it inherits their methods and properties. This class is used to handle Origin worksheet and matrix layers.
Predefined Classes
DataObjectBase
DataPlot
DataRange
DataRangeEx
DatasetObject
Datasheet
24
Folder
Project Explorer is a user interface inside Origin with folder/sub-folder structure, just likes Window Explorer. It is used to organize and access graph, layout, matrix, note, and worksheet windows in an Origin project file. The Folder class has the ability to access the methods and properties of Project Explorer, and contains collections of all Origin pages and Project Explorer folders. A Folder object is a wrapper object, which refers to an internal Origin Project Explorer object but does not actually exist in Origin. Thus, multiple wrapper objects can refer to the same internal Origin object. This class is used to handle data points that are located in three-dimensional space, with double type for their (x, y, z) coordinates. This class is used to handle data points that are located in two-dimensional, or planar, space and use double type for their (x, y) coordinates. This class is used to get the position (x, y) of a screen point or data point from an Origin graph window. This class is derived from the Layer and OriginObject classes, and it inherits their methods and properties. In this class, methods and properties are provided for Origin graph layers. Internal Origin graph pages contain one or more graph layers, and graph layers contain one or more data plots. Thus, the GraphPage class contains a collection of GraphLayer objects, and the GraphLayer class contains a collection of DataPlot objects. A GraphLayer object is a wrapper object, which refers to an internal Origin graph layer object, but does not actually exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the OriginObject class, from which it inherits methods and properties. In this class, methods and properties are provided for handling Origin graph objects, which include text annotations, graphic annotations (e.g. rectangles, arrows, line objects, etc.), data plot style holders, and region of interest objects.
fpoint3d
fpoint
GetGraphPoints
GraphLayer
GraphObject
Origin graph objects are generally contained in layers on an Origin page, thus the GraphLayer class contains a collection of GraphObjects. A Graph object is a wrapper object, which refers to an internal Origin graph object and does not exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the Page, PageBase, and OriginObject classes, and it inherits their methods and properties. In this class, methods and properties are provided for handling internal Origin graph pages (windows). A GraphPage object is a wrapper object, which refers to an internal Origin graph page object but does not exist in Origin. Thus, multiple wrapper objects can refer to the same internal Origin object. The Project class contains a collection of GraphPage objects, named GraphPages, in the open project file. A GraphPage object can be used to locate and access layers on an Origin graph page, which can then be used to access objects in the layer, such as DataPlots or GraphicObjects. This class is the base class for GraphPage and LayoutPage. This class is used to set the format of data sheet windows (Origin worksheets and matrix sheets). Extra functions are also provided in this class for data selection, showing column/row labels, setting cell text color, merging cells, and so on. This class is derived from the OriginObject class and can be used to handle Origin group plots. GroupPlot objects are contained in layers on an Origin page. This class is derived from the OriginObject class, from which it inherits methods and properties. In this class, methods and properties are provided for handling internal Origin layers. All Origin pages (windows), except note pages, contain one or more layers. Origin objects found "on" a page are generally contained by layers which are themselves contained by the page. Many graph objects are contained in layers, thus the Layer class contains the collection of graph objects. A Layer object is a wrapper object, which refers to an internal
Predefined Classes
GraphPage
GraphPageBase
Grid
GroupPlot
Layer
26
Origin layer object but does not actually exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the Page, PageBase, and OriginObject classes, from which it inherits methods and properties. In this class, methods and properties are provided for handling internal Origin layout pages (windows). The Project class contains a collection of LayoutPage objects. A LayoutPage object is a wrapper object, which refers to an internal Origin layout page object and does not exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the Layer and OriginObject classes, and it inherits their methods and properties. In this class, methods and properties are provided for handling internal Origin layout layers. Origin layout pages contain a layout layer, which contains other objects. A Layout object is a wrapper object, which refers to an internal Origin layout object but does not exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the Datasheet, Layer, and OriginObject classes, from which it inherits methods and properties. In this class, methods and properties are provided for handling matrix layers in Origin matrix pages. An Origin matrix contains a number of matrix objects, thus the MatrixLayer class contains a collection of the matrix objects in the matrix layer. A MatrixLayer object is a wrapper object, which refers to an internal Origin matrix layer object, and does not actually exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the DataObject, DataObjectBase, and OriginObject classes, and it inherits their methods and properties. This class is used to handle internal Origin matrix objects. MatrixObject is mainly used to control the style of the data in the internal Origin matrix, while the Matrix class is used to
LayoutPage
Layout
MatrixLayer
MatrixObject
access the data in the matrix. Thus, the MatrixObject class has the same relationship with the Matrix class as the Column class has with the Dataset class. That is to say, an internal Origin matrix object (MatrixObject) holds a matrix data set (Matrix), just like a worksheet column (Column) holds a data set (Dataset). The data values displayed in the cells of a matrix are considered Z values, whose associated X and Y values are linearly mapped to the columns and rows of the matrix, respectively. A MatrixLayer holds a collection of MatrixObjects, even though there is generally only one MatrixObject per MatrixLayer. A MatrixObject is a wrapper object, which refers to an internal Origin matrix object yet does not actually exist in Origin . So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the Page, PageBase, and MatrixPage classes, from which it inherits methods and properties. In this class, methods and properties are provided for handling internal Origin matrix pages (windows). A MatrixPage object is a wrapper object, which refers to an internal Origin matrix page object but does not exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. The Project class contains a collection of MatrixPage objects, named MatrixPages, in the open project file. A MatrixPage object can be used to locate and access layers on the Origin matrix page, which can then be used to access objects in the layers, such as MatrixObjects and GraphicObjects. This class is derived from the PageBase and OriginObject classes, from which it inherits their methods and properties. In this class, methods and properties are provided for handling internal Origin Note pages (windows). The Project class contains a collection of Note objects. A Note object is a wrapper object, which refers to an internal Origin Note page but does not actually exist in Origin. And so, multiple wrapper objects can refer to the same internal Origin object. This class is the Origin C base class for all Origin objects. Member functions and data members are provided in this
Predefined Classes
MatrixPage
Note
OriginObject
28
class for all Origin objects. This class is derived from the PageBase and OriginObject classes, and it inherits their methods and properties. In this class, methods and properties are provided for handling internal Origin pages, which contain one or more layers (except Note windows). The Page class contains a collection of the layers in the page. A Page object is a wrapper object, which refers to an internal Origin page object but does not exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class provides methods and properties for internal Origin pages (windows). Usually, this class is used in one of two ways. One way is by using a PageBase object as a parameter of a general function, but not using a specific Page object. The other way is by attaching a PageBase object to an unknown active page. Both usages can handle the specific page objects polymorphically. That is also the purpose of this class: to act as an abstract class for its derived page types, which include Note, GraphPage, WorksheetPage, LayoutPage, and MatrixPage. This class is used to handle data points located in twodimensional, or planar, space, with integer (x, y) coordinates. This class provides methods and properties for accessing most objects in an Origin project file. The Project class includes collections of different page types, and collections of all the data sets (including loose data sets, that are not in a worksheet column) in the Project file. This class also provides methods for getting active objects in a project file, as well as RootFolder properties, including ActiveCurve, ActiveLayer, and ActiveFolder. A Project object is a wrapper object, which refers to an internal Origin project object but does not actually exist in Origin. Only one project file can be open in Origin at a time, so all Project objects refer to the currently open project file. This class is derived from the GraphObject class, from which it inherits methods and properties. In this class, methods and properties are provided for working with Origin region of
Page
PageBase
point
Project
ROIObject
interest objects. An Origin region of interest object is used to identify a region of interest in an Origin matrix. A ROIObject is a wrapper object, which refers to an internal Origin region of interest object but does not actually exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the OriginObject class, from which it inherits methods and properties. In this class, methods and properties are provided for handling Origin axis scales. Two scale objects (X scale and Y scale) are contained in every graph layer on a graph page. A Scale object is a wrapper object, which refers to an internal Origin scale object but does not actually exist in Origin. This means that multiple wrapper objects can refer to the same internal Origin object. Origin allows for saving binary type (TreeNode type) and INI type (INIFile type) information in Origin objects, which can be any Origin C objects derived from the OriginObject class, such as a WorksheetPage, Column, Folder, GraphPage, GraphLayer, DataPlot, Project, etc. This class is derived from the GraphObject and OriginObject classes, and it inherits their methods and properties. In this class, methods and properties are provided for data plot style holders. A data plot style holder is used to store plot type information. A StyleHolder object is a wrapper object, which refers to an internal Origin StyleHolder object but does not actually exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class provides two functions for accessing projects safely, UndoBlockBegin() and UndoBlockEnd(). This class is derived from the Page, PageBase, and OriginObject classes, and it inherits their methods and properties. In this class, methods and properties are provided for internal Origin worksheet pages (windows). The Project class contains a collection of WorksheetPage objects.
Predefined Classes
Scale
storage
StyleHolder
UndoBlock
WorksheetPage
30
A WorksheetPage object is a wrapper object, which refers to an internal Origin worksheet page object, but does not actually exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the Datasheet, Layer, and OriginObject classes, from which it inherits methods and properties. In this class, methods and properties are provided for handling worksheet layers on Origin worksheet pages. An Origin worksheet may contain a number of worksheet columns, thus the Worksheet class contains a collection of all the columns in the worksheet. A Worksheet object is a wrapper object, which refers to an internal Origin worksheet object, and does not exist in Origin. So multiple wrapper objects can refer to the same internal Origin object. This class is derived from the DataRange class, from which it inherits methods and properties. By using methods defined in this class, the data range, which has one independent variable (X) and one dependent variable (Y), can be gotten from matrix and worksheet windows, and put into matrix and worksheet windows. It can also be used to make a plot on a graph window. Just like the DataRange class, XYRange does not hold data itself, but just keeps the data range with page name, sheet name (layer index for a graph) and row/column indices (data plot indices for a graph). Every XYRange object can contain multiple sub XY data ranges. This class is derived from the XYRange and DataRange classes, and it inherits their methods and properties. This class is used to get and set XY data sets of complex type for matrix and worksheet windows. Just like the DataRange class, the XYRangeComplex class does not hold data itself, but just keeps the data range with page name, sheet name and row/column indices. Every XYRangeComplex object can contain multiple sub XY complex data ranges. This class is derived from the DataRange class, from which it inherits methods and properties. This class is used to get and
Worksheet
XYRange
XYRangeComplex
XYZRange
3.5 System Class
set XYZ data sets for matrix and worksheet windows. Just like the DataRange class, the XYZRange class does not hold data itself, but just keeps the data range with page name, sheet name and row/column indices. Every XYZRange object can contain multiple sub XYZ data ranges.
3.5 System Class

The following classes are about system settings. For more details, please refer to the Origin C: Origin C Reference: Classes: System chapter in the help document of OriginC.
file
This class is used to control the permission to read/write the binary files by using unbuffered io (accessing immediate disk). It is similar to the MFC CFile class. Please also refer to the stdioFile class, which is for buffered stream io to text files. This class is used to access the data stored in the initialization file. The methods in this class are used to access Windows registry. This class is derived from the file class, from which it inherits methods and properties. This class is used to control the permission to read/write the text and binary files by using buffered stream io. However, this class does not support stream io to stdin, stdout, and stderr. Please also refer to the file class, which is for unbuffered io to binary files.
INIFile
Registry
stdioFile
3.6 User Interface Controls Class

The following classes are about user interface. For more details, please refer to the Origin C: Origin C Reference: Classes: User Interface Controls chapter in the help document of OriginC. The classes marked with * are only available in Origin with the DeveloperKit installed.
32 Predefined Classes

*BitmapRadioButton
This class provides the functionality of bitmap radio button controls. This class provides the functionality of button controls. A button control is a small rectangular child window, which can be clicked on and off. The button will change its appearance when clicked. Typical buttons include check boxes, radio buttons and push buttons. This class is the base class for message map architecture. A message map is used to send a command or message to the member functions you have written, and then the member functions handle the command or message. (A command is a message from a menu item, command button, or accelerator key.) Two key framework classes are derived from this class: Window and ObjectCmdTarget. To create a new class for handling messages, you can just derive your new class from one of these two classes. There is no need to derive from CmdTarget directly. This class is derived from the RichEdit class. It is used to display the redefined color for key words in coding text. This class is only available in Origin packages that have the DeveloperKit installed. This class is used to define combobox control. This class provides the base functionality of all controls. This class is used to define device-context objects. This class is the base class for displaying dialog boxes on the screen. This class is used to create a Dockable control bar with a child Origin C-driven dialog.
*Button
*CmdTarget
*CodeEdit
*ColorText
*ComboBox
*Control
*DeviceContext
*Dialog
*DialogBar
*DynaControl
This class is used to generate various types of customized interface controls dynamically, such as an edit box, combo box, check box, or radio button. The values will be stored in a tree node, and the on dialog will display as a tree structure. This class is used to create edit controls. An edit control is a rectangular child window, which can be filled with text. This class is derived from the OriginControls, Control and Window classes, from which it inherits methods and properties. Methods defined in this class can be used to display an Origin Graph within the specified control on the dialog. This class is the base class of GraphObjCurveTool. It is used to create and manage a rectangle on an Origin graph window, around the region of interest and containing the data. This class is derived from GraphObjTool, from which it inherits methods and properties. With these methods and properties, it can be used to create and manage a rectangle on an Origin graph window, around the region of interest and containing the data. This class also provides methods for adding a context menu and the related event functions. This class is used to define list boxes. A list box shows a list of string items for viewing and selecting. This class is used to handle menus, including creating, tracking, updating and destroying them. This class is the base class for displaying the Origin window on dialog. This class is used to paint a PictureHolder object within the control on dialog. This class provides methods and properties for opening and controlling progress dialog boxes. A progress dialog box is a small dialog box that indicates the software is busy processing data. This
Predefined Classes
*Edit
*GraphControl
GraphObjTool
GraphObjCurveTool
*ListBox
*Menu
*OriginControls
*PictureControl
progressBox
34
dialog box contains a progress bar for showing the fraction of the completed processing. The progress dialog box is usually used in iterative loops. This class is used to construct individual page objects of property sheets in a wizard dialog. This class is used to construct property sheets in a wizard dialog. One property sheet object can contain multiple property page objects. This class provides methods for formatting text. A rich edit control is a window, in which text can be written and edited. The text can be in character and paragraph formatting. A slider control is a window with a slider and optional ticks. When the slider is moved by the mouse or the directional keys on the keyboard, the control will send a notification message to implement the change. A spin button control is a pair of arrow buttons that can be used to increase or decrease a value, such as scroll position or the number displaying in an accompanying control. This value is called the current position. A tab control is used to display different information under different tabs in a dialog. This class provides methods to add/delete tab items for displaying a group of controls. A wait cursor is a visual sign for indicating that the software is busy processing data. This class provides methods and properties for opening and controlling wait cursors. This class is the base class of all window classes. It is similar to the MFC CWnd class. This class is used to construct wizard controls for implementing something step by step in a dialog. The methods available in this class enable you to add/delete steps.
*PropertyPage
*PropertySheet
*RichEdit
*Slider
*SpinButton
*TabControl
waitCursor
*Window
*WizardControl
3.7 Utility Class
*WizardSheet
This class is used to construct property sheet objects in a wizard dialog. A property sheet contains one or more property page objects. This class is derived from the OriginControls, Control and Window classes, and it inherits their methods and properties. The methods available in this class can be used to display an Origin Worksheet within the specified control in a dialog. This class is the base class of the derived control classes.
*WorksheetControl
*WndContainer
3.7 Utility Class

For more details about the following classes, please refer to the Origin C: Origin C Reference: Classes: Utility chapter in the help document of OriginC.
Array
This class is a collection of almost all data types and objects. When Array::IsOwner is TRUE, the array will be the owner of the memories that are allocated to the objects. And the objects will be destroyed when the array is resized or destructed. This class is used to compress byte vectors (1 and 0) to hexadecimal strings, and decompress hexadecimal strings to byte vectors. This class can be used to measure the call times of various functions to find out the slower ones.
BitsHex
Profiler
36
Predefined Classes
Creating and Using Origin C Code
4.1 Create and Edit an Origin C File

4.1.1 Overview
Code Builder is an Integrated Development Environment (IDE) for Origin C and LabTalk programming. Code Builder provides tools for writing/editing, compiling, linking, debugging, and executing your Origin C code. Although Origin C code can be written in any text editor, it must be added to Code Builder's Workspace to be compiled and linked.
The Code Builder window
4.1.2
File Types
Origin C utilizes four types of files: source, object, preprocessed, and workspace.
37
Source (*.c, *.cpp, *.h)

Source files are essentially text files that contain human-readable Origin C code. You may create them in Code Builder or another text editor, and save them to any location. Code Builder's text editor provides syntax coloring, context-sensitive help and debugging features. Until source files have been compiled, linked and loaded, the functions they contain cannot be used in Origin.
Object (*.ocb)
When a source file is compiled, an object file is produced. The object file will have the same file name as the source file, but will be given the *.ocb file extension. The object file is machine readable, and is what Origin uses to execute functions that are called. Origin compiles a source file for the first time, and then recompiles only when the source file is changed. Object files in Origin are version specific, and therefore, sharing them is discouraged. If you wish to share some functions or Origin C applications, share preprocessed files instead.
Preprocessed (*.op)
By default, Origin compiles source files to produce object files. However, the system variables below can be changed to produce a preprocessed file instead of an object file. Preprocessed files still require compiling, but have the following advantages for code sharing: Origin version independent Functions can be shared without sharing source code The build process happens much faster than with source files The system variables that allow you to produce either object (OCB) or preprocessed (OP) files are @OCS, @OCSB, and @OCSE. You can change their values in the Script Window or in the Code Builder LabTalk Console. For example, in the Script Window, enter:
@OCSB=0; // Hereafter, on compile, generate OP files
@OCS
The default value of this variable is 1, which allows you to create an OCB file or OP file. If @OCS=0, the compiler will not create an OCB file or an OP file.
@OCSB
The default value of @OCSB=1; this generates an object file at compile time. To generate an OP file, set @OCSB=0, after which OP files will be generated at compile time. The OP file will be saved in the same folder as its source file and have the same file name, but with the OP extension. Note that if @OCS=0, this variable is meaningless.
@OCSE
This variable is only available in OriginPro. Its default value is 0. After setting @OCSE=1, the compiler will generate an encrypted OP file, which will hide implementation details. The
38
4.1.3 The Workspace View
encrypted OP file can be loaded and linked by either Origin or OriginPro versions. Note: this variable is only meaningful when @OCSB=0.
Workspace (*.ocw)
In Code Builder, you may create or use a project that contains many Origin C source files. These files may or may not be hierarchically organized in folders. It would be very inconvenient to have to load many such files manually each time you switched between projects. For this reason, the structure and files contained in the User folder can be saved to a workspace file. Upon loading a workspace file into Code Builder, a project is restored to the state in which it was last saved; all of your source files are available in whatever structure they were assigned.
4.1.3
1. 2. 3. 4.
The Workspace View

Project System Temporary User
The Code Builder Workspace view contains four folders:
The Workspace View The files in each folder are compiled and linked following different events.
Project
Files in the Project folder are saved within the current Origin project file (*.OPJ). They are added to the Project folder of the Code Builder workspace when you open an Origin project file containing them. They are automatically compiled and linked upon opening the project file.
39
System
Files in the System folder are externally saved in Windows folders (usually in the Origin C folder or one of its subfolders). They are automatically added to the System folder of the Code Builder workspace, compiled, and linked whenever Origin starts.
Temporary
All files that are not listed in the Project, System, or User folders, and get loaded and compiled when using Origin, will appear in the Temporary folder. For example, if you export a graph then all the files used for handling a graph export will appear in the Temporary folder.
User
Files in the User folder are externally saved in Windows folders and are manually added to the User folder of the Code Builder workspace, compiled, and linked by the user in Code Builder.
4.1.4
1. 2. 3.
Code Builder Quick Start

Open Code Builder by pressing Alt+4 on the keyboard or by clicking the Code Builder toolbar button . Create a new source code file by pressing Ctrl-N or by clicking the New toolbar button. When the New File dialog appears enter a name for your source code file and then press Enter or click the OK button. An editor window will open. Go to the end of the last line in the editor window and press enter to start a new blank line. Enter the following function: void HelloWorld() { printf("Hello World, from Origin C\n"); }
Get started using Code Builder in just a few steps:
4.
Before we can call this function we need to compile and link the code. You can do this by pressing Shift+F8 or by clicking the Build toolbar button .
5. 6.
The Output window will show the compiling and linking progress. If any errors appear, then double check your function and fix the errors. When no errors appear, the function is ready to be called. Click in the top part of the Command & Results window. Type the name of your function and press Enter. In the bottom part of the Command & Results window you should see a repeat of your function's name, and the line you entered, followed by a line with your function's output.
While these steps are sufficient to get you going with Code Builder, there are many more details that will help you write, debug and execute your Origin C files effectively. These are covered in the sections that follow.
40
4.2.1 Compiling and Linking
4.2 Compiling, Linking and Loading

Before you can access your Origin C functions, you will need to compile and link them (a process known as building) using Code Builder. Once your functions compile and link without error, they are loaded automatically, and you will be able to access them from the current Origin session. To access your functions in future sessions of Origin you will need to ensure that they are reloaded and linked; a process that is fast and can be automated. This chapter covers the manual and automated build process for Origin C source files and preprocessed files.
4.2.1
Compiling and Linking
In order to make the functions defined in an Origin C source file or preprocessed file executable for the first time, the following steps are necessary:
Add the file to the Code Builder workspace Compile the file Link the file to all dependents, compiling dependents where necessary, and load the object files that are created.
The act of compiling and linking all the files is referred to as building.
Add the File to the Workspace

Before a source file or preprocessed file can be compiled and linked, the file must be added to one of the Code Builder workspace folders: Project, User, System, or Temporary. Note that all source files are initially created or loaded into the User folder.
Compile the File

After adding the file to the workspace, it needs to be compiled (by clicking the Compile button) to generate the object file, which will have the same name as the source/preprocessed file, but with the OCB file extension. In Origin versions 8.1 and later, the object file will be saved in the Application Data folder. In older versions the file was saved to the User Files\OCTemp folder.
Build the Workspace

To build the active file and all its dependents, select the Build button, or select the
Rebuild All button to build all files in the workspace. The object file that is created will be automatically loaded into memory and linked so that the functions defined in the file are executable within Origin.
Creating and Using Origin C Code 41
4.2 Compiling, Linking and Loading
Once the object file is generated, subsequent build processes will be much faster. If there are no changes to the built source/preprocessed file, Code Builder will load and link the object file directly, but not rebuild the file.
Build vs. Build All

Build: All of the files in a given folder are compiled and linked when that folder is the active window in the Code Builder (or a dependent of the active window) and the Build toolbar button is clicked. Build All: files in all Code Builder folders are compiled and linked when the Code Builder Rebuild All toolbar button is clicked.
4.2.2
Automated Building
Initially, all Origin C source or preprocessed files are created or opened in the User folder, and the discussion above gives details for manually building Origin C source files. Many times, however, it is advantageous to automate the build process. This can be done by making use of Code Builder's folder structure, each with slightly different functionality, or by utilizing the Build on Startup option:
Add files to Code Builder's Project folder, and they will be built automatically each time the associated Origin project is opened. Add files to Code Builder's System folder, and they will be built automatically each time Origin starts. Files in the System folder are also rebuilt each time an Origin project or a Code Builder project is started or opened. The Build on Startup option will build the most recently opened Code Builder workspace upon Origin startup.
Add files to the Project Folder

You can add files to the System folder using the following methods:
Right-click on the Project folder and choose Add files. Drag a file from another Workspace folder and drop it on the Project folder.
Add files to the System Folder

You can add files to the System folder using the following methods:
Right-click on the System folder and choose Add files. Drag a file from another Workspace folder and drop it on the System folder. Edit the OriginCSystem section in the Origin.ini file. Editing this section must be done when Origin is not running. The section contains an entry for each file.
42
4.2.3 Building by Script
Build on Startup
When Origin starts it will examine the contents of the Origin C Workspace System folder and if it finds any changed files then it will try to compile and link them. You also can have this procedure done to the files in the User folders by enabling the Build on Startup option. Activate Code Builder If the Workspace view is not visible then choose Workspace on the View menu. Right-click on Origin C Workspace. If the Build on Startup item is not checked then click it. The next time you start Origin it will check the files in the User folder and try to compile and link any changed files.
4.2.3
Building by Script
When you want to call an Origin C function in LabTalk script, you need to make sure the source file has been compiled and linking is done. You can then use the LabTalk command Run.LoadOC to compile and link the specific source file. For example:
1. 2. Choose File->New Workspace... to create a new workspace. The Temporary folder should be empty now. Run the following script in the Command Window... the dragNdrop.c file together with its dependent files all are loaded into the Temporary folder and compiled. if(run.LoadOC(OriginLab\dragNdrop.c, 16) != 0) { type "Failed to load dragNdrop.c!"; return 0; }
4.2.4
Identifying Errors
When you compile and link source files in Code Builder, the compiling and linking results are displayed in the Code Builder Output window. If the compiling and linking was successful, the Output window lists the source files that were compiled. The Done! line indicates success. If errors were encountered during the compiling and linking process, the Output window lists the file name, line number, and the error encountered. You can double-click on the error line in the Output window to activate the source file and position the cursor on the line of code containing the error.
43
4.3 Debugging
4.3 Debugging
4.3.1 Debugging in Code Builder
Code Builder has features that allow you to debug your Origin C and LabTalk code. You can set and remove breakpoints, step through your code one statement at a time, step into and out of functions, and monitor the values of variables. Debugging is turned on by default. You can turn debugging on or off using the Enable Breakpoints item on the Debug menu. If there is a check mark next to the item then debugging is turned on. More details of the debugger are covered in the Code Builder User Guide, which can be found in Origin under Help: Programming: Code Builder.
4.3.2
Macros for Debugging
Origin C allows users to define multi-parameter macros which have many uses. Two such uses, which help while debugging, are the ASSERT macro and macros containing debug statements. The following sections contain example code and discuss these macros in more detail. The example file DebugMacros.c can be found in the \Samples\Origin C Examples\Programming Guide\Introduction to Origin C subfolder of Origin.
The ASSERT Macro

Origin C provides an ASSERT macro to identify logic errors during program development. The Origin C ASSERT macro has the following syntax:
ASSERT(condition)
When a function is called that includes an ASSERT, the ASSERT launches a message box when the condition evaluates to false (zero). The diagnostic message indicates the source file
44 Creating and Using Origin C Code
4.3.2 Macros for Debugging
and line number where the assertion failed. Thus, if your function expects a variable value to be non-zero, you could add the following line of code to alert you if the variable value is zero.
ASSERT(myVar != 0);
In the following example, if the size of the vector bb is not equal to the size of the vector aa, then a diagnostic message box will launch to indicate assert failure.
void AssertMacro(int imax = 10) { vector<int> aa(imax); vector<int> bb; for (int ii = 0; ii < aa.GetSize(); ii++) aa[ii] = ii; bb = 10 * aa; // imax += 1; ASSERT(bb.GetSize() == imax); for (ii = 0; ii < bb.GetSize(); ii++) printf("bb[%d]=%d \n", ii, bb[ii]); }
If you run the above function with the line imax+=1; commented out then no ASSERT message box appears. However, if you uncomment the line imax+=1; (and rebuild) the ASSERT message below is outputted.
Clicking Yes will open the appropriate source file (DebugMacros.c) in the Code Builder text editor and stop at the line generating the ASSERT message box for debugging.
Debug Statements
Many programmers use output statements while developing code to indicate program flow and display the values of variables at key moments.
Create an Output Macro

A convenient debugging technique is to define an output macro and then place that macro throughout your code as shown below.
Creating and Using Origin C Code 45
4.4 Using Compiled Functions

#define DBG_OUT(_text, _value) out_int(_text, _value);
void DebugStatements() { int ii; DBG_OUT("ii at t0 = ", ii) ii++; DBG_OUT("ii at t1 = ", ii) ii++; DBG_OUT("ii at t2 = ", ii) ii++; DBG_OUT("ii at t3 = ", ii) printf("Finished running DebugMacros."); }
Comment the Debug Macro Body

During the development cycle the body of the macro can remain defined as above causing the desired debug messages to be shown on the message box. However, once development is complete (or at least stable) the macro can be redefined as below causing the debug statements to disappear.
#define DBG_OUT(_text, _value) // out_int(_text, _value);
Commenting out the body of the DBG_OUT macro (and rebuilding) causes the debug statements to disappear without having to remove the many possible instances of its use, saving them for possible reuse in the future. Should the code ever need to be modified or debugged again the body of the macro can simply be uncommented.

Once Origin C functions have been compiled, linked and loaded, they are ready to be used in Origin. This means calling the function by its name and providing the necessary arguments from any location in Origin that accepts LabTalk script commands. Common locations include the script window, the command window, or a custom button in the Origin GUI. Running Scripts chapter of the LabTalk Scripting Guide details all of the locations in Origin from which script, and therefore Origin C functions, can be used.
4.4.1
Accessing Origin C Functions from LabTalk Script
Origin C functions can be called from other Origin C functions and from LabTalk scripts. This section talks about how to control the access to Origin C functions from LabTalk. For information about accessing LabTalk from your Origin C code, refer to the Accessing LabTalk chapter.
46
4.4.1 Accessing Origin C Functions from LabTalk Script
Origin C Access from LabTalk

You can control LabTalk access to your Origin C code by putting a pragma statement in your Origin C code before your function definitions.
#pragma labtalk(0) // Disable OC functions in LabTalk void foo0() { } #pragma labtalk(1) // Enable OC functions in LabTalk (default) void foo1() { } #pragma labtalk(2) // Require '''run -oc''' LabTalk command void foo2() { }
The above code prevents foo0 from being called from LabTalk, allows foo1 to be called from LabTalk, and allows foo2 to be called from LabTalk using the run -oc command. If you were to comment out the second pragma, then both foo0 and foo1 would be prevented from being called from LabTalk. This is because a single pragma statement applies to all functions after the pragma and up to the next pragma or the end of the file. There is also a LabTalk system variable that controls LabTalk access to all Origin C functions. The variable is @OC, and it defaults to 1, which enables access. Setting the variable to 0 disables access.
Listing Functions that can be Called from LabTalk

The LabTalk list command can be used to output all the names of Origin C functions that can be called from LabTalk. Options let you modify which type of functions is listed:
list list list list list f; fs; fv; fn; fo; // // // // // List List List List List functions callable from LabTalk only those returning a string only those returning a vector only those returning a numeric only those returning void
Note that setting @OC=0 will make Origin C functions effectively invisible to LabTalk, such that the list f command will give no result.
Passing Arguments to Functions

LabTalk script does not support all of the data types used internally by Origin C. The following table lists the LabTalk variable types that should be passed (or returned) when calling an Origin C Function with the given argument (or return) type. The final column indicates whether or not that argument type can be passed by reference.
47

Origin C int double string bool matrix vector<int> vector<double> vector<complex> vector<string> int double string int matrix range dataset dataset dataset dataset, string array* LabTalk Yes Yes Yes No Yes Yes Yes No No Pass By Reference?
* string arrays cannot be passed by reference As the table above indicates, arguments of Origin C functions of type string, int, and double may be passed by value or by reference from LabTalk. Note, however, that the Origin C function must be written for the type of pass being performed.
Passing by Value
Below are examples of passing arguments by value from LabTalk to Origin C. The format for each example is to give the Origin C function declaration line, and then the LabTalk code used to call it. The Origin C function body is left out since it is unimportant for demonstrating variable passing. The simple case of a function accepts an argument of type double and returns a double.
double square(double a) double dd = 3.2; double ss = square(dd); ss =; // Origin C function declaration // LabTalk function call // ss = 10.24
Here, an Origin C function that takes a vector argument and returns a vector, is called by LabTalk using data set variables, or ranges that are assigned to data types.
vector<string> PassStrArray(vector<string> strvec)
Can be called three ways from LabTalk:

dataset dA, dB;
48
4.4.1 Accessing Origin C Functions from LabTalk Script

dB = Col(B); dA=PassStrArray(dB); Col(A)=PassStrArray(Col(B)); // Or, use Col directly, Col = dataset
// Or, LabTalk ranges may also be used range ra = [Book1]1!1, rb = [Book1]1!2; ra = PassStrArray(rb);
Passing by Reference
For the Origin C function below, note the ampersand & character in the argument declaration, indicating that the argument will be passed by reference.
double increment(double& a, double dStep) double d = 4; increment(d, 6); type -a "d = $(d)"; // d = 10
The following example demonstrates some arguments being passed by reference and others being passed by value.
int get_min_max_double_arr(vector<double> vd, double& min, double& max) dataset ds = data(2, 30, 2); double dMin, dMax; get_min_max_double_arr(ds, dMin, dMax); //Or use a data set from a column; be sure to put data in Col(A) get_min_max_double_arr(Col(A), dMin, dMax);
The following example shows passing a LabTalk matrix range variable by reference to an Origin C function.
// set data from vector to matrix void set_mat_data(const vector<double>& vd, matrix& mat) { mat.SetSize(4,4); mat.SetByVector(vd); } range mm = [MBook1]1!1; dataset ds = data(0, 30, 2); set_mat_data(ds, mm);
Precedence Rules for Functions with the Same Name

When a user-defined or global Origin C function has the same name as a built-in LabTalk function, the Origin C function has higher precedence, except when using LabTalk vector notation. Precedence:
1. 2. 3. LabTalk Function (vector) Origin C Function LabTalk Function (scalar)
Thus, LabTalk functions like Normal and Data (which return a range of values and are thus used in vector notation) would have higher precedence than Origin C functions of the same name. In all other cases, the Origin C function is called.
49
4.5 Distributing Origin C Code
4.4.2
Defining Functions for the Set Values Dialog
You may want to define a function using Origin C, that will appear in the Set Values menu of either a column or a matrix. If an Origin C function is built as part of an Origin project---either automatically by being placed in the Project or System folder of Code Builder, or manually by building a function in the User folder---it will be available in the User-Defined section of the F(x) menu in the Set Values dialogs (for both Columns and Matrices). To assign a function to a different section of the F(x) menu, issue a pragma containing the new section name as part of the function header. For instance, the following code will add function add2num to the Math section and function mean2num to the Statistics section:
#pragma labtalk(1,Math) double add2num(double a, double b) { return a + b; } #pragma labtalk(1,Statistics) double mean2num(double a, double b) { return (a + b)/2; }
In this way, many functions can be defined in a single source file and, upon building, be immediately available in the desired locations of the F(x) menu. Functions to be added to the F(x) menu must conform to the following additional restrictions:
The return type of the function cannot be void The function should not have reference or pointer (&) for argument type

4.5.1 Distributing Source Code
Origin users can share Origin C source code with one another by distributing either the source files themselves (.C or .CPP) or preprocessed files (.OP). If it is not necessary for others to see your application's source code, it is highly recommended that you distribute preprocessed files (.OP) instead of the source files (.C or .CPP). See the Preprocessed Files (*.op) in the Create and Edit an Origin C File section for more information.
4.5.2
50
Distributing Applications
After creating an application, you can distribute it as a single package file to other Origin users.
4.5.2 Distributing Applications
Use Package Manager to package all the application files into a single package file (.OPX). Note that when adding your application files into the package, be sure to add the preprocessed files (.OP) or the source files (.C or .CPP). It is not necessary to add both. Users can install your application by dropping the package file directly into Origin. The following is an example that shows how to package all the application files into one OPX file. The user can drop the package file into Origin to install, then click a button to run the source file.
1. Prepare an Origin C source file. In Code Builder, choose menu File->New to create a new c file named MyButton.c, copy the following code to it and save it to the User File Folder\OriginC subfolder. void OnButtonClick() { Worksheet wks = Project.ActiveLayer(); DataRange dr; dr.Add(wks, 0, "X"); dr.Add(wks, 1, "Y"); GraphPage gp; gp.Create(); GraphLayer gl = gp.Layers(0); int nn = gl.AddPlot(dr); gl.Rescale(); } 2. Create an OGS file named MyButton.ogs to load the Origin C source file and call function. Copy the following and save it to the User File Folder. [Main] if(0 == Run.LoadOC(%Y\OriginC\MyButton.c)) { OnButtonClick; } 3. In the Origin menu, choose View->Toolbars. In the Customize Toolbar dialog, choose the Button Groups tab, and click New to open the Create Button Group dialog. Set MyButton as the Group Name, keep Number of Buttons as 1, choose the Userdef.bmp file from the User File Folder as Bitmap, and click the OK button. In the ensuing Save As dialog, click the Save button to save the MyButton.ini file to the default path. In the Customize Tool dialog, click to choose the button, then click Settings to open a Button Settings dialog. Choose MyButton.ogs as the File Name, type Main in for Section Name, and click OK to close the dialog. Click Export to open the Export Button Group dialog, then click Add File and choose the above MyButton.c file.
4. 5.
51
6. 7.
Click Export, then in the Save As dialog click Save to save the MyButton.OPX file to the specified folder. Choose menu Tools->Package Manager, and in the dialog that opens, choose File->Open to open the MyButton.OPX file. Put the script Run.LoadOC(%Y\OriginC\HelloWorld.c); into LabTalk Script->After Installation in gird view to load the Origin C source file. This script will be run when you drop OPX into Origin to install this application.
52
Workbooks and Matrixbooks
The Origin C WorksheetPage and MatrixPage classes are for working with Origin workbooks and matrix books respectively. Each book contains a collection of sheets and each sheet contains a collection of Columns or MatrixObjects. Creating a Workbook/Matrixbook The Create method is used for creating new books.
// create a hidden workbook using the ColStat template WorksheetPage wksPg; wksPg.Create("ColStat", CREATE_HIDDEN); MatrixPage matPg; matPg.Create("Origin"); // create a matrix book using the Origin template
Accessing a Workbook/Matrixbook There are multiple ways to access an existing workbook or matrix book. The methods used are the same for both workbooks and matrix books. The Project class contains a collection of all the workbooks or matrix books in the project. The following example shows how to loop through them.
foreach(WorksheetPage wksPg in Project.WorksheetPages) out_str(wksPg.GetName()); // output workbook name foreach(MatrixPage matPg in Project.MatrixPages) out_str(matPg.GetName()); // output matrix book name
You can access a workbook or matrix book by passing its index to the Item method of the Collection class.
MatrixPage matPg; matPg = Project.MatrixPages.Item(2); if( matPg ) // if there is a 3rd matrix book out_str(matPg.GetName()); // output matrix book name
You can access a workbook or matrix book by passing its name to the class constructor.
WorksheetPage wksPg("Book1"); if( wksPg ) // if there is a workbook named "Book1" wksPg.SetName("MyBook1"); // rename the workbook
Deleting a Workbook/Matrix Book All of Origin C's internal classes are derived from the OriginObject class. This class has a Destroy method that is used to destroy the object. Calling this method on a workbook or matrix book will destroy it, all the sheets in the workbook or matrix book, and all the columns or matrix objects in each sheet.
WorksheetPage wksPg; wksPg = Project.WorksheetPages.Item(0); // get first workbook in project if( wksPg ) // if there is a workbook wksPg.Destroy(); // delete the workbook
53
5.1 Worksheets
Clone a Workbook/Matrix Book The WorksheetPage class (for a Workbook), MatrixPage class (for a Matrixbook) and GraphPage class (for a Graph window) are all derived from the Page class. This class has a Clone method that is used to clone the source page.
// Duplicate "Book1", "MBook1" and "Graph1" window with data and style // Before calling make sure these windows exist WorksheetPage wksPage("Book1"); WorksheetPage wksPage2 = wksPage.Clone(); MatrixPage matPage("MBook1"); MatrixPage matPage2 = matPage.Clone(); GraphPage gp("Graph1"); GraphPage gp2 = gp.Clone();
5.1 Worksheets
Origin C provides the Worksheet class for working with the worksheets in a WorksheetPage. While a workbook contains a collection of worksheets, a worksheet contains a collection of Columns. The Worksheet class is derived from the Layer class.
5.1.1
Adding and Deleting Worksheets
Add a worksheet to a workbook using the AddLayer method of the WorksheetPage class.
// Access the workbook named "Book1" WorksheetPage wksPage("Book1"); // Add a new sheet to the workbook int index = wksPage.AddLayer("New Sheet"); // Access the new worksheet Worksheet wksNew = wksPage.Layers(index); // Set the new worksheet to be active set_active_layer(wksNew);
Use the Destroy method to delete a worksheet.

Worksheet wks = Project.ActiveLayer(); if( wks ) // If the active layer is a worksheet wks.Destroy(); // Delete the worksheet
5.1.2
Accessing Worksheets in a Workbook
There are two ways to access a worksheet by its name. You can pass the layer's full name to the constructor or to the Attach method. The layer's full name contains the page name in square brackets followed by the layer name.
54 Workbooks and Matrixbooks
5.1.3 Reorder Worksheets

// Assume wksPage is a valid WorksheetPage holding the sheet we want to access. string strFullName = "[" + wksPage.GetName() + "]" + "Sheet1";
With the full layer name we can now access the worksheet.
// Construct a new Worksheet instance and attach it to the named sheet. Worksheet wks1(strFullName); // Attach an existing Worksheet instance to the named sheet. wks2.Attach(strFullName);
A workbook contains a collection of worksheets. You can loop through all the worksheets in a specified workbook using the foreach statement.
WorksheetPage wksPage("Book1"); foreach(Layer wks in wksPage.Layers) out_str(wks.GetName());
You can also access a specified worksheet by its name or index.

//assume there are at least two worksheets on the page Book1, //and they are named Sheet1 and Sheet2 separately. WorksheetPage wksPage("Book1"); Worksheet wksFirst = wksPage.Layers(0); //by index Worksheet wksSecond = wksPage.Layers("Sheet2"); //by name
5.1.3
Reorder Worksheets
The Reorder method allows you to change the position of a worksheet in a workbook.
// This example assumes the active workbook contains two sheets // Get the active page from the active layer WorksheetPage wksPage; Worksheet wks = Project.ActiveLayer(); if( wks ) wksPage = wks.GetPage(); // Move the 2nd worksheet to the 1st position if( wksPage.Reorder(1, 0) ) out_str("Reorder sheets successfully");
5.1.4
Copying Worksheet
The Page::AddLayer method is used to copy a layer from one page to another, and can be used with GraphPage, WorksheetPage or MatrixPage. The following example shows how to drag all worksheets from the active folder to merge into the active workbook.
WorksheetPage wksPageDest = Project.Pages(); if( !wksPageDest ) // no active window or active window is not a worksheet return; bool bKeepSourceLayer = false; // delete source layer after copying Folder fld = Project.ActiveFolder(); foreach(PageBase pb in fld.Pages) {
55
5.1 Worksheets
WorksheetPage wbSource(pb); if(!wbSource) continue;//not a workbook if(wbSource.GetName() == wksPageDest.GetName()) continue;//skip our destination book // copy worksheet to destination book and delete it from source book foreach(Layer lay in wbSource.Layers) { Worksheet wks = lay; wksPageDest.AddLayer(wks, 0, bKeepSourceLayer); } wbSource.Destroy();// destroy the empty workbook }
5.1.5
Formatting a Worksheet
A worksheet can be formatted programmatically using a theme tree. The example below demonstrates obtaining and saving an existing theme tree:
// get format tree from worksheet Worksheet wks = Project.ActiveLayer(); Tree tr; tr = wks.GetFormat(FPB_ALL, FOB_ALL, TRUE, TRUE); out_tree(tr); // Output tree to Script window
Or, you may construct a theme tree as in the following three steps. First, create a worksheet and insert some data:
// Create worksheet Worksheet wks; wks.Create("Origin"); wks.SetCell(0, 0, "abc"); // Put text to (0, 0) cell // Establish data range to apply formatting: DataRange dr; int r1 = 0, c1 = 0, r2 = 4, c2 = 1; dr.Add("Range1", wks, r1, c1, r2, c2);
Second, construct the tree using the range information and provide values for desired properties:
Tree tr; // Setup the range that the format want to apply tr.Root.RangeStyles.RangeStyle1.Left.nVal = c1 + 1; tr.Root.RangeStyles.RangeStyle1.Top.nVal = r1 + 1; tr.Root.RangeStyles.RangeStyle1.Right.nVal = c2 + 1; tr.Root.RangeStyles.RangeStyle1.Bottom.nVal = r2 + 1; // Fill color tr.Root.RangeStyles.RangeStyle1.Style.Fill.FillColor.nVal = SYSCOLOR_LTCYAN; // Alignment of text in cell, 2 for center tr.Root.RangeStyles.RangeStyle1.Style.Alignment.Horizontal.nVal = 2; // The font size of text tr.Root.RangeStyles.RangeStyle1.Style.Font.Size.nVal = 11;
56
5.1.6 Merge Cells

// The color of text tr.Root.RangeStyles.RangeStyle1.Style.Color.nVal = SYSCOLOR_BLUE;
Third, apply the formatting to the data range:

// Apply the format to the specified data range if( 0 == dr.UpdateThemeIDs(tr.Root) ) // Returns 0 for no error { bool bRet = dr.ApplyFormat(tr, true, true); }
5.1.6
Merge Cells
We can use Origin C code to merge Worksheet cells with the specified range. The selected range can be data area or column label area. If you want to merge label cells, just change bLabels to true in the following code.
Worksheet wks; wks.Create("Origin"); //Define a Grid and attach it to the worksheet Grid gg; gg.Attach(wks); // to merge the first two rows in two columns ORANGE rng; rng.r1 = 0; rng.c1 = 0; rng.r2 = 1; rng.c2 = 1; bool bLabels = false; bool bRet = gg.MergeCells(rng, bLabels); if( bRet ) printf("Successfully merged cells in %s!\n", wks.GetName()); else printf("Failed to merge cells in %s!\n", wks.GetName());
5.2 Columns
Origin C provides the Column class for handling the columns in a worksheet. A Column object is usually used to control the style, format and data type of the dataset, which is contained in the column. Example codes, demonstrating how to use the Column class, are provided in the following sections.
57
5.2 Columns
5.2.1
Dimensions
Add Column to Worksheet

// Add column with default name int nColIndex = wks.AddCol(); // Add column with name string strName; int nColIndex = wks.AddCol("AA", strName); // Returns the index of column // If the column named AA already exist, name enumeration automatically out_str(strName); Column col(wks, nColIndex); // Construct column object by column index
Delete Column from Worksheet

// Delete the column by index wks.DeleteCol(0);
Insert Column into Worksheet

// Insert a new column as the first column int nPos = 0; // The position to insert string strNewCreated; // the real name of the new column // The name will be auto enumerated if name MyCol already existed if( wks.InsertCol(nPos, "MyCol", strNewCreated) ) { printf("Insert column successfully, name is %s\n", strNewCreated); }
Set Number of Rows and Columns

// Set the number of rows and columns, and data will be kept. // If want to add a lots of columns and rows at once time, better use SetSize int nNumRows = 100; int nNumCols = 20; wks.SetSize(nNumRows, nNumCols); // If want to change the number of rows but keep the number of columns, // can use -1 replace. For example: wks.SetSize(nNumRows, -1); // The same usage also used to change column number and keep row number.
5.2.2
Data Type, Format, SubFormat
Get & Set Data Type

Worksheet wks = Project.ActiveLayer(); Column col(wks, 0);
58
5.2.3 Data Manipulation

// Get column type, can be: // 0: Y // 1: None // 2: Y Error // 3: X // 4: L // 5: Z // 6: X Error int nType = col.GetType(); out_int("Type: ", nType); // Set column type. See more define OKDATAOBJ_DESIGNATION_* in oc_const.h col.SetType(OKDATAOBJ_DESIGNATION_Z);
Get & Set Data Format

// Get and set data format // The default format of column is OKCOLTYPE_TEXT_NUMERIC. // Set the format of column to Date if( OKCOLTYPE_DATE != col.GetFormat() ) { col.SetFormat(OKCOLTYPE_DATE); }
Get & Set Data Subformat

// Get and set data subformat // The options of the sub format will be different according to the above format, // numeric, date, time and so on. if( LDF_YYMMDD != col.GetSubFormat() ) { col.SetSubFormat(LDF_YYMMDD); }
5.2.3
Data Manipulation
Get & Set Numeric Data Values from Column

// Attach to the first column, make sure the format of the column is // Text & Numeric(default) or Numeric. Column col(wks, 0); // Here assume the data type of the column is double. // Other numeric data type supported, for example, int, short, complex. vector<double>& vec = col.GetDataObject(); // Append 100 at the end of this column vec.Add(100);
Or we can use a Dataset object to get and set numeric data for a column. For example:
Worksheet wks = Project.ActiveLayer(); Dataset ds(wks, 1); for(int ii=0; ii<ds.GetSize(); ii++)
59
5.2 Columns
out_double("", ds[ii]);
Get & Set String Values from Column

Column col(wks, 0); // Attach to the first column // Get string array from column vector<string> vs; col.GetStringArray(vs); // Put string array back to column vs.Add("test"); col.PutStringArray(vs);
5.2.4
Column Label
Worksheet column labels support Long Name, Units, Comments, Parameters and UserDefined labels. We can use Origin C code to show/hide labels or to add text to the specified column label.
Worksheet wks; wks.Create(); Grid gg; gg.Attach(wks); // if Parameters label not show, show it. bool bShow = gg.IsLabelsShown(RCLT_PARAM); if( !bShow ) gg.ShowLabels(RCLT_PARAM); wks.Columns(0).SetLongName("X Data"); wks.Columns(1).SetLongName("Y Data"); wks.Columns(0).SetComments("This is a test"); wks.Columns(0).SetUnits("AA"); wks.Columns(1).SetUnits("BB"); // put text to Parameters label for two columns. wks.Columns(0).SetExtendedLabel("Param A", RCLT_PARAM); wks.Columns(1).SetExtendedLabel("Param B", RCLT_PARAM);
RCLT_PARAM is the type of Parameters column label, other types see OriginC\system\oc_const.h file ROWCOLLABELTYPE enum.
60
5.2.5 Setting Value by Formula
5.2.5
Setting Value by Formula
The DataObject::SetFormula and DataObject::ExecuteFormula methods are used to set column/matrix values, which is the same as setting values in the Set Values dialog. The following example is of creating a worksheet with three columns, and then setting values by a formula to each column.
Worksheet wks; wks.Create("origin", CREATE_VISIBLE); wks.AddCol(); // set value to the first column Column colA; colA.Attach(wks, 0); colA.SetFormula("5*(i-1)"); colA.ExecuteFormula(); // for the next two columns we will set Recalculate = Auto Column colB; colB.Attach(wks, 1); colB.SetFormula("sin(4*col(A)*pi/180)", AU_AUTO); colB.ExecuteFormula(); // using declared variables in Before Formula Script Column colC; colC.Attach(wks, 2); string strExpression = "cos(Amp*x*pi/180)"; string strBeforeScript = "double Amp=4.5;" + "\r\n" + "range x=col(A);"; string strFormula = strExpression + STR_COL_FORMULAR_SEPARATOR + strBeforeScript; colC.SetFormula(strFormula, AU_AUTO); colC.ExecuteFormula();
5.3 Matrixsheets
Origin C provides the MatrixLayer class for working with a matrix sheet. A matrix sheet contains a collection of matrix objects.
5.3.1
Accessing a Matrix Object
// Attach to one matrix page by name MatrixPage matPage("MBook3"); // Attach to the sheet named MSheet1 from matrix page // Also support get sheet from matrix page by index MatrixLayer ml1 = matPage.Layers("MSheet1"); // Get a matrix object from sheet by index MatrixObject mo = ml1.MatrixObjects(0); // The data type of matrix object must keep consistent with the matrix window
61
5.4 Matrices
if( FSI_SHORT == mo.GetInternalDataType() ) { matrix<short>& mat = mo.GetDataObject(); }
5.3.2
Adding and Deleting a Matrix Object
// add matrix object to sheet MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet int nNum = 1; // the number of added matrix objects int nPos = -1; // -1, add as the end int nDataType = -1; // Optional, -1 as default for double type. int index = ml.Insert(nNum, nPos, nDataType); // Returns the index of the first one // delete matrix object from sheet MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet // Delete two matrix objects from the beginning int nPos = 0; int nNum = 2; ml.Delete(nPos, nNum);
5.3.3
Setting View as Data or Image
// set image view MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet int nImgIndex = 0; MatrixObject mo = ml.MatrixObjects(nImgIndex); if( !mo.IsImageView() ) { BOOL bAllObjs = FALSE; ml.SetViewImage(TRUE, bAllObjs, nImgIndex); }
5.4 Matrices
The Origin C MatrixObject class allows you to handle a matrix, including dimension, data type, data format, setting values, etc. Please refer to the related sections below.
5.4.1
Dimensions
Get Number of Rows and Columns in Matrix

// get num rows and cols MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet MatrixObject mo = ml.MatrixObjects(0); // Get the first matrix object
62
5.4.2 Data Type and Format

int nNumRows = mo.GetNumRows(); int nNumCols = mo.GetNumCols(); // Get the row number // Get the column number
Set Dimensions of Matrix

// set num rows and cols MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet MatrixObject mo = ml.MatrixObjects(0); // Get the first object int nNumRows = 5, nNumCols = 5; mo.SetSize(nNumRows, nNumCols); // Set dimensions by 5x5
5.4.2
Data Type and Format
Get & Set Data Type

// get and set data type MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet MatrixObject mo = ml.MatrixObjects(0); if( mo.GetInternalDataType() != FSI_BYTE ) // Get data type { // OCD_RESTORE to backup the data and // attempt to restore it after changing type DWORD dwFlags = OCD_RESTORE; mo.SetInternalDataType(FSI_BYTE, dwFlags); // Set data type }
Get & Set Data Format

// get and set data format MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet MatrixObject mo = ml.MatrixObjects(0); int nFormat = mo.GetFormat(); // Only OKCOLTYPE_NUMERIC( = 0) supported mo.SetFormat(OKCOLTYPE_NUMERIC);
5.4.3
Labels
A matrix label includes a Long Name, Units, and Comments for X, Y, Z. The labels of X and Y are for all matrix objects in the matrix sheet, the label of Z is for each matrix object. The following code shows how to get and set the labels.
Set XY Labels
MatrixPage mp("MBook1"); MatrixLayer ml = mp.Layers(0); // the first matrix sheet Tree tr; tr.Root.Dimensions.X.LongName.strVal = "X Values";
63
5.4 Matrices
tr.Root.Dimensions.X.Unit.strVal = "X Units"; tr.Root.Dimensions.X.Comment.strVal = "X Comment"; tr.Root.Dimensions.Y.LongName.strVal = "Y Values"; tr.Root.Dimensions.Y.Unit.strVal = "Y Units"; tr.Root.Dimensions.Y.Comment.strVal = "Y Comment"; // Note, set format on matrix sheet for XY labels. if( 0 == ml.UpdateThemeIDs(tr.Root) ) ml.ApplyFormat(tr, true, true);
Get XY Labels
MatrixPage mp("MBook1"); MatrixLayer ml = mp.Layers(0); // the first matrix sheet // Note, get XY labels from matrix sheet, not matrix object. Tree tr; tr = ml.GetFormat(FPB_ALL, FOB_ALL, TRUE, TRUE); TreeNode trX = tr.Root.Dimensions.X; if( !trX.LongName.IsEmpty() ) printf("X Long Name: %s\n", trX.LongName.strVal); if( !trX.Unit.IsEmpty() ) printf("X Unit: %s\n", trX.Unit.strVal); if( !trX.Comment.IsEmpty() ) printf("X Comment: %s\n\n", trX.Comment.strVal); TreeNode trY = tr.Root.Dimensions.Y; if( !trY.LongName.IsEmpty() ) printf("Y Long Name: %s\n", trY.LongName.strVal); if( !trY.Unit.IsEmpty() ) printf("Y Unit: %s\n", trY.Unit.strVal); if( !trY.Comment.IsEmpty() ) printf("Y Comment: %s\n", trY.Comment.strVal);
Set Z Labels
MatrixPage mp("MBook1"); MatrixLayer ml = mp.Layers(0); // the first matrix sheet MatrixObject mo = ml.MatrixObjects(0);// the first matrix object // construct format tree and assign string value to tree nodes Tree tr; tr.Root.LongName.strVal = "Z Long Name"; tr.Root.Unit.strVal = "Z Units"; tr.Root.Comment.strVal = "Z Comment"; // Note, here apply format on matrix object to set Z labels, not matrix sheet. if( 0 == mo.UpdateThemeIDs(tr.Root) ) // add id for each tree node mo.ApplyFormat(tr, true, true); // do apply
Get Z Labels
MatrixPage mp("MBook1"); MatrixLayer ml = mp.Layers(0); // the first matrix sheet
64
5.4.4 Data Values

MatrixObject mo = ml.MatrixObjects(0); Tree tr; tr = mo.GetFormat(FPB_ALL, FOB_ALL, TRUE, TRUE); printf("Z Short Name: %s\n", tr.Root.ShortName.strVal); if( !tr.Root.LongName.IsEmpty() )// if not empty printf("Z Long Name is %s\n", tr.Root.LongName.strVal); if( !tr.Root.Unit.IsEmpty() ) printf("Z Unit is %s\n", tr.Root.Unit.strVal); if( !tr.Root.Comment.IsEmpty() ) printf("Z Comment is %s\n", tr.Root.Comment.strVal);
5.4.4
Data Values
Multiply Matrix by Constant

MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet MatrixObject mo = ml.MatrixObjects(0); // Get the first matrix object //Get the reference of the internal data object of matrix window. //Here assume data type of the matrix is double. matrix<double>& mat = mo.GetDataObject(); // multiply 10 for each data in matrix, this change also effect on window mat = mat * 10;
Dot Multiply Two Matrix

// Attach to two matrix pages MatrixPage matPage1("MBook1"); MatrixPage matPage2("MBook2"); if( !matPage1 || !matPage2 ) return; // Get the matrix sheet from page by name or index MatrixLayer matLayer1 = matPage1.Layers("MSheet1"); MatrixLayer matLayer2 = matPage2.Layers(1); // get the second sheet if( !matLayer1 || !matLayer2 ) return; // Get matrix object from matrix sheet by index, name is not allowed. MatrixObject mo1 = matLayer1.MatrixObjects(0); MatrixObject mo2 = matLayer2.MatrixObjects(0); // Get the reference of the internal data object of matrix window matrix<double>& mat1 = mo1.GetDataObject(); matrix<double>& mat2 = mo2.GetDataObject(); // Prepare new matrix window MatrixPage matPageNew; matPageNew.Create("Origin"); MatrixLayer mlNew = matPageNew.Layers(0); MatrixObject moNew = mlNew.MatrixObjects(0); matrix<double>& matNew = moNew.GetDataObject();
65
5.5 Virtual Matrix

// Copy values from mat1 to new matrix matNew = mat1; // Multiply two matrices element by element and put result // to a newly created matrix window matNew.DotMultiply(mat2);
5.4.5
Setting Value by Formula
The DataObject::SetFormula and DataObject::ExecuteFormula methods are used to set column/matrix values, which is the same as setting values in the Set Values dialog. The example below shows how to set values to a matrix object by formula.
// new a matrix window MatrixPage matPage; matPage.Create("Origin"); MatrixLayer ml = matPage.Layers(); // get active matrix sheet // set formula and execute MatrixObject mo = ml.MatrixObjects(0); //get first matrixobject mo.SetFormula("sin(i) + cos(j)"); mo.ExecuteFormula();
5.5 Virtual Matrix

You can construct a virtual matrix from a worksheet window. Pick separate data ranges from the worksheet for X, Y, Z data of the virtual matrix. If you do not specify X and Y data, it will automatically use default data. The following code shows how to construct a virtual matrix from an active worksheet window, and then plot this virtual matrix on a graph.
// before running, make sure there is active worksheet window with data. // For example, new a worksheet window, import XYZ Random Gaussian.dat from // Origin folder Samples\Matrix Conversion and Gridding subfolder to worksheet. Worksheet wks = Project.ActiveLayer(); int r1, r2; int c1 = 0, c2 = 2; wks.GetBounds(r1, c1, r2, c2); // construct a data range object only with Z data, X and Y data will be auto // assigned. DataRange dr; dr.Add("Z", wks, r1, c1, r2, c2); MatrixObject mo; mo.Attach(dr); int nRows = mo.GetNumRows(); int nCols = mo.GetNumCols(); // get the default x, y range
66
5.6.1 Getting Worksheet Selection

double xmin, xmax, ymin, ymax; mo.GetXY(xmin, ymin, xmax, ymax); GraphPage gp; gp.Create("CONTOUR"); GraphLayer gl = gp.Layers(0); gl.AddPlot(mo, IDM_PLOT_CONTOUR); gl.Rescale(); mo.Detach();
If you want to assign X and Y data then the data should be monotone. The following example shows how to construct a virtual matrix with an XYZ data range.
// Assume the active layer is a worksheet with 5 columns of data. Worksheet wks = Project.ActiveLayer(); // Get min and max row indices for columns 0 to 4. int r1, r2, c1 = 0, c2 = 4; wks.GetBounds(r1, c1, r2, c2); // Create a data DataRange dr; dr.Add("X", wks, dr.Add("Y", wks, dr.Add("Z", wks, MatrixObject mo; mo.Attach(dr); range object with XYZ data. 0, 1, 0, c2); // First row except the first cell 1, 0, r2, 0); // First column except the first cell 1, 1, r2, c2);
5.6 Data Manipulation

5.6.1 Getting Worksheet Selection
Worksheet::GetSelectedRange can be used to get one or multiple selected data ranges from a worksheet. The following code shows how to get data from one column by worksheet selection. This function returns range type, like one column, one row, whole worksheet, etc.
Worksheet wks = Project.ActiveLayer(); int r1, c1, r2, c2; int nRet = wks.GetSelectedRange(r1, c1, r2, c2); if( WKS_SEL_ONE_COL & nRet ) // exactly one column selected { // construct a data range object by selection DataRange dr; dr.Add("X", wks, r1, c1, r2, c2); // get data from the selected column vector vData; dr.GetData(&vData, 0); }
67
5.6.2
Setting Display Range in Worksheet
If you want to set a display range in a Worksheet, you can use Worksheet::SetBounds, and it is the same as using the Set As Begin/End menu. The following code shows how to set a beginning and end for all columns in the current worksheet window.
Worksheet wks = Project.ActiveLayer(); // the beginning and end of rows int begin = 9, end = 19; // set beginning and end for all columns int c1 = 0, c2 = -1; // -1 means end wks.SetBounds(begin, c1, end, c2);
5.6.3
Putting Large Dataset to Worksheet
In order to keep an Origin C function running efficiently when working with a large data set (e.g. 1000 columns) in a worksheet, use the steps below.
Prepare the columns and rows before putting data into the worksheet. Use Worksheet::SetSize, don't use Worksheet::AddCol to set the size. Set the size on an empty worksheet, meaning no columns and rows, since otherwise Origin will need to check the short names of the existing columns to avoid duplicate names when adding new columns, and this could cost you lots of time. You can use while( wks.DeleteCol(0) ); to remove all columns to make an empty Worksheet. Put data into worksheet columns by buffer, DataObject::GetInternalDataBuffer. Keep Code Builder closed when running functions to improve the speed of execution.
See the following example codes:

// prepare worksheet size Worksheet wks; wks.Create("Origin"); while( wks.DeleteCol(0) ); int rows = 100, cols = 1000; wks.SetSize(rows, cols);
// put data set into worksheet columns one by one foreach(Column col in wks.Columns) { col.SetFormat(OKCOLTYPE_NUMERIC); col.SetInternalData(FSI_SHORT); col.SetUpperBound(rows-1);//index of last row, 0 offset int nElementSize; uint nNum; LPVOID pData = col.GetInternalDataBuffer(&nElementSize, &nNum); short* psBuff = (short*)pData; // OC loop is still slow, but you might pass this pointer to your DLL // for much faster manipulation, here we just show that the pointer works for(int ii = 0; ii < rows; ii++, psBuff++)
68
5.6.4 Accessing Embedded Graph in a Worksheet

{ *psBuff = (ii+1) * (col.GetIndex()+1); } col.ReleaseBuffer(); // do NOT remember to call this }
5.6.4
Accessing Embedded Graph in a Worksheet
Create a new graph and a new worksheet, and then embed the graph within one of the worksheet's cells:
GraphPage gp; gp.Create("Origin"); Worksheet wks; wks.Create(); int nOptions = EMBEDGRAPH_KEEP_ASPECT_RATIO | EMBEDGRAPH_HIDE_LEGENDS; // Put the graph in worksheet cell (0, 0) wks.EmbedGraph(0, 0, gp, nOptions);
Access a graph that is embedded within a worksheet; by name or by index:

// Get embedded graph from active worksheet Worksheet wks = Project.ActiveLayer(); GraphPage gp; gp = wks.EmbeddedPages(0); // Get embedded graph page by index gp = wks.EmbeddedPages("Graph1"); // Get embedded graph page by name
5.6.5
Sorting Worksheet Data
Perform a row-wise sort of column data with the Sort method. For sorting a single column, use the vectorbase::Sort method:
// Sort column // Before running, please keep active worksheet with two columns fill with data. // For example, import \Samples\Mathematics\Sine Curve.dat to worksheet. Worksheet wks = Project.ActiveLayer(); Column colY(wks, 1); // Y column // After sort, the original relation for (x, y) will be broken. vectorbase& vec = colY.GetDataObject(); vec.Sort();
To sort all columns in a worksheet, use the Worksheet::Sort method:

// Sort worksheet // Before running, please keep active worksheet with two columns fill with data. // For example, import \Samples\Mathematics\Sine Curve.dat to worksheet. Worksheet wks = Project.ActiveLayer(); int nCol = 1; // Ascending sort all worksheet data on the second column BOOL bIsAscending = true; BOOL bMissingValuesSmall = TRUE; // Treat missing value as smallest
69

int r1 = 0, c1 = 0, r2 = -1, c2 = -1; // -1 means end for r2 and c2 // After sort, each (x, y) still keep the original relation wks.Sort(nCol, bIsAscending, bMissingValuesSmall, r1, c1, r2, c2);
5.6.6
Masking Worksheet Data
The following code shows how to set a mask on the rows of data that are less than or equal to 0 for the specified column.
int nCol = 1; Worksheet wks = Project.ActiveLayer(); Column col(wks, nCol); vector vData = col.GetDataObject(); // to find all less than and equal 0 and return row index vector<uint> vnRowIndex; vData.Find(MATREPL_TEST_LESSTHAN | MATREPL_TEST_EQUAL, 0, vnRowIndex); // construct a range including multiple subranges added by row and column index DataRange dr; for(int nn = 0; nn < vnRowIndex.GetSize(); nn++) { int r1, c1, r2, c2; r1 = r2 = vnRowIndex[nn]; c1 = c2 = nCol; dr.Add("X", wks, r1, c1, r2, c2); } // set mask on data range dr.SetMask();
5.6.7
Extracting Data from Worksheet with LT Condition
Select worksheet data using the Worksheet::SelectRows method. Rows can be selected across many columns.
// Select data from a worksheet based on a condition; // put the indices of the selected rows into a vector of type 'uint'. Worksheet wks = Project.ActiveLayer(); // Check the worksheet data based on the condition expression and // output the row index into 'vnRowIndices'. // Define Labtalk range objects, 'a' = column 1, 'b' = column 2. string strLTRunBeforeloop = "range a=1; range b=2"; string strCondition = "abs(a) >= 1 && abs(b) >= 1"; vector<uint> vnRowIndices; // This is output int r1 = 0, r2 = -1; // The row range, -1 means the last row for r2 // Optional maximum number of rows to select, -1 indicates no limit int nMax = -1; int num = wks.SelectRows(strCondition, vnRowIndices, r1, r2, nMax, strLTRunBeforeloop);
There are two ways to highlight the selection. The first is to highlight the selected indices.
70 Workbooks and Matrixbooks
5.6.8 Comparing Data in Two Worksheets

// Method 1 of show selection: highlight rows by vnRowIndices Grid gg; if( gg.Attach(wks) ) { // convert uint type vector to int type vector vector<int> vnRows; vnRows = vnRowIndices; gg.SetSelection(vnRows); }
The second method of highlighting a data selection is to prescribe a fill color for the selected rows.
// Method 2 of show selection: fill color on the selected rows by vnRowIndices DataRange dr; // Construct data ranges by the row indices in vnRowIndices. for(int index=0; index<vnRowIndices.GetSize(); index++) { // The following 0(1st col) and -1(last col) for all columns // "" for range name variable, not specified, default name will be used dr.Add("", wks, vnRowIndices[index], 0, vnRowIndices[index], -1); } Tree tr; tr.Root.CommonStyle.Fill.FillColor.nVal = SYSCOLOR_BLUE; // fill color = blue tr.Root.CommonStyle.Color.nVal = SYSCOLOR_WHITE; // font color = white if( 0 == dr.UpdateThemeIDs(tr.Root) ) // Return 0 for no error { bool bRet = dr.ApplyFormat(tr, true, true); }
5.6.8
Comparing Data in Two Worksheets
It may be useful to compare the number of rows or columns between two worksheets, or compare the data themselves. Get a row or column count from a worksheet with the GetNumRows and GetNumCols methods.
if( wks1.GetNumRows() != wks2.GetNumRows() || wks1.GetNumCols() != wks2.GetNumCols() ) { out_str("The two worksheets are not the same size"); return; }
Another way to perform a similar operation is to copy the data from each worksheet into a vector, and compare the size of the vectors.
// get all data from worksheet 1 columns one by one vector vec1; foreach(Column col in wks1.Columns) { vector& vecCol = col.GetDataObject(); vec1.Append(vecCol); }
71
5.7 Data Transformation

// get all data from worksheet 2 columns one by one vector vec2; foreach(col in wks2.Columns) { vector& vecCol = col.GetDataObject(); vec2.Append(vecCol); } if( vec1.GetSize() != vec2.GetSize() ) { out_str("The size of the two data sets is not equal"); return; }
To compare data elements themselves, use the ocmath_compare_data function on the vectors in the example above.
bool bIsSame = false; double dTolerance = 1e-10; ocmath_compare_data(vec1.GetSize(), vec1, vec2, &bIsSame, dTolerance); if( bIsSame ) { out_str("Data in the two worksheets are the same"); }

5.7.1
1.
Worksheet Gridding
Run the following command in the Command Window to compile the nag_utils.c file and add it into the current workspace Run.LoadOC(Originlab\nag_utils.c, 16);
2.
Include header files in the Origin C file. #include <wks2mat.h> #include <Nag_utils.h>
3.
Get XYZ data from the active worksheet XYZ columns. // Construct XYZ data range from XYZ columns XYZRange rng; rng.Add(wks, 0, "X"); rng.Add(wks, 1, "Y"); rng.Add(wks, 2, "Z"); // Get XYZ data from data range objects to vectors vector vX, vY, vZ; rng.GetData(vZ, vY, vX);
72
5.7.1 Worksheet Gridding

4. Examine source data type, for example: regular, sparse. UINT nVar; double xmin, xstep, xmax, ymin, ystep, ymax; int nSize = vX.GetSize(); int nMethod = ocmath_xyz_examine_data(nSize, vX, vY, vZ, 1.0e-8, 1.0e-8, &nVar, &xmin, &xstep, &xmax, &ymin, &ystep, &ymax); 5. Calculate the number of rows and columns for the result matrix window. int nRows = 10, nCols = 10; if( 0 == nMethod || 1 == nMethod ) // Regular or sparse { double dGap = 1.5; if( !is_equal(ystep, 0) ) nRows = abs(ymax - ymin)/ystep + dGap; if( !is_equal(xstep, 0) ) nCols = abs(xmax - xmin)/xstep + dGap; } 6. Prepare the result matrix window. // Prepare matrix window to put gridding result MatrixPage mp; mp.Create("origin"); // Create matrix window MatrixLayer ml = mp.Layers(0); // Get the first matrix sheet MatrixObject mo(ml, 0); // Get the first matrix object mo.SetXY(xmin, ymin, xmax, ymax); // Set the from/to for X and Y mo.SetSize(nRows, nCols); // Set the number of rows and columns 7. Do XYZ gridding with the different method types. matrix& mat = mo.GetDataObject(); // Get data object from matrix object int iRet; switch(nMethod) { case 0: // Regular iRet = ocmath_convert_regular_xyz_to_matrix(nSize, vX, vY, vZ, mat, xmin, xstep, nCols, ymin, ystep, nRows); printf("--- %d: regular conversion ---\n", iRet); break; case 1: // Sparse iRet = ocmath_convert_sparse_xyz_to_matrix(nSize, vX, vY, vZ, mat, xmin, xstep, nCols, ymin, ystep, nRows);
73

printf("--- %d: sparse conversion ---\n", iRet); break; case 2: // Random(Renka Cline) vector vxGrid(nRows*nCols), vyGrid(nRows*nCols); iRet = ocmath_mat_to_regular_xyz(NULL, nRows, nCols, xmin, xmax, ymin, ymax, vxGrid, vyGrid); if( iRet >= 0 ) { iRet = xyz_gridding_nag(vX, vY, vZ, vxGrid, vyGrid, mat); } printf("--- %d: random conversion ---\n", iRet); break; default: // Error. printf("--- Error: Other method type ---\n"); }
74
Graphs
The GraphPage class is for working with a graph window. There is a GraphPage object for each graph window. A GraphPage object contains a collection of layers. Each of these layers is a GraphLayer object. Accessing an Existing Graph There are multiple ways to access an existing graph. The methods used are the same as those used for workbooks and matrix books. You can access a graph by passing its name to the class constructor.
GraphPage grPg("Graph1"); if( grPg ) // if there is a graph named "Graph1" grPg.SetName("MyGraph1"); // rename the graph
The Project class contains a collection of all the graphs in the project. The following example shows how to loop through the collection and output the name of each graph.
foreach(GraphPage grPg in Project.GraphPages) out_str(grPg.GetName()); // output graph name
You can access a graph by passing its zero-based index to the Item method of the Collection class.
GraphPage grPg; grPg = Project.GraphPages.Item(2); if( grPg ) // if there is a 3rd graph out_str(grPg.GetName()); // output graph name
Deleting a Graph All Origin C's internal classes are derived from the OriginObject class. This class has a Destroy method that is used to destroy the object. Calling this method on a graph will destroy the graph, all the layers in the graph, and all the graph objects on each layer.
GraphPage grPg; grPg = Project.GraphPages.Item(0); // get first graph in project if( grPg ) // if there is a graph grPg.Destroy(); // delete the graph
6.1 Creating and Customizing Graph

6.1.1 Creating Graph Window
The Create method is used for creating new graphs.

GraphPage gp; gp.Create("3D"); // create a graph using the 3D template
75
6.1.2
Getting Graph Page Format
GraphPage gp("Graph1"); Tree tr; tr = gp.GetFormat(FPB_ALL, FOB_ALL, true, true); out_tree(tr);
6.1.3
Setting Graph Page Format
The following example code shows how to set page background color as a gradient in two colors.
Tree tr; tr.Root.Background.BaseColor.nVal = SYSCOLOR_RED; tr.Root.Background.GradientControl.nVal = 1; tr.Root.Background.GradientColor.nVal = SYSCOLOR_BLUE; GraphPage gp("Graph1"); if(0 == gp.UpdateThemeIDs(tr.Root) ) gp.ApplyFormat(tr, true, true);
6.1.4
Getting Graph Layer Format
GraphLayer gl = Project.ActiveLayer(); Tree tr; tr = gl.GetFormat(FPB_ALL, FOB_ALL, true, true); out_tree(tr);
6.1.5
Setting Graph Layer Format
The following example code shows how to set the background of a graph layer object to Black Line format.
GraphLayer gl = Project.ActiveLayer(); Tree tr; tr.Root.Background.Border.Color.nVal = SYSCOLOR_BLACK; tr.Root.Background.Border.Width.nVal = 1; tr.Root.Background.Fill.Color.nVal = SYSCOLOR_WHITE; if( 0 == gl.UpdateThemeIDs(tr.Root) ) gl.ApplyFormat(tr, true, true);
6.1.6
Show Additional Lines
This example shows how to show additional lines, the Y=0/X=0 line, and the opposite line.
GraphLayer gl = Project.ActiveLayer();
76
Graphs
6.1.7 Show Grid Lines

Axis axesX = gl.XAxis; axesX.Additional.ZeroLine.nVal = 1; // Show Y = 0 line axesX.Additional.OppositeLine.nVal = 1; // Show X Axes opposite line
6.1.7
Show Grid Lines
This example shows how to set gridlines to show, and how to color them. Color values can be an index into Origin's internal color palette or an RGB value. See Color in the Data Types and Variables section for more information about working with color values.
GraphLayer gl = Project.ActiveLayer(); Axis axisY = gl.YAxis; Tree tr; // Show major grid TreeNode trProperty = tr.Root.Grids.HorizontalMajorGrids.AddNode("Show"); trProperty.nVal = 1; tr.Root.Grids.HorizontalMajorGrids.Color.nVal = RGB2OCOLOR(RGB(100, 100, 220)); tr.Root.Grids.HorizontalMajorGrids.Style.nVal = 1; // Solid tr.Root.Grids.HorizontalMajorGrids.Width.dVal = 1; // Show minor grid trProperty = tr.Root.Grids.HorizontalMinorGrids.AddNode("Show"); trProperty.nVal = 1; tr.Root.Grids.HorizontalMinorGrids.Color.nVal = SYSCOLOR_GREEN; // Green tr.Root.Grids.HorizontalMinorGrids.Style.nVal = 2; // Dot tr.Root.Grids.HorizontalMinorGrids.Width.dVal = 0.3; if(0 == axisY.UpdateThemeIDs(tr.Root) ) { bool bRet = axisY.ApplyFormat(tr, true, true); }
6.1.8
Setting Axis Scale
This example shows how to set scale parameters, increment, type and so on.
GraphLayer gl = Project.ActiveLayer(); Axis axesX = gl.XAxis; axesX.Scale.From.dVal = 0; axesX.Scale.To.dVal = 1; axesX.Scale.IncrementBy.dVal = 0.2; axesX.Scale.Type.nVal = 0;// Linear axesX.Scale.Rescale.nVal = 0; // Rescake type axesX.Scale.RescaleMargin.dVal = 8; // precent 8
6.1.9
Getting Axis Format
GraphLayer gl = Project.ActiveLayer(); Axis axisX = gl.XAxis;
Graphs
77

// Get all axis format settings to tree Tree tr; tr = axisX.GetFormat(FPB_ALL, FOB_ALL, true, true); out_tree(tr);
6.1.10 Setting Axis Label

An axis label is an ordinary text object and is accessed in Origin C using the GraphObject class. On a default graph the X axis is named XB and the Y axis is named YL. The following code shows how to access the X and Y axis labels and assumes a default graph is the active page.
GraphLayer gl = Project.ActiveLayer(); // Get active graph layer GraphObject grXL = gl.GraphObjects("XB"); // Get X axis label GraphObject grYL = gl.GraphObjects("YL"); // Get Y axis label
Now that we have access to the axis labels we can change their values. The following code sets the X axis label directly and sets the Y axis label indirectly by linking it to a LabTalk string variable. Linking to a LabTalk variable requires the label's Programming Control option "Link to variables" to be turned on. This option is on by default.
grXL.Text = "My New X Asis Label"; LT_set_str("abc$", "My String Variable"); grYL.Text = "%(abc$)";
To make sure the label changes appear, it may be necessary to refresh the graph page. With our GraphLayer object we can refresh the page with the following code.
gl.GetPage().Refresh();
6.1.11 Show Top Axis

This example shows how to show X top axes.
// Show axes and ticks Tree tr; TreeNode trProperty = tr.Root.Ticks.TopTicks.AddNode("Show"); trProperty.nVal = 1; // Show tick labels trProperty = tr.Root.Labels.TopLabels.AddNode("Show"); trProperty.nVal = 1; GraphLayer gl = Project.ActiveLayer(); Axis axesX = gl.XAxis; if(0 == axesX.UpdateThemeIDs(tr.Root) ) { bool bRet = axesX.ApplyFormat(tr, true, true); }
78
Graphs
6.1.12 Customizing Axis Ticks
6.1.12 Customizing Axis Ticks

This example shows how to set the format in the Axis dialog -> Title & Format tab.
GraphLayer gl = Project.ActiveLayer(); Axis axesX = gl.XAxis; Tree tr; // Set ticks color as Auto, depend on the color of data plot tr.Root.Ticks.BottomTicks.Color.nVal = INDEX_COLOR_AUTOMATIC; tr.Root.Ticks.BottomTicks.Width.dVal = 3; tr.Root.Ticks.BottomTicks.Major.nVal = 0; // 0: In and Out tr.Root.Ticks.BottomTicks.Minor.nVal = 2; // 2: Out tr.Root.Ticks.BottomTicks.Style.nVal = 0; // Solid if(0 == axesX.UpdateThemeIDs(tr.Root) ) bool bRet = axesX.ApplyFormat(tr, true, true);
6.1.13 Customizing Tick Labels

This example shows how to set tick labels with custom positions. It performs the same action as going in the Axis dialog Custom Tick Labels tab.
GraphLayer gl = Project.ActiveLayer(); Axis axesX = gl.XAxis; Tree tr; // Show axes begin and end as scale value tr.Root.Labels.BottomLabels.Custom.Begin.Type.nVal = 2; tr.Root.Labels.BottomLabels.Custom.End.Type.nVal = 2; // Set special point as Manual type with the special value and text. tr.Root.Labels.BottomLabels.Custom.Special.Type.nVal = 3; tr.Root.Labels.BottomLabels.Custom.Special.Label.strVal = "Mid"; tr.Root.Labels.BottomLabels.Custom.Special.Value.dVal = 12; if(0 == axesX.UpdateThemeIDs(tr.Root) ) { bool bRet = axesX.ApplyFormat(tr, true, true); }
6.2 Adding Data Plots

Plots or Data plots are representations of your data within a graph layer. Each graph layer may contain one or more plots.
Graphs
79
6.2.1
2D Plot (XY, YErr, Bar/Column)
Plot XY Scatter
The following code shows how to construct an XYYErr data range from the active worksheet, and then plot the data range in a newly created graph.
Worksheet wks = Project.ActiveLayer(); // The range name must be X, Y, Z or ED(for YErr) to make sense. DataRange dr; dr.Add(wks, 0, "X"); // 1st column for X data dr.Add(wks, 1, "Y"); // 2nd column for Y data dr.Add(wks, 2, "ED"); // Optional, 3th column for Y Error data // Create a graph window GraphPage gp; gp.Create("Origin"); GraphLayer gl = gp.Layers(); // Get active layer // Plot XY data range as scatter // IDM_PLOT_SCATTER is plot type id, see other types plot id in oPlotIDs.h file. int nPlotIndex = gl.AddPlot(dr, IDM_PLOT_SCATTER); // Returns plot index (offset is 0), else return -1 for error if( nPlotIndex >= 0 ) { gl.Rescale(); // Rescale axes to show all data points }
Attach YErr Plot

Attach YErr data to an existing XY data plot.
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(-1); // Get active data plot // Get Y Error column WorksheetPage wksPage("Book1"); Worksheet wks = wksPage.Layers(); Column colErrBar(wks, 2); // Plot Y Error column to the active data plot Curve crv(dp); int nErrPlotIndex = gl.AddErrBar(crv, colErrBar); out_int("nErrPlotIndex = ", nErrPlotIndex);
Bar/Column Plot
// before running make sure the active window is worksheet Worksheet wks = Project.ActiveLayer(); DataRange dr; dr.Add(wks, 1, "Y"); // Construct data range with one column GraphPage gp; gp.Create("BAR"); // Create graph with the specified template
80
Graphs
6.2.2 3D Plot
GraphLayer gl = gp.Layers(-1); // Get active graph layer int index = gl.AddPlot(dr, IDM_PLOT_BAR); if( index >= 0 ) { out_str("Plot bar"); gl.Rescale(); }
6.2.2
3D Plot
Plot a 3D surface from a matrix on a graph window.

// Prepare matrix data MatrixLayer ml; string strFile = GetAppPath(true) + "Samples\\Matrix Conversion and Gridding\\ 2D Gaussian.ogm"; ml.Open(strFile); MatrixObject mo = ml.MatrixObjects(0); // Create graph page with template GraphPage gp; gp.Create("CMAP"); GraphLayer gl = gp.Layers(0); // Plot 3D surface int nPlotIndex = gl.AddPlot(mo, IDM_PLOT_SURFACE_COLORMAP); if(0 == nPlotIndex) { gl.Rescale(); printf("3D Surface plotted successfully\n"); }
6.2.3
Contour Plot
Plot XYZ Contour

// Before running, make sure there are XYZ columns with data in the active // worksheet window. Or you can import \Samples\Matrix Conversion and Gridding\ // XYZ Random Gaussian.dat into worksheet. Worksheet wks = Project.ActiveLayer(); DataRange dr; dr.Add(wks, 0, "X"); dr.Add(wks, 1, "Y"); dr.Add(wks, 2, "Z"); // Create graph with template GraphPage gp; gp.Create("TriContour"); GraphLayer gl = gp.Layers(); // Plot XYZ contour with type id int nPlot = gl.AddPlot(dr, IDM_PLOT_TRI_CONTOUR); if( nPlot >= 0 ) {
Graphs
81

gl.Rescale(); printf("XYZ contour plotted successfully\n"); }
Plot Color Fill Contour

MatrixLayer ml = Project.ActiveLayer(); MatrixObject mo = ml.MatrixObjects(0); // Create graph window with template GraphPage gp; gp.Create("contour"); GraphLayer gl = gp.Layers(); int nPlot = gl.AddPlot(mo, IDM_PLOT_CONTOUR); if( nPlot >= 0 ) { gl.Rescale(); }
6.2.4
Image Plot
MatrixLayer ml = Project.ActiveLayer(); MatrixObject mo = ml.MatrixObjects(0); // Create graph window with template GraphPage gp; gp.Create("image"); GraphLayer gl = gp.Layers(); int nPlot = gl.AddPlot(mo, IDM_PLOT_MATRIX_IMAGE); if( nPlot >= 0 ) { gl.Rescale(); }
6.2.5
Multi-Axes
The following example code shows how to show/hide and set format on the four axes - left, bottom, right, and top in one graph layer.
#include <..\Originlab\graph_utils.h> // needed for AXIS_* GraphLayer gl = Project.ActiveLayer(); // Show all axes and labels. 0 or 1, 1 for show. vector<int> vnAxes(4), vnLabels(4), vnTitles(4); vnAxes[AXIS_BOTTOM] = 1; vnAxes[AXIS_LEFT] = 1; vnAxes[AXIS_TOP] = 1; vnAxes[AXIS_RIGHT] = 1; vnLabels = vnAxes; // Show axis titles of left and bottom axes. 0 or 1, 1 for show. vnTitles[AXIS_BOTTOM] = 1;
82
Graphs
6.2.6 Multi-Panels (Multi-Layer, with Shared X-Axis)

vnTitles[AXIS_LEFT] = 1; vnTitles[AXIS_TOP] = 0; vnTitles[AXIS_RIGHT] = 0; // Set the major tick and minor tick of all axes as IN format // See other TICK_* items in graph_utils.h. vector<int> vnMajorTicks(4), vnMinorTicks(4); vnMajorTicks[AXIS_BOTTOM] = TICK_IN; vnMajorTicks[AXIS_LEFT] = TICK_IN; vnMajorTicks[AXIS_TOP] = TICK_IN; vnMajorTicks[AXIS_RIGHT] = TICK_IN; vnMinorTicks = vnMajorTicks; gl_smart_show_object(gl, vnAxes, vnLabels, vnTitles, vnMajorTicks, vnMinorTicks);
6.2.6
Multi-Panels (Multi-Layer, with Shared X-Axis)
The following example shows how to construct multiple graph layers in one graph page, all layers sharing the x axis in one layer, then plot XY data sets one by one from a worksheet to each graph layer. Before compiling the following codes, you need to run this command to build the graph_utils.c file to your current workspace.
run.LoadOC(Originlab\graph_utils.c, 16);
Compile the following Origin C code. Before running, make sure there is a workbook named Book1, and it has one X column and at least two Y columns.
#include <..\Originlab\graph_utils.h> // needed for page_add_layer function // Construct data range from Book1 WorksheetPage wksPage("Book1"); Worksheet wks = wksPage.Layers(0); // get the first worksheet in Book1 DataRange dr; dr.Add(wks, 0, "X"); // 1st column as X data dr.Add(wks, 1, "Y", -1); // 2nd column to last one for Y data // Get the number of Y DWORD dwRules = DRR_GET_DEPENDENT | DRR_NO_FACTORS; int nNumYs = dr.GetNumData(dwRules); // Add more layers with right Axis and link to the 1st layer GraphPage gp; gp.Create("Origin"); while ( gp.Layers.Count() < nNumYs ) { page_add_layer(gp, false, false, false, true, ADD_LAYER_INIT_SIZE_POS_MOVE_OFFSET, false, 0, LINK_STRAIGHT); } // Loop and add plot from each XY data range to graph layer foreach(GraphLayer gl in gp.Layers) { int nLayerIndex = gl.GetIndex(); // Get the sub XY range from dr DataRange drOne; dr.GetSubRange(drOne, dwRules, nLayerIndex);
Graphs
83
6.3 Customizing Data Plots

// Plot one XY range to graph layer int nPlot = gl.AddPlot(drOne, IDM_PLOT_LINE); if( nPlot >= 0 ) { DataPlot dp = gl.DataPlots(nPlot); dp.SetColor(nLayerIndex); // Set data plot as different color // Set the ticks and ticklabels of right Y axis auto color gl.YAxis.AxisObjects(AXISOBJPOS_AXIS_SECOND).RightTicks.Color.nVal = gl.YAxis.AxisObjects(AXISOBJPOS_LABEL_SECOND).RightLabels.Color.nVal = INDEX_COLOR_AUTOMATIC; gl.Rescale(); } }

6.3.1 Adding Data Marker
Origin C supports the following methods for customizing data markers. DataPlot::AddDataMarkers to add a data marker on the data plot to select a sub range DataPlot::SetDataMarkers to change the position of the present data marker DataPlot::GetDataMarkers to get all existing data plots DataPlot::RemoveDataMarker to remove the specified data marker. The following code shows how to add two data markers to the active graph window.
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(); // the indices of the data markers vector<int> vnBegin = {0, 9}; vector<int> vnEnd = {4, 14}; // to add two data markers int nRet = dp.AddDataMarkers(vnBegin, vnEnd); if( 0 == nRet ) { out_str("Add data marker successfully."); }
The code below shows how to change the position of the present data marker.
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(); // the indices of the data markers vector<int> vnBegin = {11, 2}; vector<int> vnEnd = {19, 5}; vector<int> vnIndices = {1, 0};
84
Graphs
6.3.2 Setting Color

// to add two data markers int nRet = dp.SetDataMarkers(vnBegin, vnEnd, vnIndices); if( 0 == nRet ) { out_str("Set data marker successfully."); gl.GetPage().Refresh(); }
6.3.2
Setting Color
The following code shows how to set the color of the data plot.
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(0); bool bRepaint = true; dp.SetColor(SYSCOLOR_GREEN, bRepaint);
6.3.3
Getting Format Tree
OriginObject::GetFormat and OriginObject::ApplyFormat are used to get and set Origin object formats. The following getting, setting and copying format mechanisms can be used for all Origin objects whose classes derive from the OriginObject base class (see Reference: Class Hierarchy). For example, the Origin objects can be objects of the DataPlot class, Worksheet class, WorksheetPage class, MatrixLayer class, MatrixPage class, GraphLayer class, or GraphPage class. The DataPlot class derives from the DataObjectBase class, and the DataObjectBase class derives from the OriginObject class, so we can call DataPlot::GetFormat to get the format tree structure. There are two ways to see the format tree structure via the following code.
Set a break point on the GetFormat line in the following code, activate one data plot, run the code, press F10 (Step Over) to execute the GetFormat line, and see the details of the format tree in the Code Builder Local Variables Window tr variable. (press Alt+4 to open/hide the Local Variables window). Use the last line, out_tree(tr);, to print out the format tree. GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(-1); // Get the active data plot // Different plot types(for example, Line, Box Chart...) have // different structure in the format tree. Tree tr; // Get the format tree to see details of the tree structure. tr = dp.GetFormat(FPB_ALL, FOB_ALL, true, true); out_tree(tr); // print out the format tree.
Graphs
85
6.3.4
Setting Format on Line Plot
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(-1); // Get the active data plot // Set format on a line plot // Note: See the previous section to get the structure of format tree Tree tr; tr.Root.Line.Connect.nVal = 2; // 2 for 2 point segment tr.Root.Line.Color.nVal = RGB2OCOLOR(RGB(100, 100, 220)); tr.Root.Line.Width.dVal = 1.5; if( 0 == dp.UpdateThemeIDs(tr.Root) ) { bool bRet = dp.ApplyFormat(tr, true, true); }
6.3.5
Copying Format from One Data Plot to Another
Copying Format via Theme File

Getting and saving a format tree from a data plot into a theme file, then loading the theme file to a tree and applying the format tree to another data plot.
// Save plot settings from Graph1 to a theme file GraphPage gpSource("Graph1"); GraphLayer glSource = gpSource.Layers(0); DataPlot dpSource = glSource.DataPlots(0); Tree tr; tr = dpSource.GetFormat(FPB_ALL, FOB_ALL, true, true); string strTheme = GetAppPath(false) + "plotsettings.XML"; tr.Save(strTheme); // Load plot settings from a theme file to a tree, and apply format from // tree to data plot object. GraphPage gpDest("Graph2"); GraphLayer glDest = gpDest.Layers(0); DataPlot dpDest = glDest.DataPlots(0); Tree tr2; tr2.Load(strTheme); dpDest.ApplyFormat(tr2, true, true);
Copying Format via Tree

Getting plot settings from one data plot to a tree, then apply settings from this tree to another data plot object.
GraphPage gpSource("Graph1"); GraphLayer glSource = gpSource.Layers(0); DataPlot dpSource = glSource.DataPlots(0); GraphPage gpDest("Graph2"); GraphLayer glDest = gpDest.Layers(0);
86
Graphs
6.3.6 Setting Format on Scatter Plot

DataPlot dpDest = glDest.DataPlots(0); // Get format from source data plot Tree tr; tr = dpSource.GetFormat(FPB_ALL, FOB_ALL, true, true); // Apply format to another data plot dpDest.ApplyFormat(tr, true, true);
6.3.6
Setting Format on Scatter Plot
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(-1); // Get the active data plot // Set symbol format Tree tr; tr.Root.Symbol.Size.nVal = 12; // Size of symbol tr.Root.Symbol.Shape.nVal = 1; // Circle tr.Root.Symbol.Interior.nVal = 1; // Interior type tr.Root.Symbol.EdgeColor.nVal = SYSCOLOR_RED; tr.Root.Symbol.FillColor.nVal = SYSCOLOR_BLUE; // Show vertical droplines tr.Root.DropLines.Vertical.nVal = 1; tr.Root.DropLines.VerticalColor.nVal = SYSCOLOR_LTGRAY; tr.Root.DropLines.VerticalStyle.nVal = 1; tr.Root.DropLines.VerticalWidth.nVal = 1.5; if( 0 == dp.UpdateThemeIDs(tr.Root) ) { bool bRet = dp.ApplyFormat(tr, true, true); }
6.3.7
Setting Format on Grouped Line + Symbol Plots
Use Origin C to set the format for grouped plots. The same action can be completed by going into the Plot Details dialog, under the Group tab. The formats included Line Color, Symbol Type, Symbol Interior, and Line Style. The following example shows how to set format on Line and Symbol plots. This group is assumed to contain 4 data plots.
GraphLayer gl = Project.ActiveLayer(); GroupPlot gplot = gl.Groups(0); // Get the first group in layer // the Nester is an array of types of objects to do nested cycling in the group // four types of setting to do nested cycling in the group vector<int> vNester(3); vNester[0] = 0; // cycling line color in the group vNester[1] = 3; // cycling symbol type in the group vNester[2] = 8; // cycling symbol interior in the group gplot.Increment.Nester.nVals = vNester; // set Nester of the grouped plot // Put format settings to vector for 4 plots vector<int> vLineColor = {SYSCOLOR_BLUE, SYSCOLOR_OLIVE, SYSCOLOR_RED,
Graphs
87

SYSCOLOR_CYAN}; vector<int> vSymbolShape = {1, 3, 5, 8}; vector<int> vSymbolInterior = {1, 2, 5, 0}; Tree tr; tr.Root.Increment.LineColor.nVals = vLineColor; // set line color to theme tree tr.Root.Increment.Shape.nVals = vSymbolShape; // set symbol shape to theme tree // set symbol interior to theme tree tr.Root.Increment.SymbolInterior.nVals = vSymbolInterior; if(0 == gplot.UpdateThemeIDs(tr.Root) ) { bool bb = gplot.ApplyFormat(tr, true, true); }
// apply theme tree
6.3.8
Setting Colormap Settings
This example shows how to set up colormap Z levels on a Contour graph.

GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(0); // Get original colormap Z levels vector vZs; BOOL bLogScale = FALSE; BOOL bRet = dp.GetColormap(vZs, bLogScale); int nLevels = vZs.GetSize(); // Decrease Z levels vector and set back to DataPlot double min, max; vZs.GetMinMax(min, max); double dChangeVal = fabs(max - min) * 0.2; bool bIncrease = true; if( !bIncrease ) dChangeVal = 0 - dChangeVal; min = min - dChangeVal; max = max - dChangeVal; double inc = (max - min) / nLevels; vZs.Data(min, max, inc); dp.SetColormap(vZs);
The following example shows how to remove fill color, and set up line color, style, width and text labels on a Contour graph.
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(0); Tree tr; dp.GetColormap(tr); // Remove fill color tr.ColorFillControl.nVal = 0; // Set line color vector<int> vnLineColors; vnLineColors = tr.Details.LineColors.nVals;
88
Graphs
6.3.8 Setting Colormap Settings

int nLevels = vnLineColors.GetSize(); vnLineColors.Data(1, nLevels, 1); tr.Details.LineColors.nVals = vnLineColors; // Set line style as Dash for all lines vector<int> vnLineStyles(vnLineColors.GetSize()); vnLineStyles = 1; tr.Details.LineStyles.nVals = vnLineStyles; // Set line width for all lines vector vdLineWidths(vnLineColors.GetSize()); vdLineWidths = 3; tr.Details.LineWidths.dVals = vdLineWidths; // Show/hide labels, show all except that the first two. vector<int> vnLabels(vnLineColors.GetSize()); vnLabels = 1; vnLabels[0] = 0; vnLabels[1] = 0; tr.Details.Labels.nVals = vnLabels; // Set back settings to graph dp.SetColormap(tr);
This example shows how to set the format(i.e. color, size, bold, italic) of the text labels on a Contour graph.
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(0); // Get all properties of the related objects of the colormap data plot Tree tr; tr = dp.GetFormat(FPB_ALL, FOB_ALL, true, true); // Show all labels vector<int> vnLabels; vnLabels = tr.Root.ColorMap.Details.Labels.nVals; vnLabels = 1;// 0 to hide, 1 to show tr.Root.ColorMap.Details.Labels.nVals = vnLabels; // Set the numeric format for labels tr.Root.NumericFormats.Format.nVal = 0; // Decimal tr.Root.NumericFormats.DigitsControl.nVal = 0; tr.Root.NumericFormats.SignificantDigits.nVal = 5;//DecimalPlaces tr.Root.NumericFormats.Prefix.strVal = "_"; tr.Root.NumericFormats.Suffix.strVal = "Label"; tr.Root.NumericFormats.MinArea.nVal = 5; // Labeling Criteria - Min Area(%) // Set text format for labels tr.Root.Labels.Color.nVal = SYSCOLOR_BLUE; //FontFaceIndex_to_DWORD is used to convert font from GUI index to DWORD real value tr.Root.Labels.Face.nVal = FontFaceIndex_to_DWORD(2);// choose the 3rd font in GUI tr.Root.Labels.Size.nVal = 20; tr.Root.Labels.WhiteOut.nVal = 1; tr.Root.Labels.Bold.nVal = 1; tr.Root.Labels.Italic.nVal = 1; tr.Root.Labels.Underline.nVal = 1; if(0 == dp.UpdateThemeIDs(tr.Root) ) dp.ApplyFormat(tr, true, true);
Graphs
89
6.4 Managing Layers
6.4 Managing Layers

6.4.1 Creating a Panel Plot
Creating a 6 Panel Graph

The following example will create a new graph window with 6 layers, arranged as 2 columns and 3 rows. This function can be run independent of what window is active.
GraphPage gp; gp.Create("Origin"); while(gp.Layers.Count() < 6) { gp.AddLayer(); } graph_arrange_layers(gp, 3, 2);
Creating and Plotting into a 6 Panel Graph

The following example will import some data into a new workbook, create a new graph window with 6 layers, arranged as 2 columns and 3 rows, and loop through each layer (panel), plotting the imported data.
// Import data file to worksheet ASCIMP ai; Worksheet wks; string strDataFile = GetOpenBox(FDLOG_ASCII, GetAppPath(true)); if(AscImpReadFileStruct(strDataFile,&ai) == 0) { wks.Create("Origin"); wks.ImportASCII(strDataFile, ai); } // Add XY data from worksheet to graph each layers GraphPage gp("Graph1"); // the graph has the 3x2 panel layers created above int index = 0; foreach(GraphLayer gl in gp.Layers) { DataRange dr; dr.Add(wks, 0, "X"); dr.Add(wks, index+1, "Y"); if( gl.AddPlot(dr, IDM_PLOT_LINE) >= 0 ) gl.Rescale(); index++; }
90
Graphs
6.4.2 Adding Layers to a Graph Window
6.4.2
Adding Layers to a Graph Window
The following example will add an independent right Y axis scale. A new layer is added, displaying only the right Y axis. It is linked in dimension and the X axis is linked to the current active layer at the time the layer is added. The new added layer becomes the active layer. Before compiling the following codes, you need to add graph_utils.c to your current workspace. Run Labtalk command "Run.LoadOC(Originlab\graph_utils.c)" to do this.
#include <..\Originlab\graph_utils.h>// Needed for page_add_layer function GraphLayer gl = Project.ActiveLayer(); GraphPage gp = gl.GetPage(); bool bBottom = false, bLeft = false, bTop = false, bRight = true; int nLinkTo = gl.GetIndex(); // New added layer link to the active layer bool bActivateNewLayer = true; int nLayerIndex = page_add_layer(gp, bBottom, bLeft, bTop, bRight, ADD_LAYER_INIT_SIZE_POS_SAME_AS_PREVIOUS, bActivateNewLayer, nLinkTo);
6.4.3
Arranging the Layers
The following example will arrange the existing layers on the active graph into two rows by three columns. If the active graph does not already have 6 layers, it will not add any new layers. It arranges only the layers that exist.
GraphLayer gl = Project.ActiveLayer(); GraphPage gp = gl.GetPage(); int nRows = 3, nCols = 2; graph_arrange_layers(gp, nRows, nCols);
6.4.4
Moving a Layer
The following example will left align all layers in the active graph window, setting their position to be 15% from the left-hand side of the page.
GraphLayer gl = Project.ActiveLayer(); GraphPage gp = gl.GetPage(); int nRows = gp.Layers.Count(); int nCols = 1; stLayersGridFormat stFormat; stFormat.nXGap = 0; // the X direction gap of layers stFormat.nYGap = 5; // the Y direction gap of layers stFormat.nLeftMg = 15; // left margin stFormat.nRightMg = 10; stFormat.nTopMg = 10; stFormat.nBottomMg = 10; page_arrange_layers(gp, nRows, nCols, &stFormat);
Graphs
91
6.4 Managing Layers
6.4.5
Resizing a Layer
The following example will resize the current layer to reduce the width and height to half of the original size. Before compiling the following codes, you need to add graph_utils.c to your current workspace. Run Labtalk command "Run.LoadOC(Originlab\graph_utils.c)" to do this.
#include <..\Originlab\graph_utils.h> // Needed for layer_set_size function GraphLayer gl = Project.ActiveLayer(); // get the original size of graph layer double dWidth, dHeight; layer_get_size(gl, dWidth, dHeight); // resize layer dWidth /= 2; dHeight /= 2; layer_set_size(gl, dWidth, dHeight);
6.4.6
Swap two Layers
The following example will swap the position on the page of layers indexed 1 and 2. Before compiling the following codes, you need to add graph_utils.c to your current workspace. Run Labtalk command "Run.LoadOC(Originlab\graph_utils.c)" to do this.
#include <..\Originlab\graph_utils.h> // Needed for layer_swap_position function GraphPage gp("Graph1"); GraphLayer gl1 = gp.Layers(0); GraphLayer gl2 = gp.Layers(1); layer_swap_position(gl1, gl2);
The following example will swap the position on the page of layers named Layer1 and Layer2.
GraphPage gp("Graph1"); GraphLayer gl1 = gp.Layers("Layer1"); GraphLayer gl2 = gp.Layers("Layer2"); layer_swap_position(gl1, gl2);
6.4.7
Aligning Layers
The following example will bottom align layer 2 with layer 1 in the active graph window. Before compiling the following codes, you need to add graph_utils.c to your current workspace. Run Labtalk command "Run.LoadOC(Originlab\graph_utils.c)" to do this.
#include <..\Originlab\graph_utils.h> // Needed for layer_aligns function // Get the active graph page GraphLayer gl = Project.ActiveLayer(); GraphPage gp = gl.GetPage(); GraphLayer gl1 = gp.Layers(0); GraphLayer gl2 = gp.Layers(1);
92
Graphs
6.4.8 Linking Layers

// Bottom align layer 2 with layer 1 layer_aligns(gl1, gl2, POS_BOTTOM);
6.4.8
Linking Layers
The following example will link all X axes in all layers in the active graph to the X axis of layer 1. The Units will be set to a % of Linked Layer. Before compiling the following codes, you need to add graph_utils.c to your current workspace. Run Labtalk command "Run.LoadOC(Originlab\graph_utils.c)" to do this.
#include <..\Originlab\graph_utils.h> // Needed for layer_set_link function GraphLayer gl = Project.ActiveLayer(); GraphPage gp = gl.GetPage(); GraphLayer gl1 = gp.Layers(0); // Layer 1 foreach(GraphLayer glOne in gp.Layers) { int nUnit = M_LINK; // Set layer unit as % of linked layer if( glOne != gl1 ) layer_set_link(glOne, gl1.GetIndex(), LINK_STRAIGHT, LINK_NONE, &nUnit); }
6.4.9
Setting Layer Unit
int nUnit = M_PIXEL; GraphLayer gl = Project.ActiveLayer(); // Get the current position double dPos[TOTAL_POS]; gl.GetPosition(dPos); // Convert position to the specified unit gl.UnitsConvert(nUnit, dPos); // Set position with unit gl.SetPosition(dPos, nUnit);
6.5 Creating and Accessing Graphical Objects

6.5.1 Creating Graphical Object
Add a Graphical Object, for example: text, or a rectangle or line. The following example shows how to add a rectangle to the active graph. For other Graph object types see GROT_* (for example: GROT_TEXT, GROT_LINE, GROT_POLYGON) in the oc_const.h file.
Graphs 93

GraphLayer gl = Project.ActiveLayer(); string strName = "MyRect"; GraphObject goRect = gl.CreateGraphObject(GROT_RECT, strName);
Add a text label on the current graph window:

GraphLayer gl = Project.ActiveLayer(); GraphObject go = gl.CreateGraphObject(GROT_TEXT, "MyText"); go.Text = "This is a test";
The example below shows how to add an arrow to a graph. The object type of an arrow is GROT_LINE, the same type as a line. And for both lines and arrows, the number of data points required is 2.
GraphPage gp; gp.Create(); GraphLayer gl = gp.Layers(); string strName = "MyArrow"; // the name of the graph object GraphObject go = gl.CreateGraphObject(GROT_LINE, strName); go.Attach = 2; // change attach mode to Layer and Scale Tree tr; tr.Root.Dimension.Units.nVal = 5; // Set unit as Scale // Set position by scale value vector vx = {2, 6}; vector vy = {6, 2}; tr.Root.Data.X.dVals = vx; tr.Root.Data.Y.dVals = vy; tr.Root.Arrow.Begin.Style.nVal = 0; tr.Root.Arrow.End.Style.nVal = 1; if( 0 == go.UpdateThemeIDs(tr.Root) ) { go.ApplyFormat(tr, true, true); }
The example below shows how to add a curved arrow to a graph. For a curved arrow, the number of data points required is 4.
GraphPage gp; gp.Create(); GraphLayer gl = gp.Layers(); string strName = "MyArrow"; // the name of the graph object GraphObject go = gl.CreateGraphObject(GROT_LINE4, strName); go.Attach = 2; // change attach mode to Layer and Scale Tree tr; tr.Root.Dimension.Units.nVal = 5; // Set unit as Scale // Set position by scale value vector vx = {2, 4, 6, 5}; vector vy = {7, 6.9, 6.8, 2}; tr.Root.Data.X.dVals = vx; tr.Root.Data.Y.dVals = vy;
94
Graphs
6.5.2 Setting Properties

tr.Root.Arrow.Begin.Style.nVal = 0; tr.Root.Arrow.End.Style.nVal = 1; if( 0 == go.UpdateThemeIDs(tr.Root) ) { go.ApplyFormat(tr, true, true); }
6.5.2
Setting Properties
Set Properties for a Graphical Object, for example, text font, color, line width.
// Set color and font for graph object GraphLayer gl = Project.ActiveLayer(); GraphObject goText = gl.GraphObjects("Text"); goText.Text = "This is a test"; goText.Attach = 2; // Attach to layer scale Tree tr; tr.Root.Color.nVal = SYSCOLOR_RED; // the color of text tr.Root.Font.Bold.nVal = 1; tr.Root.Font.Italic.nVal = 1; tr.Root.Font.Underline.nVal = 1; tr.Root.Font.Size.nVal = 30; // font size of text if( 0 == goText.UpdateThemeIDs(tr.Root) ) { bool bRet = goText.ApplyFormat(tr, true, true); }
6.5.3
Setting Position and Size
GraphLayer gl = Project.ActiveLayer(); GraphObject go = gl.GraphObjects("Rect"); go.Attach = 2; // Attach to layer scale // Move text object to the layer left top Tree tr; tr.Root.Dimension.Units.nVal = UNITS_SCALE; tr.Root.Dimension.Left.dVal = gl.X.From; // Left tr.Root.Dimension.Top.dVal = gl.Y.To/2; // Top tr.Root.Dimension.Width.dVal = (gl.X.To - gl.X.From)/2; // Width tr.Root.Dimension.Height.dVal = (gl.Y.To - gl.Y.From)/2; // Height if( 0 == go.UpdateThemeIDs(tr.Root) ) { bool bRet = go.ApplyFormat(tr, true, true); }
6.5.4
Updating Attach Property
The attach property has 3 choices, Page, Layer Frame, and Layer Scale.
// Attach graph object to the different object:
Graphs
95

// 0 for layer, when move layer, graph object will be moved together; // 1 for page, when move layer, not effect on graph object; // 2 for layer scale, when change the scale, the position of graph object // will be changed according. go.Attach = 2;
6.5.5
Getting and Setting Disable Property
// To check disable properties, for example, movable, selectable. Tree tr; tr = go.GetFormat(FPB_OTHER, FOB_ALL, true, true); DWORD dwStats = tr.Root.States.nVal; // To check vertical and horizontal movement. // More property bits, see GOC_* in oc_const.h file. if( (dwStats & GOC_NO_VMOVE) && (dwStats & GOC_NO_HMOVE) ) { out_str("This graph object cannot be move"); }
6.5.6
Programming Control
// 1. Add a line GraphLayer gl = Project.ActiveLayer(); GraphObject go = gl.CreateGraphObject(GROT_LINE); go.Attach = 2; // Set attach mode to layer scale go.X = 5; // Set init position to X = 5 // 2. Set line properties Tree tr; tr.Root.Direction.nVal = 2; // 1 for Horizontal, 2 for vertical tr.Root.Span.nVal = 1; // Span to layer tr.Root.Color.nVal = SYSCOLOR_RED; // Line color if( 0 == go.UpdateThemeIDs(tr.Root) ) { go.ApplyFormat(tr, true, true); } // 3. Set event mode and LT script. // Move line will print out line position, x scale value. Tree trEvent; trEvent.Root.Event.nVal = GRCT_MOVE;// More other bits, see GRCT_* in oc_const.h trEvent.Root.Script.strVal = "type -a $(this.X)"; if( 0 == go.UpdateThemeIDs(trEvent.Root) ) { go.ApplyFormat(trEvent, true, true); }
96
Graphs
6.5.7 Updating Legend
6.5.7
Updating Legend
A legend is a graphical object named "Legend" on a graph window. After adding/removing data plots, we can use the legend_update function to refresh the legend according to the current data plots.
// Simple usage here, just used to refresh legend. // Search this function in OriginC help to see the description of other arguments // for more usages. legend_update(gl); // gl is a GraphLayer object
6.5.8
Adding Table Object on Graph
// 1. Create the worksheet with Table template Worksheet wks; wks.Create("Table", CREATE_HIDDEN); WorksheetPage wksPage = wks.GetPage(); // 2. Set table size and fill in text wks.SetSize(3, 2); wks.SetCell(0, 0, "1"); wks.SetCell(0, 1, "Layer 1"); wks.SetCell(1, 0, "2"); wks.SetCell(1, 1, "Layer 2"); wks.SetCell(2, 0, "3"); wks.SetCell(2, 1, "Layer 3"); //3. Add table as link to graph GraphLayer gl = Project.ActiveLayer(); GraphObject grTable = gl.CreateLinkTable(wksPage.GetName(), wks);
Graphs
97
Working with Data
7.1 Numeric Data

This section gives examples of working with numeric data in Origin C. Numeric data can be stored in variables of the following data types:
1. 2. 3. 4. double integer vector matrix
Numeric data and strings can be stored in the nodes of a tree, provided the nodes have one of the data types above.
7.1.1
Missing Values
As important as numeric data is, it is also important to be able to represent missing data. Origin C defines the NANUM macro for comparing and assigning values to missing data. Missing values are only supported with the double data type.
double d = NANUM; if( NANUM == d ) out_str("The value is a missing value.");
Origin C also provides the is_missing_value function for testing if a value is a missing value.
if( is_missing_value(d) ) out_str("The value is a missing value.");
7.1.2
Precision and Comparison
In the following example code, the prec and round functions are used to control the precision of double type numeric data. The is_equal function is used to compare two pieces of double type numeric data.
double dVal = PI; // PI defined as 3.1415926535897932384626 // convert the double value to have 6 significant digits int nSignificantDigits = 6; printf("%f\n", prec(dVal, nSignificantDigits)); // force the double value to only have two decimal digits uint nDecimalPlaces = 2; double dd = round(dVal, nDecimalPlaces); printf("%f\n", dd);
99
7.1 Numeric Data

// compare two double values if( is_equal(dd, 3.14) ) { out_str("equal\n"); } else { out_str("not equal\n"); }
7.1.3
Convert Numeric to String
// assign int type numeric to string string str = 10; out_str(str); int nn = 0; str = nn; out_str(str); // convert double type numeric to string double dd = PI; str = ftoa(dd, "*"); // Use "*" for Origin's global setting in Options dialog out_str(str); str = ftoa(dd, "*8"); // Use "*8" for 8 significant out_str(str);
7.1.4
Vector
// One-Dimensional array with basic data type, for example, double, int, string, // complex. vector vx, vy; int nMax = 10; vx.Data(1, nMax, 1); // assign value to vx from 1 to 10 with increment 1 vy.SetSize(nMax); // set size(10) to vy for(int nn = 0; nn < nMax; nn++) { vy[nn] = rnd(); // assign random data to each item in vy printf("index = %d, x = %g, y = %g\n", nn+1, vx[nn], vy[nn]); } // Access the data in a worksheet window Worksheet wks = Project.ActiveLayer(); Column col(wks, 0); vector& vec = col.GetDataObject(); vec = vec * 0.1; // Multiply 0.1 by each piece of data in vec vec = sin(vec); // Find the sine of each piece of data in vec
100
Working with Data
7.1.5 Matrix
7.1.5
Matrix
// Two-Dimensional array with basic data type, for example, double, int, complex, // but not string. matrix mat(5, 6); for(int ii = 0; ii < 5; ii++) { for(int jj = 0; jj < 6; jj++) { mat[ii][jj] = ii + jj; printf("%g\t", mat[ii][jj]); } printf("\n"); // new line } // Access the data in matrix window MatrixLayer ml = Project.ActiveLayer(); MatrixObject mo = ml.MatrixObjects(0); matrix& mat = mo.GetDataObject(); mat = mat + 0.1; // Add 0.1 for the each data in matrix
7.1.6
TreeNode
The Origin C TreeNode class provides several methods for constructing multi-level trees, traversing trees and accessing the value/attributes of tree nodes.
Tree tr; // Access the value of a tree node TreeNode trName = tr.AddNode("Name"); trName.strVal = "Jane"; tr.UserID.nVal = 10; vector<string> vsBooks = {"C++", "MFC"}; tr.Books.strVals = vsBooks; out_tree(tr); // output tree
7.1.7
Complex
complex cc(1.5, 2.2); cc.m_re = cc.m_re +1; cc.m_im = cc.m_im * 0.1; out_complex("cc = ", cc); // output cc = 2.500000+0.220000i // Access complex dataset Worksheet wks = Project.ActiveLayer(); Column col(wks, 1); if( FSI_COMPLEX == col.GetInternalDataType() ) { vector<complex>& vcc = col.GetDataObject();
Working with Data
101
7.1 Numeric Data

vcc[0] = 0.5 + 3.6i; } // Access complex matrix MatrixLayer ml = Project.ActiveLayer(); MatrixObject mo = ml.MatrixObjects(); if( FSI_COMPLEX == mo.GetInternalDataType() ) { matrix<complex>& mat = mo.GetDataObject(); mat[0][0] = 1 + 2.5i; }
7.1.8
DataRange
The DataRange class is a versatile mechanism to get and put data in a Worksheet, Matrix or Graph window.
Data Range in Worksheet

For a Worksheet, a data range can be specified by column/row index as one column, one row, any sub block range, one cell or entire Worksheet.
// Construct a data range on the active worksheet, all columns and rows // from 1st row to 5th row. Worksheet wks = Project.ActiveLayer(); int r1 = 0, c1 = 0, r2 = 4, c2 = -1; DataRange dr; // range name should be make sense, for example, "X", "Y", // "ED"(Y error), "Z". If the data range is not belong to dependent // or independent type, default can be "X". dr.Add("X", wks, r1, c1, r2, c2);
Get data from data range to vector. DataRange::GetData supports multiple overloaded methods. For example:
vector vData; int index = 0; // range index dr.GetData(&vData, index);
Data Range in Matrixsheet

For a Matrix window, the data range can be a matrix object index.
MatrixLayer ml = Project.ActiveLayer(); DataRange dr; int nMatrixObjectIndex = 0; dr.Add(ml, nMatrixObjectIndex, "X");
Get data from data range to matrix.

matrix mat; dr.GetData(mat);
102
Working with Data
7.2.1 String Variables
Data Range in Graph

For a Graph window, the data range can be one data plot, or a sub range of one data plot.
GraphLayer gl = Project.ActiveLayer(); DataPlot dp = gl.DataPlots(); // Get active data plot DataRange dr; int i1 = 0; // from the first data point int i2 = -1; // to the last data point dp.GetDataRange(dr, i1, i2);
Get XY data from data plot to vector by data range object.

vector vx, vy; DWORD dwRules = DRR_GET_DEPENDENT; dr.GetData(dwRules, 0, NULL, NULL, &vy, &vx);
Data Range Control

OriginC supports a GetN dialog interactive control to choose a data range.
#include <GetNBox.h> // Open a dialog to choose a range from one graph data plot. // And construct a data range object by this selection. GETN_TREE(tr) GETN_INTERACTIVE(Range1, "Select Range", "") if( GetNBox(tr) ) // returns true if click OK button { DataRange dr; dr.Add("Range1", tr.Range1.strVal); vector vData; int index = 0; // range index dr.GetData(&vData, index); // The data in vData is the selected data points }
7.2 String Data

7.2.1 String Variables
string str1; // Declare a string variable named str1 str1 = "New York"; // Assigns to str1 a character sequence string str2 = "Tokyo"; // Declare a string variable and assignment // Declare a character array and initialize with a character sequence char ch[] = "This is a test!"; // Declare a character array, set size and initialize with a character sequence char chArr[255] = "Big World.";
Working with Data
103
7.2 String Data
7.2.2
Convert String to Numeric
string str = PI; // Assigns a numeric value to string variable // Convert string to numeric double dd = atof(str, true); out_double("dd=", dd); // dd=3.14159 // Convert string to complex str = "1+2.5i"; complex cc = atoc(str); out_complex("cc = ", cc); // cc = 1.000000+2.500000i // Convert string to int str = "100"; int nn = atoi(str); out_int("nn = ", nn); // nn = 100
7.2.3
Append Numeric/String to another String
// Append numeric or string to another string // In Origin C, support use '+' to add a numeric/string type const or variable string str = "The area is " + 30.7; // Append a double type const to string str += "\n"; // Append a string const to string variable int nLength = 10; str += "The length is " + nLength; // Append a int type variable to string out_str(str);
7.2.4
Find Sub String
// Find and get sub string string str = "[Book1]Sheet1!A:C"; int begin = str.Find(']'); // Find and return the index of ']' begin++; // Move to the next character of ] int end = str.Find('!', begin); // Find and return the index of '!' end--; // Move the previous character of ! // Get the sub string with the begin index and substring length int nLength = end - begin + 1; string strSheetName = str.Mid(begin, nLength); out_str(strSheetName);// Should output "Sheet1"
7.2.5
Replace Sub String
// Find and replace one character string str("A+B+C+"); int nCount = str.Replace('+','-'); out_int("", nCount); // nCount will be 3
104
Working with Data
7.2.6 Path String Functions

out_str(str); // "A-B-C-" // Find and replace a character string str = "I am a student.\nI am a girl."; nCount = str.Replace("I am", "You are"); out_int("", nCount); // nCount will be 2 out_str(str);
7.2.6
Path String Functions
File Path String

// string::IsFile is used to check the file if exist string strFile = "D:\\TestFolder\\abc.txt"; bool bb = strFile.IsFile(); printf("The file %s is %sexist.\n", strFile, bb ? "" : "NOT "); // GetFilePath function is used to extract the path from a full path string string strPath = GetFilePath(strFile); out_str(strPath); // GetFileName function is used to extracts the file name part // from a string of full path bool bRemoveExtension = true; string strFileName = GetFileName(strFile, bRemoveExtension); out_str(strFileName); // string::IsPath to check if the path is exist bb = strPath.IsPath(); out_int("", bb);
Origin System Path

string strSysPath = GetOriginPath(ORIGIN_PATH_SYSTEM); printf("Origin System Path: %s\n", strSysPath); string strUserPath = GetOriginPath(ORIGIN_PATH_USER); printf("User File Path: %s\n", strUserPath);
7.3 Date and Time Data

Origin C provides support for date and time data.
7.3.1
Get Current Date Time
// Get current time time_t aclock; time( &aclock ); // Converts a time value and corrects for the local time zone
Working with Data
105
7.3 Date and Time Data

TM tmLocal; convert_time_to_local(&aclock , &tmLocal); // Convert time value from TM format to system time format SYSTEMTIME sysTime; tm_to_systemtime(&tmLocal, &sysTime); // Get date string from system time char lpcstrTime[100]; if(systemtime_to_date_str(&sysTime, lpcstrTime, LDF_SHORT_AND_HHMM_SEPARCOLON)) printf("Current Date Time is %s\n", lpcstrTime);
7.3.2
Convert Julian Date to String
SYSTEMTIME st; GetSystemTime(&st); // Gets current date time double dJulianDate; SystemTimeToJulianDate(&dJulianDate, &st); // Convert to Julian date // Convert Julian date to string with the specified format string strDate = get_date_str(dJulianDate, LDF_SHORT_AND_HHMM_SEPARCOLON); out_str(strDate);
7.3.3
Convert String to Julian Date
string strDate = "090425 17:59:59"; double dt = str_to_date(strDate, LDF_YYMMDD_AND_HHMMSS);
106
Working with Data
Projects
The Origin C Project class is used for accessing the various high level objects contained in an Origin project. This includes workbooks, matrixbooks, graphs, notes, folders, and more.
8.1 Managing Projects

Origin C provides the Project class for opening, saving, and appending projects and for accessing the various objects contained in a project. The Project class contains collections for all the page types and loose data sets. There are methods to get the active objects such as the active curve, layer, and folder.
8.1.1
Open and Save a Project
The code below demonstrates saving a project, starting a new project, and opening a saved project.
string strPath = "c:\\abc.opj"; // Project path and name Project.Save(strPath); // Save current project Project.Open(); // Start a new project Project.Open(strPath); // Open saved project
8.1.2
Append One Project to Another
You can append a project to the current project by using the optional second argument of the Project.Open method. The appended project's folder structure will be put into the current project's active folder.
Project.Open("c:\\abc.opj", OPJ_OPEN_APPEND);
8.1.3
The Modified Flag
When a project is modified, the IsModified flag is set internally by Origin. Origin C allows setting and clearing the IsModified flag. When a project is being closed, this flag is checked. If the flag is set then Origin will ask the user if they want to save their changes. If your Origin C code made changes that you know should not be saved, then you may want to clear the flag to prevent Origin from prompting the user.
107
8.2 Managing Folders

if( Project.IsModified() ) { // Set the active project as not modified. We do this when we know // we do not want to save the changes and want to prevent Origin // from prompting the user about unsaved changes. Project.ClearModified(); // Start a new project, knowing the user will not be prompted about // unsaved changes in the active project. Project.Open(); }
8.2 Managing Folders

Pages in an Origin project (workbooks, matrix books, and graphs) can be organized in a hierarchical folder structure, visible in Origin's Project Explorer. The Origin C Folder class allows you to create, activate, select, and arrange folders.
8.2.1
Create a Folder and Get Its Path
Folder fldRoot, fldSub; fldRoot = Project.RootFolder; // Add a sub folder in root folder with name fldSub = fldRoot.AddSubfolder("MyFolder"); printf("Folder added successfully, path is %s\n", fldSub.GetPath());
8.2.2
Get the Active Folder
Folder fldActive; fldActive = Project.ActiveFolder(); // Add a sub folder to it fldSub = fldActive.AddSubfolder("MyFolder"); printf("Folder added successfully, path is %s\n", fldSub.GetPath());
8.2.3
Activate a Folder
// activate root folder Folder fldRoot = Project.RootFolder; fldRoot.Activate(); // activate the specified sub folder Folder fldSub("/MyFolder"); fldSub.Activate();
108
Projects
8.2.4 Get Path for a Specific Page
8.2.4
Get Path for a Specific Page
GraphPage gp("Graph1"); if( gp.IsValid() ) { Folder fld = gp.GetFolder(); out_str(fld.GetPath()); }
8.2.5
Move a Page/Folder to Another Location
Folder::Move is used to move a window (Worksheet, Graph...) or folder to another location. The following example shows how to move a folder.
// Add two sub folders to root folder Folder subfld1 = root.AddSubfolder("sub1"); Folder subfld2 = root.AddSubfolder("sub2"); // Move the sub2 folder under the sub1 folder if( !root.Move(subfld2.GetName(), "/"+subfld1.GetName()+"/", true) ) printf("move folder failed!");
8.3 Accessing Pages

Pages in Origin consist of workbooks, matrix books and graphs, and are the core objects in a project. Origin C allows you to access a page by name or by index, or access all instances of a particular page type in the current project using the foreach statement.
8.3.1
Access a Page by Name and Index
All pages have names, which can be used to access them, as in the following example:
// Access a page by its name GraphPage gp1("Graph1"); // Access a page by its zero based index GraphPage gp2 = Project.GraphPages(0); // 0 for first page
8.3.2
Get the Active Page and Layer
In a workbook page, a layer is a worksheet; in a graph page, a layer is a pair of axes; in a matrix page, a layer is a matrix sheet. If you want to access the page associated with a particular layer, such as the active layer, it can be done with the GetPage() method:
// get active layer GraphLayer gl = Project.ActiveLayer();
Projects
109
8.4 Accessing Metadata

// get active page from layer GraphPage gp = gl.GetPage();
8.3.3
Using foreach
The foreach statement simplifies the process of looping through all the items in a collection. The project contains all the pages in various collections.
// Loop through all workbook pages in the current project // and output the name of each page. foreach( WorksheetPage wksPage in Project.WorksheetPages ) { out_str(wksPage.GetName()); } // Loop through all matrixbook pages in the current project // and output the name of each page. foreach( MatrixPage matPage in Project.MatrixPages ) { out_str(matPage.GetName()); } // Loop through all graph pages in the current project // and output the name of each page. foreach( GraphPage gp in Project.GraphPages ) { out_str(gp.GetName()); } // Loop through all pages in the current project // and output the name of each page. foreach( Page pg in Project.Pages ) { out_str(pg.GetName()); }

Metadata is information which refers to other data. Examples include the time at which data was originally collected, the operator of the instrument collecting the data and the temperature of a sample being investigated. Metadata can be stored in Projects, Pages, Layers and Columns.
8.4.1
Access DataRange
The Origin C Project class provides methods to add, get, and remove an Origin C DataRange object to and from the current project.
Worksheet wks = Project.ActiveLayer(); DataRange dr; // Construct the range object dr.Add("X", wks, 0, 0, -1, -1); // Add whole worksheet to range
110
Projects
8.4.2 Access Tree

dr.SetName("Range1"); int UID = dr.GetUID(TRUE); // Set range name // Get Unique ID for the range object
int nn = Project.AddDataRange(dr); // Add range to project
In the Command Window or Script Window you can use the LabTalk command list r to list all the DataRange objects in the current project.
8.4.2
Access Tree
Access a Tree in a Project

Add Tree
This code declares a variable of type tree, assigns some data to nodes of the tree, and adds the tree to the current project.
Tree tr; tr.FileInfo.name.strVal = "Test.XML"; tr.FileInfo.size.nVal = 255; // add tree variable to project int nNumTrees = Project.AddTree("Test", tr); out_int("The number of trees in project: ", nNumTrees);
Get Tree
Likewise, a similar code extracts data stored in an existing tree variable named Test and puts it into a new tree variable named trTest:
// get tree from project by name Tree trTest; if( Project.GetTree("Test", trTest) ) out_tree(trTest);
Get the Names of All LabTalk Trees

The Project.GetTreeNames method gets the names of all LabTalk tree variables in the project. Here, the names are assigned to a string vector; the number of strings assigned is returned as an integer.
vector<string> vsTreeNames; int nNumTrees = Project.GetTreeNames(vsTreeNames);
Access Tree in a Worksheet

OriginObject::PutBinaryStorage is used to put a tree into many types of Origin object, for example, a WorksheetPage, Worksheet, Column, GraphPage, or MatrixPage.
Add Tree
Keep an active worksheet window in the current project, to run the example code below. After running the code to add a user tree, right click on the title of the worksheet window, choose Show Organizer, and you will see the added user tree show up in the panel on the right.
Worksheet wks = Project.ActiveLayer();
Projects
111

if( wks ) { Tree tr; tr.name.strVal = "Jacky"; tr.id.nVal = 7856; // put tree with name wksTree to worksheet object string strStorageName = "wksTree"; wks.PutBinaryStorage(strStorageName, tr); }
Get Tree
The OriginObject::GetBinaryStorage method is used to get a tree from an Origin object by name.
Worksheet wks = Project.ActiveLayer(); if( wks ) { Tree tr; string strStorageName = "wksTree"; // if the tree named wksTree is existed, return true. if( wks.GetBinaryStorage(strStorageName, tr) ) out_tree(tr); // output tree }
Get the Names of All Trees

The OriginObject::GetStorageNames method gets the names of everything in storage in an Origin object. There are two storage types: INI and binary. Trees belong to binary storage, and the following example code shows how to get binary storage from a Worksheet.
Worksheet wks = Project.ActiveLayer(); if( wks ) { // get the names of all binary type storage vector<string> vsNames; wks.GetStorageNames(vsNames, STORAGE_TYPE_BINARY); for(int nn = 0; nn < vsNames.GetSize(); nn++) out_str(vsNames[nn]); }
Access Tree in a Worksheet Column

For setting and getting a tree in a Worksheet Column, use the same methods for setting and getting a tree in a Worksheet, as described above.
Add Tree
Worksheet wks = Project.ActiveLayer(); Column col(wks, 0); Tree tr; tr.test.strVal = "This is a column"; tr.value.dVal = 0.15;
112
Projects
8.4.2 Access Tree

col.PutBinaryStorage("colTree", tr);
Get Tree
Worksheet wks = Project.ActiveLayer(); Column col(wks, 0); Tree tr; if( col.GetBinaryStorage("colTree", tr) ) out_tree(tr);
Get the Names of All Trees

Worksheet wks = Project.ActiveLayer(); Column col(wks, 0); // get the names of all binary type storage vector<string> vsNames; col.GetStorageNames(vsNames, STORAGE_TYPE_BINARY); for(int nn = 0; nn < vsNames.GetSize(); nn++) out_str(vsNames[nn]);
Access Import File Tree Nodes

After importing data into a worksheet, Origin stores metadata in a special tree-like structure at the page level. Basic information about the file can be retrieved and put into a tree.
Worksheet wks = Project.ActiveLayer(); WorksheetPage wksPage = wks.GetPage(); storage st; st = wksPage.GetStorage("system"); Tree tr; tr = st; double dDate printf("File printf("File printf("File = tr.Import.FileDate.dVal; Date: %s\n", get_date_str(dDate, LDF_SHORT_AND_HHMMSS_SEPARCOLON)); Name: %s\n", tr.Import.FileName.strVal); Path: %s\n", tr.Import.FilePath.strVal);
Access Report Sheet Tree

Analysis Report sheets are specially formatted Worksheets based on a tree structure. You can get the report tree from a report sheet as below.
Worksheet wks = Project.ActiveLayer(); Tree trReport; uint uid; // to receive the UID of the report range // true to translate the escaped operation strings(ex. ?$OP:A=1) // to real dataset name in the returned tree bool bTranslate = true; if( wks.GetReportTree(trReport, &uid, 0, GRT_TYPE_RESULTS, true) ) { out_tree(trReport); }
Projects
113
8.5 Accessing Operations
8.5 Accessing Operations

8.5.1 List All Operations
Many recalculating analysis tools, such as the Statistics on Columns dialog, the Nonlinear Curve Fitting dialog, etc., are based on the Operation class. After finishing the whole operation, there will be a lock on the result sheet or result graph. We can list all operations via Project::Operations. The following code is used to get all operations objects and print out the operation names.
OperationManager opManager; opManager = Project.Operations; int count = opManager.GetCount(); for(int index=0; index < count; index++) { OperationBase& op = opManager.GetOperation(index); string strName = op.GetName(); out_str(strName); }
8.5.2
Check Worksheet if Hierarchy
If you want to check whether a worksheet is a result table sheet, you can check with layer system parameters, as in the following code.
Worksheet wks = Project.ActiveLayer(); bool bHierarchySheet = (wks.GetSystemParam(GLI_PCD_BITS) & WP_SHEET_HIERARCHY); if( bHierarchySheet ) out_str("This is a report table sheet"); else out_str("This is not a report table sheet");
8.5.3
Accessing Report Sheet
The following code shows how to get a report tree from a report sheet, convert the result gotten from the report tree into a cell linking format string, and put it into a new worksheet. This is how to get a report tree from a report sheet. To run this code you need keep a report sheet active.
Worksheet wks = Project.ActiveLayer(); Tree trResult; wks.GetReportTree(trResult);
114
Projects
8.5.3 Accessing Report Sheet
The following code shows how to get the needed results from the report tree, convert them to a cell linking format string, and put it into a newly created worksheet.
// Add a new sheet for summary table WorksheetPage wksPage = wks.GetPage(); int index = wksPage.AddLayer(); Worksheet wksSummary = wksPage.Layers(index); string strCellPrefix; strCellPrefix.Format("cell://%s!", wks.GetName()); vector<string> vsLabels, vsValues; // Parameters vsLabels.Add(strCellPrefix + "Parameters.Intercept.row_label2"); vsValues.Add(strCellPrefix + "Parameters.Intercept.Value"); vsLabels.Add(strCellPrefix + "Parameters.Slope.row_label2"); vsValues.Add(strCellPrefix + "Parameters.Slope.Value"); // Statistics vsLabels.Add(strCellPrefix vsValues.Add(strCellPrefix vsLabels.Add(strCellPrefix vsValues.Add(strCellPrefix + + + + "RegStats.DOF.row_label"); "RegStats.C1.DOF"); "RegStats.SSR.row_label"); "RegStats.C1.SSR");
// put to columns Column colLabel(wksSummary, 0); Column colValue(wksSummary, 1); colLabel.PutStringArray(vsLabels); colValue.PutStringArray(vsValues);
Projects
115
Importing
One of the huge benefits of Origin is the ability to import data of different formats into a worksheet or a matrix sheet. Origin C provides this ability to import ASCII and binary data files, image files, and data from a database. The following sections will show you how to import data into a worksheet or matrix sheet.
9.1 Importing Data

The Worksheet and MatrixLayer classes are derived from the Datasheet class. The Datasheet class has a method named ImportASCII. The ImportASCII method is used for importing ASCII data files. There are also ImportExcel and ImportSPC methods for importing Microsoft Excel and spectroscopic data files, respectively.
9.1.1
Import ASCII Data File into Worksheet
The first example will import an ASCII data file into the active worksheet of the active workbook. It will first call the AscImpReadFileStruct global function to detect the file's format. The format information is stored in an ASCIMP structure. The structure will then be passed to the ImportASCII method to do the actual importing.
string strFile = "D:\\data.dat"; // some data file name ASCIMP ai; if(0 == AscImpReadFileStruct(strFile, &ai) ) { // In this example we will disable the ASCII import progress // bar by setting the LabTalk System Variable @NPO to zero. // This is optional and is done here to show it is possible. // The LTVarTempChange class makes setting and restoring a // LabTalk variable easy. See the Accessing LabTalk section // for more details about the LTVarTempChange class. LTVarTempChange progressBar("@NPO", 0); // 0 = disable progress bar // Get active worksheet from active work book. Worksheet wks = Project.ActiveLayer(); if(0 == wks.ImportASCII(strFile, ai)) out_str("Import data successful."); }
The next example will also import an ASCII data file into a worksheet but it will also obtain additional information about each column from the file, and set up the worksheet columns.
// Prompt user with a File Open dialog to choose a file to import. string strFile = GetOpenBox("*.dat"); if( strFile.IsEmpty() )
117
9.1 Importing Data

return; // User canceled or error ASCIMP ai; if( 0 == AscImpReadFileStruct(strFile, &ai) ) { ai.iAutoSubHeaderLines = 0; // Disable auto detect sub header // 1, LongName // 2. Units // 3. Expanded Description(User defined) // 4. Type Indication(User defined) ai.iSubHeaderLines = 4; // When iAutoSubHeaderLines is false(0), the beginning index of ai.nLongName, // ai.nUnits and ai.nFirstUserParams are from main header ai.nLongNames = ai.iHeaderLines; ai.nUnits = ai.iHeaderLines + 1; // Set the index for the first user params ai.nFirstUserParams = ai.iHeaderLines + 2; ai.nNumUserParams = 2; // Set the number of user params // Not set any header to Comments label ai.iMaxLabels = 0; // Get active worksheet from active work book. Worksheet wks = Project.ActiveLayer(); if( 0 == wks.ImportASCII(strFile, ai) ) // Return 0 for no error { // The names of the user parameter labels vector<string> vsUserLabels = {"Expanded Description", "Type Indication"}; // Set user parameter labels to specified names Grid grid; grid.Attach(wks); grid.SetUserDefinedLabelNames(vsUserLabels); wks.AutoSize(); // Resize column widths to best fit their contents. } }
9.1.2
Import ASCII Data File into Matrix Sheet
Importing data into a matrix sheet is very similar to importing into a worksheet. This example is almost identical to the first worksheet example. The only difference is we get the active matrix sheet from the active matrix book using the MatrixLayer class instead of the Worksheet class.
string strFile = "D:\\someData.dat"; ASCIMP ai; if( 0 == AscImpReadFileStruct(strFile, &ai) ) { MatrixLayer ml = Project.ActiveLayer(); if( 0 == ml.ImportASCII(strFile, ai) ) out_str("Data imported successfully."); }
118
Importing
9.1.3 Import Data Using an Import Filter
9.1.3
Import Data Using an Import Filter
Functions for importing files are declared in the OriginC\Originlab\FileImport.h file. These functions are also documented in the Origin C Language Reference help file. Prior to calling the import file functions, you need to first programmatically load and compile FileImport.c. This can be done from script using the command:
run.LoadOC(Originlab\FileImport.c, 16); // Option 16 ensures that all dependent Origin C files are loaded, // by scanning for the corresponding .h in FileImport.c
The following example shows importing data with a filter file.

#include <..\Originlab\FileImport.h> void import_with_filter_file() { Page pg = Project.Pages(); // Active Page // Get page book name string strPageName = pg.GetName(); // Get page active layer index int nIndexLayer = pg.Layers().GetIndex(); // Get Origin sample folder string strPath = GetAppPath(TRUE) + "Samples\\Signal Processing\\"; // specify .oif filter name string strFilterName = "TR Data Files"; import_file(strPageName, nIndexLayer, strPath + "TR2MM.dat", strFilterName); }
Sometimes the existing filter might need to be modified to meet the requirements of the data format, so you need to load the filter from the file and configure it. See the following case:
#include <..\Originlab\FileImport.h> void config_filter_tree() { string strFile = GetAppPath(1) + "Samples\\Curve Fitting\\Step01.dat"; if( !strFile.IsFile() ) return; Worksheet wks; wks.Create("origin"); // load filter to tree Tree trFilter; string strFilterName = "ASCII"; int nLocation = 1; // build-in Filters folder WorksheetPage wp = wks.GetPage(); string strPageName = wp.GetName(); int nRet = load_import_filter(strFilterName, strFile, strPageName, nLocation, trFilter); if( 0 != nRet ) out_str("Failed to load import filter"); ASCIMP ascimp;
Importing
119
9.2 Importing Images

ascimp = trFilter.ASCIMP;// convert filter tree to ASCIMP struct ascimp.iRenameCols = 0; // 0 to keep default column name, 1 to rename column nRet = wks.ImportASCII(strFile, ascimp); if(0 == nRet) out_str("Import successful"); }
There are times when there is no existing filter for importing a data file. In these cases you will need to make an import filter using Origin's Import Wizard. Using Origin C and the impFile XFunction you can import data files using both Origin's included import filters and your own. For a detailed example of calling the impFile X-Function from Origin C, please refer to the Calling X-Functions in Origin C section.
9.2 Importing Images

Origin allows you to import images into a matrix or a worksheet cell, and onto a graph. The following sections will show you how to import images in your Origin C applications.
9.2.1
Import Image into Matrix
The following example function demonstrates how to import an image file into a matrix. The function takes three arguments: matrix name, file name, and grayscale depth. The key functions being called in this example are oimg_image_info and oimg_load_image. The first is used to get information about the image contained in the image file. The information obtained is used in preparing the target matrix. The latter function is used to do the actual importing of the image file into the target matrix as grayscale data values.
#include <import_image.h> // needed for oimg_ functions bool import_image_to_matrix_data( LPCSTR lpcszMatrixName, // matrix book name LPCSTR lpcszFileName, // image file name int nGrayDepth) // import as 8-bit or 16-bit gray { // Get the target matrix object MatrixObject mo(lpcszMatrixName); if( !mo.IsValid() ) return false; // Get source image information int nWidth, nHeight, nBPP; if( !oimg_image_info(lpcszFileName, &nWidth, &nHeight, &nBPP) ) return false; // Set target matrix to same dimensions as source image if( !mo.SetSize(nHeight, nWidth, 0) ) return false;
120
Importing
9.2.2 Import Image into Worksheet Cell

// Set target matrix data size int nDataType = (16 == nGrayDepth ? FSI_USHORT : FSI_BYTE); if( !mo.SetInternalData(nDataType, FALSE, FALSE) ) return false; // Import the image into the matrix bool bRet; if( FSI_USHORT == nDataType ) { Matrix<WORD>& mm = mo.GetDataObject(); bRet = oimg_load_image(lpcszFileName, &mm, 16, nHeight, nWidth); } else // FSI_BYTE { Matrix<BYTE>& mm = mo.GetDataObject(); bRet = oimg_load_image(lpcszFileName, &mm, 8, nHeight, nWidth); } return bRet; }
9.2.2
Import Image into Worksheet Cell
The following example will embed a JPEG image from a file into a worksheet cell. This is accomplished using the AttachPicture method of the Worksheet class.
int nRow = 0, nCol = 0; string strFile = "D:\\Graph1.jpg"; DWORD dwEmbedInfo = EMBEDGRAPH_KEEP_ASPECT_RATIO; Worksheet wks = Project.ActiveLayer(); if( wks.AttachPicture(nRow, nCol, strFile, dwEmbedInfo) ) { wks.Columns(nCol).SetWidth(20); wks.AutoSize(); }
9.2.3
Import Image to Graph
The following example will embed a JPEG image from a file onto a graph layer. This is accomplished using the image_import_to_active_graph_layer global function.
#include <image_utils.h> // make sure image_utils.c is compiled before calling // the image_import_to_active_graph_layer function. LT_execute("run.LoadOC(Originlab\\image_utils.c)"); string strFile = "D:\\Graph1.jpg"; image_import_to_active_graph_layer(strFile);
Importing
121
10
Exporting
10.1 Exporting Worksheets

The Worksheet class has the ExportASCII method for saving worksheet data to a file. The method has arguments for specifying the starting row and column and the ending row and column. It also allows you to specify how to handle missing data values and whether column labels should be exported or not. All of the examples below assume wks is a valid Worksheet object and strFileName is a string object containing the full path and name of the target file. The first example will save all the data in the worksheet to a file using the tab character as the delimiter and blanks for missing values.
wks.ExportASCII(strFileName, WKS_EXPORT_ALL|WKS_EXPORT_MISSING_AS_BLANK);
The next example will save all the data in a worksheet to a file, with a comma as the delimiter and blanks for missing values. In addition the column labels are also saved.
wks.ExportASCII(strFileName, WKS_EXPORT_ALL|WKS_EXPORT_LABELS|WKS_EXPORT_MISSING_AS_BLANK, ',');
The final example will save the first two columns of data in a worksheet to a file, using a comma as the delimiter and blanks for missing values. In addition, the column labels are also saved. Row and column indices start with zero. The end row and column indices can also be -1 to indicate the last row or last column, respectively.
wks.ExportASCII(strFileName, WKS_EXPORT_ALL|WKS_EXPORT_LABELS|WKS_EXPORT_MISSING_AS_BLANK, '\t', 0, 0, // start with first row, first column -1, 1); // end with last row, second column
10.2 Exporting Graphs

Origin allows users to export graphs to several different image file types. Origin C allows access to this ability using the global export_page and export_page_to_image functions. The following example will export all the graphs in the project to EMF files. The EMF file names will be the same as the graph names, and will be located in the root of drive C.
string strFileName; foreach(GraphPage gp in Project.GraphPages) { strFileName.Format("c:\\%s.emf", gp.GetName());
123
10.3 Exporting Matrices

export_page(gp, strFileName, "EMF"); }
The next example will export the active graph to an 800x600 JPEG file. The JPEG file name will be the name of the graph and will be located in the root of drive C.
GraphPage gp; gp = Project.ActiveLayer().GetPage(); if( gp ) // if active page is a graph { string strFileName; strFileName.Format("c:\\%s.emf", gp.GetName()); export_page_to_image(strFileName, "JPG", gp, 800, 600); }
10.3 Exporting Matrices

An Origin Matrix can be exported to an ASCII data file or an image file.
10.3.1 Export Matrix to ASCII Data File

The following example shows how to export ASCII data from the active matrix window to a *.txt file. You need to include the oExtFile.h file for the export_matrix_ascii_data function.
file ff; if ( !ff.Open("C:\\ExpMatData.txt", file::modeCreate|file::modeWrite) ) return; //fail to open file for write string strRange; MatrixLayer ml = Project.ActiveLayer(); ml.GetRangeString(strRange); LPCSTR vector<string> DWORD lpcszSep = "\t"; vXLabels, vYLabels; // empty means no label dwCntrl = GDAT_FULL_PRECISION | GDAT_MISSING_AS_DASHDASH;
// return 0 for no error int nErr = export_matrix_ascii_data(&ff, strRange, ml.GetNumRows(), ml.GetNumCols(), lpcszSep, &vXLabels, &vYLabels, dwCntrl);
10.3.2 Export Image from Matrix to Image File

The following example shows how to export a matrix to an image file. You need to include the image_utils.h file for the export_Matrix_to_image function.
MatrixLayer ml = Project.ActiveLayer(); MatrixObject mo = ml.MatrixObjects(); export_Matrix_to_image("c:\\matrixImg.jpg", "jpg", mo);
124
Exporting
11
Analysis and Applications
Origin C supports functions that are valuable to data analysis, as well as mathematic and scientific applications. The following sections provide examples on how to use the more common of these functions, broken down by categories of use.
11.1 Mathematics
11.1.1 Normalize
The following example shows how to pick a point in a data plot (curve) and then normalize all curves in the layer to the same value at that point. This snippet of code assumes a graph layer with multiple curves is active and all curves share the same X values. This assumption is typical in spectroscopy.
GraphLayer gl = Project.ActiveLayer(); if( !gl ) return; // Allow user to click and select one particular point of one particular curve GetGraphPoints mypts; mypts.SetFollowData(true); mypts.GetPoints(1, gl); vector vx, vy; vector<int> vn; if(mypts.GetData(vx, vy, vn) == 1) { // Save index and y value of picked point int nxpicked = vn[0] - 1; double dypicked = vy[0]; // Loop over all data plots in layer foreach( DataPlot dp in gl.DataPlots ) { // Get the data range and then the y column for current plot XYRange xy; Column cy; if(dp.GetDataRange(xy) && xy.GetYColumn(cy)) { // Get a vector reference to y values from the y column vectorbase &vycurrent = cy.GetDataObject(); // Scale vector so y value matches user-picked point vycurrent *= dypicked/vycurrent[nxpicked]; } } }
125
11.1 Mathematics
11.1.2 Interpolation/Extrapolation
The ocmath_interpolate function is used to do interpolation/extrapolation with modes of Linear, Spline and B-Spline.
// Make sure there are 4 columns in active worksheet // The first two columns are source xy data, // 3rd column has input x data, 4th column to put output y. Worksheet wks = Project.ActiveLayer(); wks.SetSize(-1, 4); DataRange drSource; drSource.Add(wks, 0, "X"); // 1st column - source x data drSource.Add(wks, 1, "Y"); // 2nd column - source y data vector vSrcx, vSrcy; drSource.GetData(&vSrcx, 0); drSource.GetData(&vSrcy, 1); DataRange drOut; drOut.Add(wks, 2, "X"); // 3rd column - input x data drOut.Add(wks, 3, "Y"); // 4th column - interpolated y data vector vOutx, vOuty; drOut.GetData(&vOutx, 0); int nSrcSize = vSrcx.GetSize(); int nOutSize = vOutx.GetSize(); vOuty.SetSize(nOutSize); int nMode = INTERP_TYPE_BSPLINE; double dSmoothingFactor = 1; int iRet = ocmath_interpolate(vOutx, vOuty, nOutSize, vSrcx, vSrcy, nSrcSize, nMode, dSmoothingFactor); drOut.SetData(&vOuty, &vOutx);
11.1.3 Integration
Origin C provides access to NAG's integral routines to perform integration. With Origin C and NAG you can do integration on a normal integrand, an integrand with parameters, an integrand with oscillation, an infinite integral, higher dimension integration, and more. The following examples show how to do integration with NAG. Your Origin C code will need to include the NAG header file at least once before your code calls any NAG functions.
#include <OC_nag8.h> // NAG declarations
Simple Integral Function

The first example shows how to do a basic integration on a simple integrand with only one integration variable.
// NAG_CALL denotes proper calling convention. You may treat it
126
11.1.3 Integration
// like a function pointer and define your own integrand double NAG_CALL func(double x) { return (x*sin(x*30.0)/sqrt(1.0-x*x/(PI*PI*4.0))); } void nag_d01ajc_ex() { double a = 0.0; double b = PI * 2.0; // integration interval double epsabs, abserr, epsrel, result; // you may use epsabs and epsrel and this quantity to enhance your desired // precision when not enough precision encountered epsabs = 0.0; epsrel = 0.0001; // The max number of sub-intervals needed to evaluate the function in the // integral. For most cases 200 to 500 is adequate and recommmended. int max_num_subint = 200; Nag_QuadProgress qp; NagError fail; d01ajc(func, a, b, epsabs, epsrel, max_num_subint, &result, &abserr, &qp, &fail); // // // // if { NAG_FREE(qp.sub_int_beg_pts); NAG_FREE(qp.sub_int_end_pts); NAG_FREE(qp.sub_int_result); NAG_FREE(qp.sub_int_error); } printf("%g\n", result); } For the error other than the following three errors which are due to bad input parameters or allocation failure. You will need to free the memory allocation before calling the integration routine again to avoid memory leakage (fail.code != NE_INT_ARG_LT && fail.code != NE_BAD_PARAM && fail.code != NE_ALLOC_FAIL)
Integral Function with Parameters

The next example shows how to define and perform integration on an integrand with parameters. Notice that the parameters are passed to the integrator by a user-defined structure. This avoids having to use static variables as parameters of the integrand, and makes it thread-safe. This example can also be adapted to use NAG's infinite integrator. For instance, by enabling the line calling the infinite integrator d01smc function, the example can be used to perform infinite integration.
struct user // integrand parameters { double A; double Xc;
127
11.1 Mathematics
double W; }; // Function supplied by user, return the value of the integrand at a given x. static double NAG_CALL f_callback(double x, Nag_User *comm) { struct user *param = (struct user *)(comm->p); return param->A * exp(-2 * (x - param->Xc) * (x - param->Xc) / param->W / param->W) / (param->W * sqrt(PI / 2)); }
Now, we set parameter values for the function and define the additional parameters necessary to perform the integration. The integration is then performed by a single function call, passing the parameters as arguments.
void nag_d01sjc_ex() { double a = 0.0; double b = 2.0; // integration interval // The following variables are used to control // the accuracy and precision of the integration. double epsabs = 0.0; // absolute accuracy, set negative to use relative double epsrel = 0.0001; // relative accuracy, set negative to use absolute int max_num_subint = 200; // max sub-intervals, 200 to 500 is recommended // Result keeps the approximate integral value returned by the algorithm // abserr is an estimate of the error which should be an upper bound // for |I - result| where I is the integral value double result, abserr; // The structure of type Nag_QuadProgress, it contains pointers // allocated memory internally with max_num_subint elements Nag_QuadProgress qp; // The NAG error parameter (structure) NagError fail; // Parameters passed to integrand by NAG user communication struct struct user param; param.A = 1.0; param.Xc = 0.0; param.W = 1.0; Nag_User comm; comm.p = (Pointer)&param; // Perform integration // There are 3 kinds of infinite boundary types you can use in Nag infinite // integrator Nag_LowerSemiInfinite, Nag_UpperSemiInfinite, Nag_Infinite /* d01smc(f_callback, Nag_LowerSemiInfinite, b, epsabs, epsrel, max_num_subint, &result, &abserr, &qp, &comm, &fail); */ d01sjc(f_callback, a, b, epsabs, epsrel, max_num_subint, &result, &abserr, &qp, &comm, &fail); // check the error by printing out error message if (fail.code != NE_NOERROR)
128
11.1.3 Integration
printf("%s\n", fail.message); // // // // if { NAG_FREE(qp.sub_int_beg_pts); NAG_FREE(qp.sub_int_end_pts); NAG_FREE(qp.sub_int_result); NAG_FREE(qp.sub_int_error); } printf("%g\n", result); } For errors other than the following three errors which are due to bad input parameters, or allocation failure, you will need to free the memory allocation before calling the integration routine again to avoid memory leakage. (fail.code != NE_INT_ARG_LT && fail.code != NE_BAD_PARAM && fail.code != NE_ALLOC_FAIL)
Multi-dimension Integral Function

For integrals of dimension higher than 2, you can call the NAG integrator function d01wcc to perform the integration. Our user defined call back function will be passed to the NAG d01wcc function.
double NAG_CALL f_callback(int n, double* z, Nag_User *comm) { double tmp_pwr; tmp_pwr = z[1]+1.0+z[3]; return z[0]*4.0*z[2]*z[2]*exp(z[0]*2.0*z[2])/(tmp_pwr*tmp_pwr); }
Main function:
void nag_d01wcc_ex() { // Input variables int ndim = NDIM; // the integral dimension double a[4], b[4]; for(int ii=0; ii < 4; ++ii) // integration interval { a[ii] = 0.0; b[ii] = 1.0; } int minpts = 0; int maxpts = MAXPTS; // maximum number of function evaluation double eps = 0.0001; // set the precision // Output variable double finval, acc; Nag_User comm; NagError fail; d01wcc(ndim, f_callback, a, b, &minpts, maxpts, eps, &finval, &acc, &comm, &fail); if (fail.code != NE_NOERROR) printf("%s\n", fail.message); if (fail.code == NE_NOERROR || fail.code == NE_QUAD_MAX_INTEGRAND_EVAL) { printf("Requested accuracy =%12.2e\n", eps); printf("Estimated value =%12.4f\n", finval);
129
11.2 Statistics
printf("Estimated accuracy =%12.2e\n", acc); } }
11.1.4 Differentiation
The ocmath_derivative function is used to do simple derivative calculations without smoothing. The function is declared in ocmath.h as shown below.
int ocmath_derivative( const double* pXData, double* pYData, uint nSize, DWORD dwCntrl = 0);
The function ignores all missing values and computes the derivative by taking the average of the two slopes between the point and each of its neighboring data points. If the dwCntrl argument uses the default value of 0, the function fills in the average when data changes direction.
if( OE_NOERROR == ocmath_derivative(vx, vy, vx.GetSize()) ) out_str("successfully");
If dwCntrl is set to DERV_PEAK_AS_ZERO, the function fills in zero if data changes direction.
if( OE_NOERROR == ocmath_derivative(vx, vy, vx.GetSize(), DERV_PEAK_AS_ZERO) ) out_str("successfully");
11.2 Statistics
Often we want to do statistics on the selected data in a worksheet, i.e. one column, one row, or an entire worksheet. The Working with Data: Numeric Data: DataRange chapter shows how to construct a data range object by column/row index, then get the raw data into a vector.
11.2.1 Descriptive Statistics on Columns and Rows

The ocmath_basic_summary_stats function is used to compute basic descriptive statistics, such as total number, mean, standard deviation, and skewness, for raw data. For more details, refer to Origin C help. The following Origin C code calculates and outputs the number of points, the mean, and the standard error of mean on the data in the vector object named vData.
int N; double Mean, SE; ocmath_basic_summary_stats(vData.GetSize(), vData, &N, &Mean, NULL, &SE); printf("N=%d\nMean=%g\nSE=%g\n", N, Mean, SE);
11.2.2 Frequency Count

The ocmath_frequency_count function is used to calculate the frequency count, according to the options in the FreqCountOptions structure.
// Source data to do frequency count vector vData = {0.11, 0.39, 0.43, 0.54, 0.68, 0.71, 0.86};
130
11.2.3 Correlation Coefficient

// Set options, including bin size, from, to and border settings. int nBinSize = 5; FreqCountOptions fcoOptions; fcoOptions.FromMin = 0; fcoOptions.ToMax = 1; fcoOptions.StepSize = nBinSize; fcoOptions.IncludeLTMin = 0; fcoOptions.IncludeGEMax = 0; vector vBinCenters(nBinSize); vector vAbsoluteCounts(nBinSize); vector vCumulativeCounts(nBinSize); int nOption = FC_NUMINTERVALS; // to extend last bin if not a full bin int nRet = ocmath_frequency_count( vData, vData.GetSize(), &fcoOptions, vBinCenters, nBinSize, vAbsoluteCounts, nBinSize, vCumulativeCounts, nBinSize, nOption); if( STATS_NO_ERROR == nRet ) out_str("Done");
In addition, there are two functions to calculate frequency count for discrete/categorical data. One is ocu_discrete_frequencies for text data, and the other is ocmath_discrete_frequencies for numeric data. Also, there are two functions to calculate frequency count on 2 dimensions: ocmath_2d_binning_stats and ocmath_2d_binning.
11.2.3 Correlation Coefficient

The ocmath_corr_coeff function is used to calculate the Pearson rank, Spearman rank and Kendall rank correlation coefficients.
matrix mData = {{10,12,13,11}, {13,10,11,12}, {9,12,10,11}}; int nRows = mData.GetNumRows(); int nCols = mData.GetNumCols(); matrix mPeaCorr(nCols, nCols); matrix mPeaSig(nCols, nCols); matrix mSpeCorr(nCols, nCols); matrix mSpeSig(nCols, nCols); matrix mKenCorr(nCols, nCols); matrix mKenSig(nCols, nCols); if(STATS_NO_ERROR == ocmath_corr_coeff(nRows, nCols, mData, mPeaCorr, mPeaSig, mSpeCorr, mSpeSig, mKenCorr, mKenSig)) { out_str("Done"); }
131
11.3 Curve Fitting
11.2.4 Normality Test

Use the *ocmath_shapiro_wilk_test function to perform a Shapiro-Wilk Normality Test. Use the *ocmath_lilliefors_test function to perform a Lilliefors Normality Test. Use the *ocmath_kolmogorov_smirnov_test function to perform a Kolmogorov-Smirnov Normality Test.
vector vTestData = {0.11, 0.39, 0.43, 0.54, 0.68, 0.71, 0.86}; NormTestResults SWRes; if( STATS_NO_ERROR == ocmath_shapiro_wilk_test(vTestData.GetSize(), vTestData, &SWRes, 1) ) { printf("DOF=%d, TestStat=%g, Prob=%g\n", SWRes.DOF, SWRes.TestStat, SWRes.Prob); }
11.3 Curve Fitting

NLFit is the new fitter starting with Origin version 8. This new fitter handles the fitting process with a copy of the data while performing iterations. This results in faster operation compared to older versions where the fitter directly accessed data repeatedly from the worksheet. There are two classes available to perform nonlinear fitting:
NLFit This is the Origin C class that wraps the low level API from the new fitting engine. This class has no knowledge of Origin and works with copies of data in buffers. In order to use this class, you will be responsible in preparing all necessary buffers (pointers). This separation prepares for the future implementation of performing fitting as a background process. NLFitSession This is a higher level Origin C class with a friendly interface that wraps the NLFit class to Origin objects. This class is the kernel in the new NLFit Dialog. We recommend that you use this class in your Origin C code, as the process to interface to Origin is rather complicated and the NLFitSession classtakes care of this complexity for you.
11.3.1 Nonlinear Fitting

Before you use the NLFitSession class, you need to include a specific header file:
#include <..\originlab\NLFitSession.h>
You also need to include and compile the OriginC\Originlab\nlsf_utils.c file to your current workspace. Run the Labtalk command below in the Command window, or from your script file, to programmatically add the file:
Run.LoadOC(Originlab\nlsf_utils.c, 16)
Define an NLFitSession object, and set the fitting function as Gauss:

// Set Function NLFitSession nlfSession;
132
11.3.1 Nonlinear Fitting

if ( !nlfSession.SetFunction("Gauss") ) { out_str("Fail to set function!"); return; } // Get parameter names and number: vector<string> vsParamNames; int nNumParamsInFunction = nlfSession.GetParamNamesInFunction(vsParamNames);
Set two XY datasets with DATA_MODE_GLOBAL mode, to perform global fitting with sharing of parameters:
int nNumData = 2; // Set the first dataset if ( !nlfSession.SetData(vY1, vX1, NULL, 0, nNumData) ) { out_str("Fail to set data for the first dataset!"); return; } // Set the second dataset if ( !nlfSession.SetData(vY2, vX2, NULL, 1, nNumData, DATA_MODE_GLOBAL) ) { out_str("Fail to set data for the second dataset!"); return; }
Run parameter initialization code to initialize parameter values:

// Parameter initialization if ( !nlfSession.ParamsInitValues() ) { out_str("Fail to init parameters values!"); return; }
Alternately, you can directly set parameter values one by one:

vector vParams(nNumParamsInFunction*nNumData); // set parameter value for the first dataset vParams[0] = 5.5; // y0 vParams[1] = 26; // A vParams[2] = 8; // xc vParams[3] = 976; // w // set parameter value for the second dataset vParams[4] = 2.3; // y0 vParams[5] = 26; // A vParams[6] = 10.3; // xc vParams[7] = 102; // w int nRet = nlfSession.SetParamValues(vParams); if(nRet != 0) // 0 means no error return;
Share xc parameter between the two datasets:

int nSharedParamIndex = 1; // 1, the index of xc in Gauss function nlfSession.SetParamShare(nSharedParamIndex);
Perform the fit and output status message:

// Do fit
133
11.3 Curve Fitting

int nFitOutcome; nlfSession.Fit(&nFitOutcome); string strOutcome = nlfSession.GetFitOutCome(nFitOutcome); out_str("Outcome of the fitting session : " + strOutcome);
Get fit statistic result:

int nDataIndex = 0; RegStats fitStats; NLSFFitInfo fitInfo; nlfSession.GetFitResultsStats(&fitStats, &fitInfo, false, nDataIndex); printf("# Iterations=%d, Reduced Chisqr=%g\n", fitInfo.Iterations, fitStats.ReducedChiSq);
Get final fit parameter values:

vector vFittedParamValues, vErrors; nlfSession.GetFitResultsParams(vFittedParamValues, vErrors); // The parameter xc is shared in two input data. // So the value of xc is same for all data sets, and it only appears one time // in the fitted parameter values - vParamValues. // vsParamNames contains the parameter names in Gauss function - y0, xc, w, A. // The following to add parameter names for the second dataset without xc. vsParamNames.Add("y0"); vsParamNames.Add("w"); vsParamNames.Add("A"); for( int nParam = 0; nParam < vFittedParamValues.GetSize(); nParam++) { printf("%s = %f\n", vsParamNames[nParam], vFittedParamValues[nParam]); }
Calculate fit curve Y values using the final fit parameters:

vector vFitY1(vX1.GetSize()), vFitY2(vX2.GetSize()); // Get fitted Y for the first dataset nlfSession.GetYFromX(vX1, vFitY1, vX1.GetSize(), 0); // Get fitted Y for the second dataset nlfSession.GetYFromX(vX2, vFitY2, vX1.GetSize(), 1);
11.3.2 Accessing FDF File

Fitting function settings stored in an FDF file can be loaded into a tree variable. You will need to include the OriginC\system\FDFTree.h file:
#include <FDFTree.h>
Then use the nlsf_FDF_to_tree function:

string strFile = GetOpenBox("*.FDF"); Tree tr; if(nlsf_FDF_to_tree(strFile, &tr)) { out_tree(tr); }
134
11.4.1 Smoothing
11.4 Signal Processing

Origin C provides a collection of global functions and NAG functions for signal processing, ranging from smoothing noisy data to Fourier Transform (FFT), Short-time FFT(STFT), Convolution and Correlation, FFT Filtering, and Wavelet analysis. The Origin C functions are under the Origin C help -> Origin C Reference -> Global Functions > Signal Processing category.
11.4.1 Smoothing
The ocmath_smooth function support 3 methods: median filter, Savitzky-Golay smoothing and adjacent averaging smoothing.
vector vSmooth; // output vSmooth.SetSize(vSource.GetSize()); //do Savitzky-Golay smoothing, Left=Right=7, quadratic int nLeftpts = nRightpts = 3; int nPolydeg = 2; int nRet = ocmath_smooth(vSource.GetSize(), vSource, vSmooth, nLeftpts, SMOOTH_SG, EDGEPAD_NONE, nRightpts, nPolydeg);
11.4.2 FFT
Before using fft_* functions, you need to include fft_utils.h.
#include <fft_utils.h>
FFT
fft_real performs a discrete Fourier transform(FFT_FORWARD) or inverse Fourier transform(FFT_BACKWARD).
fft_real(vSig.GetSize(), vSig, FFT_FORWARD); // return 0 for no error
Frequency Spectrum
fft_one_side_spectrum is used to compute the one side spectrum of FFT Result.
fft_one_side_spectrum(vSig.GetSize(), vSig); // return 0 for no error
IFFT
fft_real(vSig.GetSize(), vSig, FFT_BACKWARD); // return 0 for no error
135
11.4 Signal Processing
STFT
The stft_real function is used to perform a Short-Time-Fourier-Transform on 1d signal real data. The stft_complex function is used to perform a Short-Time-Fourier-Transform on 1d signal complex data. The following is an example for real data.
int nWinSize = 4; vector win(nWinSize); get_window_data(RECTANGLE_WIN, nWinSize, win); matrix stft; double stime, sfreq; vector sig = {0, 0, 0, 1, 1, 0, 0, 0}; stft_real(sig, win, 0.1, 1, 4, stft, stime, sfreq); for (int ii = 0; ii < stft.GetNumRows(); ii++) { for (int jj = 0; jj < stft.GetNumCols(); jj++) printf ("%f\t", stft[ii][jj]); printf ("\n"); }
11.4.3 FFT Filtering

Origin C supports multiple filter types for performing FFT Filtering, including: low pass, high pass, band pass, band block, threshold, and low pass parabolic. For example:
double dFc = 6.5; int iRet = fft_lowpass(vecSignal, dFc, &vecTime);
11.4.4 Wavelet Analysis

In Origin C, you can call a NAG function to do Wavelet analysis. To see all wavelet functions, go to the Origin C help -> Origin C Reference -> Global Function -> NAG Functions -> Accessing NAG Functions Category and Help -> Wavelet category. It is necessary to include the related header.
#include <..\OriginLab\wavelet_utils.h>
The following is an example of a real type, one-dimensional, continuous wavelet transform.

int n = vX.GetSize(); int ns = vScales.GetSize(); matrix mCoefs(ns, n); NagError fail; nag_cwt_real(Nag_Morlet, 5, n, vX, ns, vScales, mCoefs, &fail);
136
11.5.1 Creating a Baseline
11.5 Peaks and Baseline

11.5.1 Creating a Baseline
The ocmath_create_baseline_by_masking_peaks function can create a baseline according to only positive peaks, only negative peaks, or both direction peaks. The following example shows how to create a baseline for the positive peaks and the negative peaks in input XY data(vx, vy).
// Allocate memory for baseline XY vectors vector vxBaseline(vx.GetSize()), vyBaseline(vx.GetSize()); // find baseline XY data int nRet = ocmath_create_baseline_by_masking_peaks(vx.GetSize(), vx, vy, vxBaseline.GetSize(), vxBaseline, vyBaseline, BOTH_DIRECTION); // Ascending sort baseline XY data by X data. if( OE_NOERROR == nRet ) { vector<uint> vn; vxBaseline.Sort(SORT_ASCENDING, true, vn); vyBaseline.Reorder(vn); }
11.5.2 Removing a Baseline

If the x coordinate of a baseline is the same as that of the peak curve, you can directly subtract, otherwise you need do interpolation before removing the baseline. The following code shows how to do interpolation and then remove a baseline. Assume the current worksheet has 4 columns in which to put peak XY data and baseline XY data.
Worksheet wks = Project.ActiveLayer(); Column colPeakX(wks, 0), colPeakY(wks, 1); Column colBaseLineX(wks, 2), colBaseLineY(wks, 3); // Get peak XY data. // Get Y data by reference since want to subtract baseline on it below. vector vPeakX = colPeakX.GetDataObject(); vector& vPeakY = colPeakY.GetDataObject(); // Get base line data vector vBaselineX = colBaseLineX.GetDataObject(); vector vBaselineY = colBaseLineY.GetDataObject(); if( vPeakX.GetSize() != vPeakY.GetSize() || vPeakX.GetSize() == 0 || vBaselineX.GetSize() == 0 ) return; // do interpolation on baseline data to keep x coordinate same as peak data. vector vyBaseTemp(vPeakX.GetSize());
137
11.5 Peaks and Baseline

if(OE_NOERROR != ocmath_interpolate(vPeakX, vyBaseTemp, vPeakX.GetSize(), vBaselineX, vBaselineY, vBaselineX.GetSize(), INTERP_TYPE_LINEAR)) { return; } // subtract base line vPeakY -= vyBaseTemp;
11.5.3 Finding Peaks

The ocmath_find_peaks_* function is used to find peaks by multiple methods. The following example shows how to find a local maximum point in a local scope selected by nLocalPts. For a current point marked by nIndex, the scope is [nIndex-nLocalPts, nIndex+nLocalPts].
// Allocate memory for output vectors UINT nDataSize = vxData.GetSize(); vector vxPeaks(nDataSize), vyPeaks(nDataSize); vector<int> vnIndices(nDataSize); // nDataSize, on input, the size of vxData, vyData; // on output, return number of peaks int nLocalPts = 10; int nRet = ocmath_find_peaks_by_local_maximum( &nDataSize, vxData, vyData, vxPeaks, vyPeaks, vnIndices, POSITIVE_DIRECTION | NEGATIVE_DIRECTION, nLocalPts); if(OE_NOERROR == nRet) { printf("Peak Num=%d\n", nDataSize); vxPeaks.SetSize(nDataSize); vyPeaks.SetSize(nDataSize); }
Origin C supports two functions: ocmath_test_peaks_by_height and ocmath_test_peaks_by_number, to verify peaks by specified height and peak number, respectively. The following is an example showing how to verify peaks by minimum peak height.
// Get minimum and maximum from source Y data double dMin, dMax; vyData.GetMinMax(dMin, dMax); // Get // And double double the bigger value from the highest point or the lowest point. multiply 20% to get the peak minimum height. dTotalHeight = max(abs(dMax), abs(dMin)); dPeakMinHeight = dTotalHeight * 20 / 100;
// Verify peaks by specified minimum height nRet = ocmath_test_peaks_by_height(&nDataSize, vxPeaks, vyPeaks, vnIndices, dPeakMinHeight); printf("Peak Num = %d\n", nDataSize); for(int ii=0; ii<nDataSize; ii++) {
138
11.5.4 Integrating and Fitting Peaks

printf("Peak %d: (%f,%f)\n", ii+1, vxPeaks[ii], vyPeaks[ii]); }
11.5.4 Integrating and Fitting Peaks

Integrate Peak
The ocmath_integrate function is used to integrate to find the area under a curve. The following example shows how to perform integration on the sub curve of one peak.
int i1 = 51, i2 = 134; // From/to index to set the sub range of one peak IntegrationResult IntResult; // Output, integration result vector vIntegral(i2+1); // Output, integral data // Integrate and output result if( OE_NOERROR == ocmath_integrate(vx, vy, i1, i2, &IntResult, vIntegral, MATHEMATICAL_AREA, NULL, false, SEARCH_FROM_PEAK) ) { printf("Peak 1: Peak Index = %d, Area = %g, FWHM = %g, Center = %g, Height = %g\n", IntResult.iPeak, IntResult.Area, IntResult.dxPeak, IntResult.xPeak, IntResult.yPeak); }
Fitting Peak
The Origin C NLFitSession class supports a method to fit peaks with a different fitting function. Refer to the Curve Fitting chapter to see a more in depth description and examples about this class.
11.6 Using NAG Functions

11.6.1 Header Files
To call any NAG function, you need to include the header file or files where the NAG function is declared. A single header file, which includes all the commonly used NAG header files, is provided below. Usually, you can just include this header file in your code.
#include <OC_nag8.h> // includes all common NAG header files
If only a single NAG function or just a few are used, you can also just include its (their) own individual NAG header file(s). For example, if the NAG function f02abc is called in the code, then two related NAG header files need to be included.
#include <NAG8\nag.h> // NAG struct and type definitions #include <NAG8\nagf02.h> // contains the f02 function declarations
139
11.6.2 Error Structure

All NAG functions accept one argument, which is a pointer of NagError structure. This structure is used to test whether the NAG function is executing successfully or not. The example below shows whether the NAG function f02abc works successfully.
NagError err; f02abc(n, mx, n, r, v, n, &err); if( err.code != NE_NOERROR ) printf(err.message); // // // // Declare an error structure Call NAG f02abc function If an error occurred Output error message
If you don't need to know whether the call is successful or not, the error structure declaration is not needed. And the NAGERR_DEFAULT macro can be passed instead. This macro is a NULL pointer. To ensure compatibility with future versions of NAG functions, it will be better to use this macro if you can work without error structure.
f02abc(n, mx, n, r, v, n, NAGERR_DEFAULT);
11.6.3 Callback Functions

In the NAG Library, most of the routines involve callback functions. Before defining a callback function, you need to know the return type and argument types of the callback function that NAG will expect when calling it. Take the NAG function d01ajc for example. In the header file nagd01.h, we can see that the first argument is NAG_D01AJC_FUN f. This argument is a callback function. Then in nag_types.h, we find that NAG_D01AJC_FUN is a type of NAG_D01_FUN, which is defined as:
typedef double (NAG_CALL * NAG_D01_FUN)(double);
Then we can define the callback function as follows:

double NAG_CALL myFunc(double x) { double result; // Do processing on 'x' return result; }
When calling the NAG function d01ajc, myFunc (defined above) can be passed as the first argument.
Calling c05adc Example

This example will show how to call the NAG function c05adc, the fourth argument of which is the callback function argument. This callback function of type NAG_C05ADC_FUN is defined in nag_types.h.
typedef double (NAG_CALL * NAG_C05ADC_FUN)(double);
From the definition, we know that both the return type and the only argument type are double. So we define the callback function as follows:
double NAG_CALL myC05ADCfunc(double x) {
140
11.6.4 NAG Get Data from Origin

return exp(-x)-x; }
The following code shows how to call the c05adc function by passing the myC05ADCfunc callback function.
double a = 0.0, b = 1.0, x, ftol = 0.0, xtol = 1e-05; NagError err; c05adc(a, b, &x, myC05ADCfunc, xtol, ftol, &err);

Many NAG functions take a pointer to an array of numeric data. Both Origin worksheets and matrix sheets allow getting a pointer to their data. This pointer can be passed to NAG functions. In Origin C, data is commonly passed using Dataset or DataRange objects. The sections below will show how to pass data from a worksheet by using Dataset and DataRange. The DataRange way is recommended.
Dataset
A Dataset object can be passed to a NAG function as long as the Dataset is of the data type expected by the NAG function. The data type of an Origin worksheet column is Text & Numeric by default. For most, but not all, NAG functions, this data type is not allowed to be passed, because NAG functions expect floating or integer pointers. If you make sure that the Dataset is of the type expected by the NAG function, the following code can be used to pass a Dataset object to a NAG function.
// Get access to the active worksheet. Worksheet wks = Project.ActiveLayer(); // Construct Datasets to get access to the wks data. Dataset dsX, dsY; dsX.Attach(wks, 0); dsY.Attach(wks, 1); // Call NAG's nag_1d_spline_interpolant(e01bac) function. NagError err; Nag_Spline spline; e01bac(m, dsX, dsY, &spline, &err);
DataRange
The DataRange class provides the GetData method for getting data from a worksheet into a vector, even if the worksheet columns are of the Text & Numeric data type. The GetData method can also ignore the rows with missing values easily, which is very important when passing data to NAG functions. Using DataRange to pass data from Origin to NAG functions is much safer, and is recommended. The following example demonstrates how to do that.
void call_NAG_example() {
141

int i, numPoints = 5; // Create a new worksheet page. WorksheetPage pg; pg.Create("origin"); // Get access to the active worksheet and add two more columns. Worksheet wks = Project.ActiveLayer(); // Add X2 column i = wks.AddCol(); Column col(wks, i); col.SetType(OKDATAOBJ_DESIGNATION_X); // Add Y2 column wks.AddCol(); // Create some starting XY values in first two columns Dataset dsX, dsY; dsX.Attach(wks, 0); dsY.Attach(wks, 1); for (i = 0; i < numPoints; i++) { int r = rnd(0) * 10; if (r < 1) r = 1; if (i > 0) r += dsX[i - 1]; dsX.Add(r); dsY.Add(rnd(0)); } // Create data range object. DataRange dr; dr.Add(wks, 0, "X"); dr.Add(wks, 1, "Y"); // Copy data from wks to vector using data range. // This copy will ignore rows with missing values. vector vX1, vY1; dr.GetData(DRR_GET_DEPENDENT, 0, NULL, NULL, &vY1, &vX1); // Call NAG to calculate coefficients. NagError err; Nag_Spline spline; e01bac(vX1.GetSize(), vX1, vY1, &spline, &err); // Get the spline's XY values vector vX2, vY2; double fit, xarg; for (i = 0; i < vX1.GetSize(); i++) { vX2.Add(vX1[i]); vY2.Add(vY1[i]); if (i < vX1.GetSize() - 1) { xarg = (vX1[i] + vX1[i + 1]) * 0.5; e02bbc(xarg, &fit, &spline, &err); vX2.Add(xarg); vY2.Add(fit); }
142

} // Free memory allocated by NAG NAG_FREE(spline.lamda); NAG_FREE(spline.c); // Copy spline values to worksheet dsX.Attach(wks, 2); dsX = vX2; dsY.Attach(wks, 3); dsY = vY2; }
143
12
Output Objects
12.1 Results Log

The Results Log is an output window that automatically stamps each block of output with the date and time and the name of the window associated with the results. The user interface allows users to configure which results are displayed and to float the window or dock it to Origin's main window. The following example shows the simplest way to output to the Results Log from Origin C using the OutStringToResultsLog method of the Project class. While this is the simplest way to output to the Results Log, it can also be considered the most limited. Each call to the OutStringToResultsLog method is considered an individual log and will be stamped with the current date and time and the name of the associated window.
string str = "Column1\tColumn2\tColumn3\n3.05\t17.22\t35.48"; Project.OutStringToResultsLog(str);
12.2 Script Window

The Script Window is the default output window for Origin C. Whenever you output strings or numeric values they will appear in the Script Window. You can change which window such output appears in by setting LabTalk's Type.Redirection property. This property allows you to redirect your application's output to the Script window, Command window, Results Log, or even a Note window. See LabTalk's Type.Redirection property for more details. The following example will save the current Redirection setting, set it to redirect output to the Script window output, then the Command window, and then restore the saved setting.
string strTypeRedir = "type.redirection"; double dCurTypeRedir; LT_get_var(strTypeRedir , &dCurTypeRedir); // get current LT_set_var(strTypeRedir , 5); // 5 for Script window out_str("Hello Script Window"); LT_set_var(strTypeRedir , 128); // 128 for Command window out_str("Hello Command Window"); LT_set_var(strTypeRedir , dCurTypeRedir); // restore current
The next example will use Type.Redirection and Type.Notes$ to redirect Origin C output to a Note window.
145
12.3 Notes Window

Note note; note.Create(); // Create the target Note window LT_set_str("type.notes$", note.GetName()); LT_set_var("type.redirection", 2); // 2 for Note window out_str("Hello Notes Window");
12.3 Notes Window

The first example shows how to work with the text of a Note window using the Text property. The Text property is a string class type which allows you to use all the string capabilities of strings.
Note note; note.Create(); // Create the target Note window if( note ) { note.Text = "Hello Note window."; note.Text += "\nAnother line of text." }
The next example will use Type.Redirection and Type.Notes$ to redirect Origin C output to a Note window.
Note note; note.Create(); // Create the target Note window LT_set_str("type.notes$", note.GetName()); LT_set_var("type.redirection", 2); // 2 for Note window out_str("Hello Notes Window");
12.4 Report Sheet

The Datasheet class has the GetReportTree and SetReportTree methods for getting and setting a report into a worksheet or matrix sheet.
if( wks.SetReportTree(tr.MyReport) < 0 ) out_str("Failed to set report sheet into worksheet."); if( wks.GetReportTree(tr.MyReport) ) out_tree(tr.MyReport); else out_str("Failed to get report tree from worksheet.");
146
Output Objects
13
Accessing Database
13.1 Importing from a Database

Origin C includes the ability to import data from a database into a worksheet. The following example shows how to do this by importing an Access database file, included in the Origin Samples folder. An ADODB.Reocrdset object can refer to MSDN. To find out how to construct your connection string, refer to DbEdit X-Function
Object ocora; try { ocora = CreateObject("ADODB.Recordset"); } catch(int nError) { out_str("Failed to create ADODB.Recordset"); return FALSE; } // Import stars.mdb from the Origin Samples folder string strDatabaseFile = GetAppPath(1) + "Samples\\Import and Export\\stars.mdb"; // Prepare the database connection string string strConn; strConn.Format("Provider=Microsoft.Jet.OLEDB.4.0; Data Source=%s; User ID=admin; Password=;", strDatabaseFile); // Prepare the SQL string string strQuery = "Select Stars.Index, Stars.Name, Stars.LightYears, Stars.Magnitude From Stars"; ocora.CursorLocation = adUseClient; try { ocora.open(strQuery, strConn, 1, 3); } catch(int nError) { out_str("Failed to open Oracle database"); return FALSE; } Worksheet wks; wks.Create(); //put data into the worksheet.
147
13.2 Exporting into a Database

BOOL out_int("bRet = ", bRet); return bRet; bRet = wks.PutRecordset(ocora);
13.2 Exporting into a Database

Origin C has the ability to export data from a worksheet to a specified database table. The following steps show how to export fitting summary data into a database.
Set up a database named "Analysis" in MySQL, and assume it is running on the machine "Lintilla". 2. Create a table named "FittingSummary" with 9 fields, set the data type of the first two fields as varchar(40) and the rest as double. 3. Open OriginExe\Samples\Curve Fitting\autofit.ogw, and fill the columns on the "Data" layer with data. 4. After recalculating, activate the "Summary" layer, and run the following code to export the result to a database. //user should modify connect and query string according to their database settings. //such as value of Server, Database, UID, PWD etc. #define STR_DB_CONN "Driver={MySQL ODBC 3.51 Driver};\ Server=Lintilla;Port=3306;Option=4;Database=Analysis;UID=test;PWD=test;" #define STR_QUERY "Select * from FittingSummary" bool write_wks_to_db() { Worksheet wks = Project.ActiveLayer(); if ( wks ) return false; //connect to database "Analysis" on "Lintilla" string strConn = STR_DB_CONN; string strQuery = STR_QUERY; Object oConn; oConn = CreateObject("ADODB.Connection"); if ( !oConn ) return error_report("Fail to create ADODB.Connection object!"); oConn.Open(strConn); Object oRecordset; oRecordset = CreateObject("ADODB.Recordset"); if ( !oRecordset ) return error_report("Fail to create ADODB.Recordset object!"); //open recordset oRecordset.CursorLocation = 3; //adUseClient, please refer to MSDN for details oRecordset.Open(strQuery, oConn, 1, 3); //adOpenKeyset, adLockOptimistic int iRowBegin = 0, nRows = 8; //8 rows int iColBegin = 0, nCols = 9; //9 columns //LAYWKSETRECORDSET_APPEND for appending new recordset; 1.
148
Accessing Database
13.3 Accessing SQLite Database

//LAYWKSETRECORDSET_REPLACE for replacing existing recordsets. int nOption = LAYWKSETRECORDSET_APPEND; //append. int nRet = wks.WriteRecordset(oRecordset, nOption, iRowBegin, nRows, iColBegin, nCols); return (0 == nRet); }
13.3 Accessing SQLite Database

SQLite is a software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine, and it has become the most widely deployed SQL database in the world. Due to the excellent features, SQLite is now widely used in different applications and systems. SQLite3 is the latest version released. Origin provides a DLL for accessing SQLite database from Origin C. It is necessary to include a header file that contains the prototypes of SQLite3 APIs:
#include <oc_Sqlite.h>
A simple example of how to use these functions is available at the end of the header file. Origin C also provides a wrapped class, OSQLite, that makes accessing SQLite much easier. To use this Origin C class, the header file containing this class must be included, like:
//DataSet1.1.db is a database file, which contains a table named Originlab //The table is created with the following statement //CREATE TABLE OriginLab(ID INTEGER NOT NULL, NUMBER INTEGER NOT NULL, SALARY INTE //GER NOT NULL, Data BLOB NOT NULL); #include <..\Originlab\oSQLite.h> //required header file #define STR_DATABASE_FILE "E:\\DataSet1.1.db" #define STR_QUERY_STRING "select * from Originlab limit 80" void test_OSQLite() { OSQLite sqlObj(STR_DATABASE_FILE); LPCSTR lpSQL = STR_QUERY_STRING; sqlObj.Select(lpSQL); Worksheet wks; wks.Create("Origin"); sqlObj.Import(wks); //after modify the data, may use the following code to export data //sqlObj.Export("OriginLab", wks); }
Accessing Database
149
14
Accessing LabTalk
Origin C has the ability to get and set LabTalk numeric and string values and run LabTalk scripts.
14.1 Getting and Setting LabTalk Numeric Values

The Origin C LT_get_var and LT_set_var global functions are used for getting and setting LabTalk numeric values. Numeric values include variables, system variables and object properties.
double dOriginVer; LT_get_var("@V", &dOriginVer); printf("Running Origin version %f\n", dOriginVer);
This is how to set the minimum font size used in the Data Display window.
LT_set_var("System.DataDisplay.MinFontSize", 12);
There are times when you will want to temporarily set a LabTalk variable, do some work, and then restore the LabTalk variable to its original value. There are mainly two ways to do this. The first way is the long way to do it using LT_get_var and LT_set_var.
double dProgressBar; LT_get_var("@NPO", &dProgressBar); // get starting value LT_set_var("@NPO", 0); // set new value // // do some work // LT_set_var("@NPO", dProgressBar); // restore starting value
The next way is the simple way using the LTVarTempChange class. To use the class you simply pass the variable name and the temporary value. The constructor saves the starting value into a data member and sets the variable to the temporary value. The destructor will restore the variable to its starting value.
{ LTVarTempChange progressBar("@NPO", 0); // // do some work // }
151
14.2 Getting and Setting LabTalk String Values
14.2 Getting and Setting LabTalk String Values

The Origin C LT_get_str and LT_set_str global functions are used for getting and setting LabTalk string values. String values include variables, string substitution variables and object properties.
char szCustomDateFmt[200]; LT_get_str("System.Date.CustomFormat1$", szCustomDateFmt, 200); printf("Custom Date Format 1: %s\n", szCustomDateFmt);
This is how to set the font used in the Data Display window.
LT_set_str("System.DataDisplay.Font$", "Courier");
This is how to rename the active sheet of the active book.

LT_set_str("wks.name$", "MySheet");
14.3 Running LabTalk Script

The Origin C LT_execute global function allows you to run LabTalk script stored in a string. The Format string method can be useful in passing Origin C variables into the LabTalk script:
string strScript; string strBook = "Book1"; int iColStart = 2, iColEnd = 5; strScript.Format("win -a %s;plotxy %u:%u;", strBook, iColStart, iColEnd); LT_execute(strScript);
The next example calls the LT_execute method of the Layer class instead of the global LT_execute function. When calling the global LT_execute function, the script runs and will operate on the active layer when no layer is specified by the script code. When calling the LT_execute method of the Layer class, the script runs and will operate on the layer instance instead of the active layer.
WorksheetPage wksPg("Book1"); Worksheet wks = wksPg.Layers(0); WorksheetPage wksPgActive; wksPgActive.Create("Origin"); // This page is now active LT_execute("wks.colWidth=16"); // Set column widths of active layer wks.LT_execute("wks.colWidth=8"); // Set column widths of Book1
14.4 Embedding LabTalk Script in Origin C Code

LT_execute allows you to execute the LabTalk script contained in a string, but there are times when you will want to execute a large block of script that you may not want to put into a string, for readability. For those times you can use the _LT_Obj block. The _LT_Obj block allows you to embed a large block of LabTalk script code right into the flow of your Origin C code.
152 Accessing LabTalk
14.4 Embedding LabTalk Script in Origin C Code

out_str("Choose an image file..."); _LT_Obj // Use LabTalk's FDlog to show a file dialog { FDlog.UseGroup("image"); FDlog.Open("A"); } char szFileName[MAX_PATH]; LT_get_str("%A", szFileName, MAX_PATH); printf("File Name: %s\n", szFileName);
Accessing LabTalk
153
15
User Interface
This chapter demonstrates ways in which Origin C functions allow user interaction.
15.1 Wait Cursors

The waitCursor class changes the mouse pointer to the hour glass, or busy indicator. It is a visual cue to indicate that Origin is running a piece of code that may require an amount of time sufficiently large that it will be prevented from responding to other requests. The mouse pointer changes to the busy indicator when an instance of a waitCursor object is created, and changes back to the arrow when the instance is destroyed. The following example is a function that pretends to do something time consuming. At the beginning, we declare and create a waitCursor instance. During the creation, the mouse pointer will be changed to the busy indicator. When the function exits, the waitCursor instance is automatically destroyed, causing the mouse pointer to be changed back to the arrow.
void myTimeConsumingFunction() { waitCursor wc; // declare and show the wait cursor for( int i = 0; i < 10000; i++ ) { if( 0 == (i % 100) ) printf("i == %d\n", i); } }
The next example is similar to the above example, but adds the ability to exit the function before it finishes its time consuming task. The exiting early ability is accomplished by calling the wait cursor's CheckEsc method. This method returns true if the user has pressed the Esc key, otherwise it returns false.
void myEscapableTimeConsumingFunction() { waitCursor wc; // declare and show the wait cursor for( int i = 0; i < 10000; i++ ) { if( 0 == (i % 100) ) printf("i == %d\n", i); if( wc.CheckEsc() ) break; // end loop early } }
155
15.2 Common Dialog Boxes
15.2 Common Dialog Boxes

15.2.1 Input Box
Input boxes are used to solicit textual information from program users. The global function InputBox is used to open an input box.
// enter string string strName = InputBox("Please enter your name", ""); printf("Name is %s.\n", strName); // enter numeric double dVal = InputBox(0, "Please enter a value"); printf("Value is %g.\n", dVal);
15.2.2 Message Box

Message boxes are used to convey information, or to prompt a user with a limited number of choices. The information presented is considered important enough to require the user's attention before they are allowed to continue. The first example shows a simple OK message box to inform the user that their file has downloaded successfully.
string strTitle = "File Download"; string strMsg = "Your file downloaded successfully."; MessageBox(GetWindow(), strMsg, strTitle, MB_OK);
The next example shows an OK-Cancel message box with an exclamation icon to warn the user that they will not be able to undo an action. This gives the user a choice to proceed or to cancel their action.
string strTitle = "Delete Data"; string strMsg = "You will not be able to undo this change."; int nMB = MB_OKCANCEL|MB_ICONEXCLAMATION; if( IDOK == MessageBox(GetWindow(), strMsg, strTitle, nMB) ) out_str("Data has been deleted");
The next example shows a Yes-No message box with a question mark icon. This is being used to ask the user if they want to continue with their action.
string strTitle = "Close Windows"; string strMsg = "Are you sure you want to close all windows?"; int nMB = MB_YESNO|MB_ICONQUESTION; if( IDYES == MessageBox(GetWindow(), strMsg, strTitle, nMB) ) out_str("All windows have been closed.");
15.2.3 Progress Box

A progress box is a small dialog box that indicates the software is busy processing data. This dialog box contains a progress bar for showing the fraction of the completed processing. The progress dialog box is usually used in iterative loops.
156 User Interface
15.2.4 File Dialogs

int iMax = 10, iMin = 0; progressBox prgbBox("This is a ProgressBox example:"); prgbBox.SetRange(iMin, iMax); for (int ii=iMin; ii<=iMax; ii++) { if(prgbBox.Set(ii)) printf("Hi, it is now at %d.\n", ii); else { out_str("User abort!"); // Click Cancel button to abort break; } LT_execute("sec -p 0.5"); }
15.2.4 File Dialogs

Origin C provides functions for all the common file and path dialogs. This includes dialogs that prompt the user to open a single file, open multiple files, save a file, and choose a folder. The following sections show you how to use these dialogs in your own applications.
File Open Dialog

StringArray saFiletypes(3); saFiletypes[0]="[Project (*.OPJ)] *.OPJ"; saFiletypes[1]="[Old version (*.ORG)] *.ORG"; saFiletypes[2]="[Worksheets (*.OGW)] *.OGW"; string strPath = GetOpenBox( saFiletypes, GetAppPath(false) ); out_str(strPath);
Multiple Files Open Dialog

StringArray saFilePaths; StringArray saFileTypes(3); saFileTypes[0]="[Project (*.OPJ)] *.OPJ"; saFileTypes[1]="[Old version (*.ORG)] *.ORG"; saFileTypes[2]="[Worksheets (*.OGW)] *.OGW"; // Press Ctrl or Shirt key to choose multiple files int iNumSelFiles = GetMultiOpenBox(saFilePaths, saFileTypes, GetAppPath(false));
File SaveAs Dialog

string strDefaultFilename = "Origin"; FDLogUseGroup nFDLogUseGroup = FDLOG_ASCII; // ASCII file group string strPath = GetSaveAsBox(nFDLogUseGroup,GetAppPath(false),strDefaultFilename); out_str( strPath );
User Interface
157
15.3 GetN Dialogs
Path Browser Dialog

string strPath = BrowseGetPath(GetAppPath() + "OriginC\\", "This is an example"); out_str(strPath);
15.3 GetN Dialogs

Origin C's GetNBox function is an easy way to show a full-featured dialog box. The GetNBox function uses a Tree that has been previously created using the GETN macros. The Tree contains nodes and branches containing more nodes. Each node represents an item in the dialog box. An item can be a check box, an edit box, a combo box, or another supported control. The following sections explain the steps involved in making a tree that can be passed to the GetNBox function.
15.3.1 The GETN Macros

The GetNBox function requires a Tree containing information about what dialog it should create and how it should be presented. Although it requires a tree, the caller does not have to know much about trees, thanks to the GETN macros. The entire tree is created using the GETN macros.
The GETN_BOX and GETN_TREE macros

The first macro you will use when creating your tree is either the GETN_BOX or the GETN_TREE macro. The GETN_BOX macro constructs a base GetNBox tree and gives the dialog box the simple dialog appearance. The GETN_TREE macro constructs a base GetNBox tree and gives the dialog box a tree appearance. Both macros declare a new tree instance with the name passed to the macro. After declaration it will set up the base of the tree for the style requested.
GETN_BOX(trMyDlg) GETN_TREE(trMyDlg)
Data Item Macros

After you have declared and set up your tree using the GETN_BOX or GETN_TREE macro you can start adding data item nodes. There are macros for adding string or numeric edit boxes, check boxes, drop down lists, button controls, sliders, and more.
#include <GetNbox.h> void GETN_ex1() { GETN_TREE(testTree) GETN_STR(name, "Name", "Jacky") // string edit box GETN_NUM(age, "Age", 31) // numeric edit box GETN_LIST(gender, "Gender", 0, "Male|Female") // drop-down list
158
User Interface
15.3.1 The GETN Macros

GETN_BUTTON(path, "File Path", GetAppPath()) // button control GETN_OPTION_EVENT(button_event) // the event function of button control if(GetNBox(testTree, NULL, NULL, NULL, NULL)) out_tree(testTree); } // define the event function of button control bool button_event(TreeNode& myTree, int nRow, int nType, Dialog& theDlg) { if(TRGP_STR_BUTTON == nType && nRow >= 0) { string strPath = BrowseGetPath(myTree.path.strVal); myTree.path.strVal = strPath; return true; } else return false; }
The Branch Macros

A GetNBox can contain many items. To help keep items organized, there are the GETN_BEGIN_BRANCH and GETN_END_BRANCH macros. The begin branch macro starts a new branch that can contain child nodes. All data item macros that follow a begin branch will be children of that branch. The branch is ended when the end-branch macro is called.
#include <GetNbox.h> void GETN_ex2() { GETN_TREE(testTree) GETN_BEGIN_BRANCH(Personal, "Personal Info") GETN_STR(name, "Name", "") // string edit box GETN_NUM(age, "Age", 31) // numeric edit box GETN_LIST(gender, "Gender", 0, "Male|Female") // drop-down list GETN_END_BRANCH(Personal) if(GetNBox(testTree, NULL, NULL, NULL, NULL)) out_tree(testTree); }
Options Control
There are GetN macros to set format on GetN controls. For example, GETN_OPTION_BRANCH can control whether the branch default is open or closed.
GETN_BEGIN_BRANCH(Personal, "Personal Info") GETN_OPTION_BRANCH(GETNBRANCH_OPEN) // open the branch //... GETN_END_BRANCH(Personal)
User Interface
159
15.3 GetN Dialogs
Apply Button
The default GetN Dialog has OK and Cancel buttons; the Apply button is optional. When the Apply button is displayed, and the user clicks this button, you may want to call the related event function to do something. The following is an example showing how to display the Apply button on a GetN dialog, and call the event function _apply_event when the Apply button is clicked.
#include <GetNbox.h> // The interface of apply button event function need to according to // PAPPLY_FUNC typedef. bool _apply_event(TreeNode& tr) { int nIndex = tr.LineColor.nVal; UINT cr = color_index_to_rgb(nIndex); printf("Red = %d, Green = %d, Blue = %d\n", GetRValue(cr), GetGValue(cr), GetBValue(cr)); return true; } void GETN_Apply_ex1() { GETN_TREE(tr) GETN_COLOR(LineColor, "Color", 3) // the option to set color list to contain custom panel GETN_COLOR_CHOICE_OPTIONS(COLORLIST_CUSTOM | COLORLIST_SINGLE) bool bShowApplyButton = true; if(GetNBox(tr, NULL, "Example", NULL, GetWindow(), bShowApplyButton, _apply_event)) { out_str("Click OK"); } }
15.3.2 Event Handling

Above, we have introduced the apply button event function, but GetN dialogs also support a mechanism to respond to other events, like dialog initialization, control value changes, and so on. The following is an example showing how to access these types of event.
#include <GetNbox.h> int _normal_event(TreeNode& tr, int nRow, int nEvent, DWORD& dwEnables, LPCSTR lpcszNodeName, WndContainer& getNContainer, string& strAux, string& strErrMsg) { if( 0 == lstrcmp(lpcszNodeName, "list") || GETNE_ON_INIT == nEvent ) { tr.name.Enable = (1 == tr.list.nVal); tr.id.Show = (2 == tr.list.nVal); } return 0; }
160
User Interface

void GETN_Event_Ex() { GETN_TREE(tr) GETN_LIST(list, "Options", 0, "None|Name|ID") GETN_STR(name, "Name", "") GETN_STR(id, "ID", "") if(GetNBox(tr, _normal_event, "Example", NULL, GetWindow())) { out_str("Click OK"); } }
15.4 Picking Points from a Graph

The Origin C GetGraphPoints class is used to pick points from the curve on the Graph window. This class has virtual methods to allow the user to derive from it to overload methods. The following example shows how to use the GetGraphPoints class to pick two points from a Graph.
GetGraphPoints mypts; // Set as true , the cursor moves along the DataPlot and picks points from // the curve. // Set as false, the cursor does not move along the DataPlot, and picks // points from the screen. mypts.SetFollowData(true, dp.GetIndex()); // To pick point from the specified Graph by GraphLayer object(gl) int nPts = 2; // the number of the points to pick mypts.GetPoints(nPts, gl); // Get the x/y data and indices from the picked points vector vx, vy; vector<int> vnPtsIndices, vnPlotIndices; if( mypts.GetData(vx, vy, vnPtsIndices, vnPlotIndices) == nPts ) { for(int ii = 0; ii < vx.GetSize(); ii++) { printf("point %d: index = %d, x = %g, y = %g, on plot %d\n", ii+1, vnPtsIndices[ii], vx[ii], vy[ii], vnPlotIndices[ii]+1); } }
User Interface
161
15.5 Adding Controls to a Graph
15.5 Adding Controls to a Graph

If you want to attach a dialog to a page, similar to a workbook's organizer or the top of a polar graph, then the SetSplitters method of the PageBase class can be used to accomplish this. To add a dialog bar to a page, lpcszString needs to include the dialog class name and the position (Left, Right, Top or Bottom) of the page window. Set lpcszString as NULL to remove the existing dialog bar. The following example shows how to add and remove user-created dialog on a Graph window. The class of the user-defined dialog:
#include <..\Originlab\DialogEx.h> // OC_REGISTERED key word must allow the PageBase::SetSplitters method // to find this class. class OC_REGISTERED MyGraphPolarBar : public Dialog { public: // IDD_POLAR_CONTROL is dialog resource ID // Odlg8 is the name of dialog resource DLL file, if not specified path, //default path is \OriginC\Originlab. MyGraphPolarBar() :Dialog(IDD_POLAR_CONTROL, "Odlg8") { } BOOL CreateWindow(int nID, HWND hWnd) { int nRet = Dialog::Create(hWnd, DLG_AS_CHILD); HWND hWndThis = GetSafeHwnd(); SetWindowLong(hWndThis, GWL_ID, nID); return nRet; } };
Add or remove dialog on a Graph window.

void Page_SplittersControl(BOOL bShow = TRUE, int nPos = 2) { Page pg = Project.Pages("Graph1"); if( bShow ) { int nPercent = 30; string strDlgClass = "MyGraphPolarBar"; // the above dialog class string strConfig; switch(nPos) { case 0: // Bottom strConfig.Format("r{%s}r[%s]", (string)nPercent+"%", strDlgClass); break; case 1: // Right strConfig.Format("c{%s}c[%s]", (string)nPercent+"%", strDlgClass); break; case 2: // Top strConfig.Format("r[%s]{%d}r", strDlgClass, nPercent);
162
User Interface

break; case 3: // Left strConfig.Format("c[%s]{%d}c", strDlgClass, nPercent); break; } pg.SetSplitters(strConfig); } else pg.SetSplitters(NULL); } // remove dialog bar from page
User Interface
163
16
Dialog Builder
Dialog Builder refers to the Origin C support to use Microsoft Visual C++ generated resource DLL for building floating tools, dialog boxes, and wizards in Origin. All resource elements, including Windows common controls and Origin's worksheet and graph controls can be accessed and controlled from Origin C. This capability used to require a Dialog Builder license, but since Origin 8.5, this restriction has been removed and all Origin installations include this support. This guide contains a tutorial that shows how to use Microsoft Visual C++ to create a resourceonly DLL containing a dialog and then how to use Origin C to display the dialog. Additional sections describe in more detail how to create a resource-only DLL and access it's resources from Origin C. Developer Kit Samples Developer Kit sample files are available as an Origin Package file (.OPX). This OPX file is available to our maintenance customers. Please contact OriginLab or your Origin distributor to obtain the file. The OPX file will add all sample files, including resource DLLs, in the \Samples\DeveloperKit\ subfolder under the Origin installation folder.
165
16.1 Simple Hello World Dialog

16.1.1 Create Resource DLL in VC
Create by Origin Dialog AppWizard
1. 2. 3. 4. 5. 6. 7. Start Visual C++ 6.0, select File->New to open the New dialog. On the Projects tab, choose Origin Dialog AppWizard, set Project name to "ODialog", choose a Location and click OK. Choose a simple dialog, and click Next. Keep Origin C selected and click Finish, then click OK. The resource file with one simple dialog and the related source file and header file will be generated. Click menu Build->Set Active Configuration to choose Debug or Release. Choose menu Build->Builder ODialog.dll to create DLL. Go to the file location specified above. Copy the DLL file to outside the Debug or Release folder, to keep the path of the DLL file the same as that of the ODialog.cpp file. Open the ODialog.cpp file in Origin C Code Builder, compile, and run the DoMyDialog function to open the dialog.
Create by Win32 Dynamic-Link Library

This section describes how to create a Resource-only DLL in Visual C++ 6.0.
1. Start Visual C++ 6.0, select File->New to open the New dialog. On the Projects tab, choose Win32 Dynamic-Link Library as the project template, set the Project name as ODialog, choose a Location and click OK. In the dialog that appears, select a simple DLL project and click Finish. Select Project->Settings to open the Project Settings dialog. On the Resources tab, set the Resource file name, like ODialog.res, and select the Language according to your software settings as English (United States), and click OK. Select Insert->Resource to insert resources into the project. For a Dialog and controls on it, set dialog ID to IDD_OC_DIALOG. Choose File->Save As to save the Resource Script file as ODialog.rc. Choose Project->Add To Project->Files, then choose the ODialog.rc file to add it to the project. If the Language is not English, please do this step. In the Workspace view Resource tab, open the list tree, right click on IDD_OC_DIALOG, choose Properties, and then in the dialog choose Neutral for Language. Build the whole project with Debug or Release configuration. The resulting DLL file is generated under the Debug or Release subfolder.
2. 3. 4. 5. 6.
Create Resource-only DLL in Visual Studio 2008

This article describes in detail the general process of creating a Resource-only DLL in Visual Studio 2008. The following steps show how to build a Resource-only DLL with VS2008 that is accessible in Origin using Origin C.
1. 2. 3. Start Microsoft Visual Studio 2008. Select File->New->Project to create a new project. In the New Project dialog, choose Visual C++ as the programming language and Win32 Project as the template, type in the project name as "Welcome", select its location, like in the following picture, and click OK.
166
Dialog Builder
16.1.1 Create Resource DLL in VC
4.
In the Win32 Application Wizard dialog, set Application type as DLL and click Finish.
5.
Switch to the Resource View of the project, right click on the project name to add resources, choose a resource type and click New.
Dialog Builder
167
6.
Remember to set the Language property of the resource according to the environment in which your software is planning to install; say English(United States) if your software is in English.
7.
Add more controls as you want, configure the project as Debug or Release, and save the project. Then select Build>Build Solution or Rebuild Solution to build the project. You can now find a folder named "Debug" or "Release" generated under the solution folder, which contains the DLL. Files generated in this solution are as follows:
168
Dialog Builder
16.1.2 Use Resource DLL in Origin C
16.1.2 Use Resource DLL in Origin C

This section describes how to use the Resource-only DLL created in the section above.
1. 2. 3. Copy the DLL file to outside the Debug or Release folder, to keep the path of the DLL file the same as that of the resource.h file. Start Origin and open Code Builder. Create a new Origin C file named testODialog.c under the path of the DLL file. Add it to the current Workspace, and write testing code like the following. Run the OpenDlg function to open the dialog. #include <Dialog.h> #include <..\Originlab\Resource.h> //ODialog resource header class MyDialog : public Dialog { public: // Construct dialog with dialog ID and DLL name. // "ODialog" is the DLL file name. // Not specify path, means the DLL file under the same path of this // Origin C file. // If the DLL located at other place, should provide the full path // of the DLL file. MyDialog() : Dialog(IDD_OC_DIALOG, "ODialog") { } }; void OpenDlg() { MyDialog odlg; odlg.DoModal(); }
16.2 Wizard Dialog

This section describes how to open a wizard dialog in Origin C. The examples in this section will use an existing wizard dialog resource DLL that gets installed with Origin C's Developer Kit. The DLL can be found in the "Samples\DeveloperKit\Dialog Builder\Wizard" sub-folder. To open a wizard dialog we need to first define some user-defined classes. We will need a class derived from the Dialog class, another derived from the WizardSheet class, and a class for each page derived from the PropertyPage class.
Dialog Builder 169
16.2 Wizard Dialog
The WizardSheet::AddPathControl method is used to provide a wizard map which helps the user navigate through steps or pages of a wizard. The map also allows the user to skip to any page in the wizard by clicking on the map. The first class we define is derived from the PropertyPage class. This first class will contain all the information shared by all the pages in the wizard.
class WizPage : public PropertyPage { protected: WizardSheet* m_Sheet; };
Now that we have defined our class based on PropertyPage we can define a class for handling each page in the wizard. These next classes will be derived from our page class defined above.
class WizPage1 : public WizPage { }; class WizPage2 : public WizPage { }; class WizPage3 : public WizPage { };
The next class to be defined is the place holder class. This class is derived from the WizardSheet class which in turn is derived from the PropertySheet class. This class will hold the instances of all our pages as data members.
class WizSheet : public WizardSheet { public: // Data members of PropertySheet are WizPage objects WizPage1 m_WizPage1; WizPage2 m_WizPage2; WizPage3 m_WizPage3; };
With the definitions of all the pages and sheet classes completed we can now define our dialog class.
class WizPageDialog : public Dialog { public: // Constructor for main Dialog WizPageDialog(int ID) : Dialog(ID, "Wizard.DLL") { } // Data member of main Dialog is PropertySheet (place holder) WizSheet m_Sheet; };
170
Dialog Builder
16.3.1 Prepare Dialog Resource
16.3 Graph Preview Dialog

This section shows how to create custom dialog with a graph preview.

We first need a dialog resource containing a static control, in which the preview graph will nest. Here we will use a built-in resource, IDD_SAMPLE_SPLITTER_DLG, in OriginC\Originlab\ODlg8.dll.
16.3.2 Prepare Source File

In Code Builder, click New button , type file name, and set Location as the same path of the above dialog resource dll oDlg8.dll - Origin install path OriginC\Originlab subfolder.
16.3.3 Including Needed Headers

//These headers contain declarations of dialog and controls #include <..\Originlab\DialogEx.h> #include <..\Originlab\GraphPageControl.h>
16.3.4 Adding User Defined Preview Class

//forbid some action on preview graph #define PREVIEW_NOCLICK_BITS (NOCLICK_DATA_PLOT|NOCLICK_LAYER|NOCLICK_LAYERICON) #define PREVIEW_TEMPLATE "Origin" //preview graph template
class MyPreviewCtrl { public: MyPreviewCtrl(){} ~MyPreviewCtrl() { //destroy temporary books when dialog closed. if ( m_wksPreview.IsValid() ) m_wksPreview.Destroy(); } void { Init(int nCtrlID, WndContainer& wndParent) //create preview graph control Control ctrl = wndParent.GetDlgItem(nCtrlID); GraphControl gCtrl; gCtrl.CreateControl(ctrl.GetSafeHwnd()); gCtrl.Visible = true;
Dialog Builder
171
16.3 Graph Preview Dialog

GraphPageControl gpCtrl; gpCtrl.Create(gCtrl, PREVIEW_NOCLICK_BITS, PREVIEW_TEMPLATE); GraphPage gpPreview; gpPreview = gpCtrl.GetPage(); gpPreview.Rename("MyPreview"); m_glPreview = gpPreview.Layers(0); //first layer if ( !m_wksPreview ) { //temporary worksheet to hold preview data. m_wksPreview.Create("Origin", CREATE_TEMP); m_wksPreview.SetSize(-1, 2); //two columns //long name will be displayed as axis title Column colX(m_wksPreview, 0); colX.SetLongName("Preview X"); Column colY(m_wksPreview, 1); colY.SetLongName("Preview Y"); //prepare datarange DataRange drPrev; drPrev.Add(m_wksPreview, 0, "X"); drPrev.Add(m_wksPreview, 1, "Y"); //plot preview curve, although it has no points now. int nPlot = m_glPreview.AddPlot(drPrev, IDM_PLOT_LINE); DataPlot dp = m_glPreview.DataPlots(nPlot); if ( dp ) //set preview curve color dp.SetColor(SYSCOLOR_RED); } } //update preview curve with external data. void Update(const vector& vX, const vector& vY) { if ( m_wksPreview.IsValid() ) { Dataset dsX(m_wksPreview, 0); Dataset dsY(m_wksPreview, 1); if ( !dsX.IsValid() || !dsY.IsValid() ) return; //no columns for preview //update source data will also update preview graph. dsX = vX; dsY = vY; //rescale graph for better view. m_glPreview.Rescale(); } } private: //preview graph on dialog GraphLayer m_glPreview; //temporary worksheet to put preview data. Worksheet m_wksPreview; };
172
Dialog Builder
16.3.5 Adding Dialog Class
16.3.5 Adding Dialog Class

class MyGraphPreviewDlg : public MultiPaneDlg { public: //dialog resource ID and the DLL containing it. MyGraphPreviewDlg() : MultiPaneDlg(IDD_SAMPLE_SPLITTER_DLG, GetAppPath(TRUE) + "OriginC\\Originlab\\ODlg8") { } ~MyGraphPreviewDlg() { } int { DoModalEx(HWND hParent = NULL) InitMsgMap(); //show dialog until user closes it. return DoModal(hParent, DLG_NO_DEFAULT_REPOSITION); } //message handler of dialog events BOOL OnInitDialog(); BOOL OnDraw(Control ctrl); protected: DECLARE_MESSAGE_MAP private: //member stands for the preview control MyPreviewCtrl m_Preview; };
16.3.6 Open the Dialog

void open_preview_dlg() { MyGraphPreviewDlg dlg; dlg.DoModalEx(GetWindow()); return; }
Execute the function above, and click the Draw button. You will notice the preview be updated.
16.4 Splitter Dialog

This example shows how to create a splitter dialog, which provides a better display of tree view or grid view.
Dialog Builder 173

To create this dialog, you first must prepare a dialog resource with a Static control and two Button controls. Here we just use the existing resource IDD_SAMPLE_SPLITTER_DLG in the built-in OriginC\Originlab\ODlg8.dll file to simplify this example.
16.4.2 Prepare Source File

In Code Builder, click New button , type file name, and set Location as the same path of the above dialog resource dll oDlg8.dll - Origin install path OriginC\Originlab subfolder.
16.4.3 Including Header Files

The following header files will be used in the example. Copy the following to the above created source file.
#include <..\Originlab\DialogEx.h> #include <..\Originlab\SplitterControl.h> #include <..\Originlab\DynaSplitter.h>
16.4.4 Adding User Defined Splitter Class

We can derive a class from TreeDynaSplitter. Most dialog initialization and other event functions' code are done in a base class and make our splitter class a light class.
class MySplitter : public TreeDynaSplitter { public: MySplitter(){} ~MySplitter(){} //init the splitter control int Init(int nCtrlID, WndContainer& wndParent, LPCSTR lpcszDlgName = NULL)
174
Dialog Builder
16.4.4 Adding User Defined Splitter Class

{ TreeDynaSplitter::Init(nCtrlID, wndParent, 0, lpcszDlgName); return 0; } //output current settings void Output() { out_tree(m_trSettings); } protected: // Declare message map table and message handler DECLARE_MESSAGE_MAP BOOL OnInitSplitter(); BOOL InitSettings(); void OnRowChange(Control ctrl); private: BOOL constructSettings(); BOOL initSystemInfo(TreeNode& trSys);//show system information BOOL initUserInfo(TreeNode& trUser);//to collect user settings. private: GridTreeControl m_List; //grid control on left panel Tree m_trSettings;//splitter tree on right panel bool m_bIsInit;//indicate whether it is from init event }; //map the control messages and events. BEGIN_MESSAGE_MAP_DERIV(MySplitter, TreeDynaSplitter) ON_INIT(OnInitSplitter) //init splitter settings //save splitter size & position when destroy //this is done in base class. ON_DESTROY(OnDestroy) ON_SIZE(OnCtrlResize) //when control is ready, need to resize the splitter and its position ON_USER_MSG(WM_USER_RESIZE_CONTROLS, OnInitPaneSizs) //when user select different row on left panel ON_GRID_ROW_COL_CHANGE(GetMainPaneID(), OnRowChange) END_MESSAGE_MAP_DERIV BOOL MySplitter::OnInitSplitter() { TreeDynaSplitter::OnInitSplitter(&m_List); constructSettings(); //construct tree settings InitSettings(); //tree settings to splitter GUI SetReady(); return TRUE; } //when user selects a different row, update right panel void MySplitter::OnRowChange(Control ctrl) { if ( !m_bReady ) return; //show sub nodes under current branch TreeNode trCurrent = ShowListContent(-1, true, m_bIsInit);
Dialog Builder
175

if ( trCurrent ) { //load settings from registry string strTag = trCurrent.tagName; LoadBranchSetting(GetDlgName(), strTag); } m_bIsInit = false; return; } //init splitter settings BOOL MySplitter::InitSettings() { m_bIsInit = true; ///set not ready, avoid flash and painting problem on GUI m_bReady = false; //set the splitter tree for display ShowList(m_trSettings, ATRN_STOP_LEVEL); m_bReady = true; //reset ready state. SelectRow(0); //select first row. return TRUE; } BOOL MySplitter::constructSettings() { TreeNode trSys = m_trSettings.AddNode("System"); trSys.SetAttribute(STR_LABEL_ATTRIB, "System Information"); initSystemInfo(trSys); TreeNode trUser = m_trSettings.AddNode("User"); trUser.SetAttribute(STR_LABEL_ATTRIB, "User Settings"); initUserInfo(trUser); return TRUE; } //display your Origin's basic information. //you can also display OS related information here. BOOL MySplitter::initSystemInfo(TreeNode& trSys) { if ( !trSys ) return FALSE; char szUser[LIC_USERINFO_NAME_COMPANY_MAXLEN]; char szCompany[LIC_USERINFO_NAME_COMPANY_MAXLEN]; char szSerial[LIC_OTHER_INFO_MAXLEN]; char szRegCode[LIC_OTHER_INFO_MAXLEN]; DWORD dwProd = GetLicenseInfo(szUser, szCompany, szSerial, szRegCode); string strProduct; switch( dwProd & 0x000000FF ) { case ORGPRODUCTTYPE_EVALUATION: strProduct = "Evaluation"; break; case ORGPRODUCTTYPE_STUDENT: strProduct = "Student"; break; case ORGPRODUCTTYPE_REGULAR: strProduct = "Regular"; break;
176
Dialog Builder
16.4.5 Adding User Defined Splitter Dialog Class

case ORGPRODUCTTYPE_PRO: strProduct = "Professional"; break; default: strProduct = "Unknown"; break; } GETN_USE(trSys) GETN_STR(UserName, "User Name", szUser) GETN_READ_ONLY_EX(2) GETN_STR(Company, "Company Name", szCompany) GETN_READ_ONLY_EX(2) GETN_STR(SeriNum, "Serial Number", szSerial) GETN_READ_ONLY_EX(2) GETN_STR(RegCode, "Register Code", szRegCode) GETN_READ_ONLY_EX(2) GETN_STR(Product, "Product Version", strProduct) GETN_READ_ONLY_EX(2) return TRUE; } //controls to collect user information and settings. BOOL MySplitter::initUserInfo(TreeNode& trUser) { if ( !trUser ) return FALSE; GETN_USE(trUser) GETN_STRLIST(Language, "Language", "English", "|English|German") GETN_STR(UserID, "User ID", "") GETN_PASSWORD(Password, "Password", "") GETN_STR(Email, "Email", "user@originlab.com") return TRUE; }
16.4.5 Adding User Defined Splitter Dialog Class

The splitter dialog contains a splitter control object, so the dialog can initialize the splitter control and post messages to it on the proper events.
//dialog name, which will also be used to save settings in registry #define STR_DLG_NAME "My Splitter Dialog" class MySplitterDlg : public MultiPaneDlg { public: //resource ID and which DLL contains this dialog resource MySplitterDlg() : MultiPaneDlg(IDD_SAMPLE_SPLITTER_DLG, "ODlg8") { } ~MySplitterDlg() { } //open dialog until user close it. int DoModalEx(HWND hParent = NULL) {
Dialog Builder
177

//set up message map InitMsgMap(); return DoModal(hParent, DLG_NO_DEFAULT_REPOSITION); } //init controls and other settings before dialog open BOOL OnInitDialog(); //when dialog initialization finish BOOL OnReady(); //when user click 'Output' button BOOL OnOutput(Control ctrl); protected: DECLARE_MESSAGE_MAP private: MySplitter m_Splitter; }; //map dialog message BEGIN_MESSAGE_MAP(MySplitterDlg) ON_INIT(OnInitDialog) ON_READY(OnReady) ON_BN_CLICKED(IDC_LOAD, OnOutput) END_MESSAGE_MAP BOOL MySplitterDlg::OnInitDialog() { //rename buttons title to meaningful text GetDlgItem(IDC_LOAD).Text = "Output"; GetDlgItem(IDCANCEL).Text = "Close"; m_Splitter.Init(IDC_FB_BOX, *this, STR_DLG_NAME); return TRUE; } BOOL MySplitterDlg::OnReady() { //update dialog UpdateDlgShow(); SetInitReady(); //set splittercontrol ready as to init the position and size m_Splitter.OnReady(); return TRUE; } BOOL MySplitterDlg::OnOutput(Control ctrl) { //dump current user settings. m_Splitter.Output(); return TRUE; }
16.4.6 Open Dialog

After the steps above, save all the code and build it, then execute the following function to open the splitter dialog.
void { test_MySplitterDlg()
178
Dialog Builder
16.4.6 Open Dialog

MySplitterDlg dlg; dlg.DoModalEx(GetWindow()); }
Dialog Builder
179
17
X-Functions
X-Function technology provides a framework for building Origin tools. In fact, most of Origin's revamped and greatly-expanded lineup of analysis and data processing tools have been implemented using this new technology.
17.1 Creating an X-Function

Creating an X-Function is a two-step process: first, the X-Function and its parameters are defined in X-Function Builder; second, the X-Function's Origin C code is written and compiled in Code Builder.
17.1.1 Creating a Simple X-Function

X-Functions are created with X-Function Builder. You can open X-Function Builder by choosing X-Function Builder on the Tools menu or by pressing F10. The X-Function Builder dialog is shown below.
Creating X-Function
The steps below will walk you through the creation of an X-Function that will perform the task of copying data from one column to another column.
181

1. 2. Start creating an X-Function by pressing F10 to open X-Function Builder. Name the X-Function "CopyCol" and add a second variable by right-clicking on the Variables list and choosing "Add variable". Change the variable names, labels, and other values to match the settings in the dialog below.
3.
After you make the necessary changes to the variables, save the X-Function by clicking the Save OXF file button . When the Save As dialog appears click the Save button.
4.
Click the X-Function Tree View button to switch to tree view. Make sure the Labtalk check box is checked and the Auto GetN Dialog is set to Simple GetNBox, as below. Select the Labtalk check box to make it so the X-Function can be used in the Command Window. The Auto GetN Dialog provides the choice to use an X-Function without dialog or with dialog, as there are multiple different types.
5.
Now we need to write the Origin C code that will do the work for our X-Function. Click on the Code Builder button . This will open the X-Function in Code Builder where we can write our Origin C code. In the main function, add the following Origin C code: ocol = icol;
182
X-Functions
17.1.2 X-Function Builder

6. Click the Compile button and then click the Return to Dialog button to go back to X-Function Builder. Click the Save OXF file button.
Using X-Functions
Now that we have successfully created our X-Function, we can test it.
1. 2. 3. Create a new a worksheet with two columns. Fill column A with row numbers and select the whole column by clicking on its heading. In the Script or Command Window enter "CopyCol -d", without the quotes, and press Enter. When the dialog appears, keep the default values and click the OK button.
After the X-Function executes, the worksheet will contain a third column which will contain a copy of the data from column A.

Open X-Function Builder by choosing X-Function Builder on the Tools menu or by pressing F10.
X-Function Name
Input the X-Function name in the X-Function edit box. Do not give your X-Function the same name as an existing LabTalk macro, OGS file, LabTalk command, or LabTalk callable Origin C function. If two or more of these have the same name, the priority order of calling is: LabTalk macros > LabTalk OGS > X-Function > LabTalk callable Origin C functions > LabTalk commands.
X-Function Variables
Specify the name of the variable. When the X-Function is executed by script, you have to assign values to variables using their names. Therefore, we recommend that you use shorter names and begin them with different characters. Specify a label for the variable. Special characters and white space are allowed. Displays on the X-Function dialog as control label. If not specified, variable name will be used.
Name
Label
X-Functions
183

Input/Output
Specify whether the variable is used for input, output or both. Specify the variable data type. More details can be referred to below in the Variable Data Type and Default Value section. Specify the default value for the variable. More details can be referred to below in the Variable Data Type and Default Value section. Specify the control for the variable in the dialog box (combo box, slider, etc.). More details can be referred to below in the Control Types section. Specify an option string for the variable. You can apply advanced settings with option strings, such as grouping several variables together, enabling recalculation, etc. More details can be referred to below in the Option String section. Specify the Theme ID for the variable. If not assigned, the Theme ID of the variable will refer to the index of the variable. The Theme ID is used in the theme file for the X-Function dialog. More details can be referred to below in the Theme ID section.
Data Type
Data
Control
Option String
Theme ID
Variable Data Type and Default Value

X-Functions provide dozens of data types, as below.
1. Basic Data Type o Types are double, string, int. o The default value can be 0 for numeric or kept empty for string type. Origin Composite Data Type o Types are vector, vector<string>, vector<complex>, and matrix. o For example, a vector can attach to a worksheet column as input or output. o The default value can be <active>, <new>, or <unassigned>. o For more details, please refer to the Origin C help Composite Data Types book. Origin Object Type o The types are Column, Range, GraphLayer and other Origin Object types. o The default value can be <active>, <new>, <input>, or <unassigned>. o Origin C provides the function BOOL okxf_resolve_string_get_origin_object(LPCSTR lpcsz, OriginObject* pObj) to get an Origin Object from a GetN tree string value. o For more details, please refer to the Origin C help Internal Origin Objects book. TreeNode Type
2.
3.
4.
184
X-Functions

Types are TreeNode, ReportData, and ReportTree. TreeNode is input, ReportData and ReportTree are output. Origin Graphical Object Control o Types are ButtonInfo, LineInfo, TextInfo and so on. o To see the usage, open a built-in X-Function from OriginEXE\X-Functions\Data Manipulation\curve translate.OXF in X-Function Builder as an example. Report Type o Types are ReportData, and ReportTree. o See X-Function ReportTree Example in the X-Function Examples chapter.
5.
6.
Control Types
After specifying the different control strings in the variables grid Control column in the XFunction Builder, we can easily create different types of user interface controls in the XFunction dialog.
Usage Data Type Control String
Numeric Edit Box Text Edit Box Check Box
double
string
int
0|1
Combo Box
int
string1|string2|string3 CaseA:string1|CaseB:string2|CaseC:string3
Editable Combo Box
string
Keep empty in the Control column in the Variables grid, but add the codes below to the xfname_before_execute function to set the var variable control as an editable combo box. if( nGetNDialog > 0 ) trGetN.var.SetAttribute(STR_COMBO_ATTRIB, "|aa|bb|cc");
Radio Box Slider Color List
int int/double int
Radio:string1|string2|string3 slider:start|end|nstep ColorList
X-Functions
185
Graph Browser
string
...Graph for one graph ...Graphs for multiple graphs Origin supports interface settings for the Graph Browser in an OriginC function, using the control string GraphBrowserFilter. See X-Function Graph Browser Dialog Example for details.
Text Edit Box with File Browser Button Text Edit Box with Path Browser Button Text Edit Box with Save As Browser Button
string
...File for single file ...Files for multiple files
string
...Path
string
...Save
Option String
We can set the special string in the Option String column to specify the action of a variable. For example, setting the recalculate default mode, setting the number of decimal digits for a numeric control, or setting the default name of an output object. For more details, see Reference: X-Function Option Strings.
Theme ID
The Theme ID is used in the X-Function dialog theme file, and the default value is 0. If you keep the Theme ID of all the variables at 0(default), the Theme ID in the theme file will be converted according to the index of the variable, beginning from 1. When you want to insert a variable into an existing X-Function (to append a variable as the last, there's no need do this), in order to remain compatible with the existing theme file, you need to:
1. 2. 3. Before inserting the variable, change the Theme ID from 0 to the index of the variable. Insert the variable. Set the Theme ID for the inserted variable as the maximum to avoid repeats.
186
X-Functions
17.1.3 Programming in Code Builder
Tree View
Click the Tree View button to switch to tree view. The settings in Tree View are mainly used to create X-Function dialogs, add X-Functions to the Origin menu, and add documentation. See the next chapter, Customizing an X-Function, for details.

Click on the Code Builder button write our Origin C code. to open the X-Function in Code Builder, where we can
Editor Window
There are two buttons near the top of the editor window: a Compile button and
. The Compile button is used to compile your Xa Return to Dialog button Function's Origin C code. The Return to Dialog button will close the editor window and return you to the X-Function Builder dialog. In the editor you will notice some of the Origin C code has a gray background. These parts of the code are read-only and cannot be changed. The X-Function framework generated these parts of the code and they are in a required syntax.
X-Functions 187
Include Header Files

You can include additional header files in your X-Function's Origin C code. While not required, it is recommended that you include your additional header files near the top of the file, after the following line:
//put additional include files here
This recommendation is to help keep the file organized and to be consistent with other XFunctions.
Search Paths
When you include files using the < and > brackets, then those files are included from the Origin C System folder located in the Origin installation folder. You can still provide a relative path to move above the System folder. These brackets behave the same when compiling .c and .cpp files in Origin C.
// Include fft_utils.h located in the "OriginC\System" folder. #include <fft_utils.h> // Include abffiles.h located in the "OriginC\OriginLab" folder #include <..\OriginLab\abffiles.h> // relative path
When you include files using double quotes, then those files are included from the "OriginC\XFunctions" folder in your "User Files" folder. This behavior is different than when you compile a .c or .cpp file in Origin C. This different behavior is necessary because X-Functions are installed in a location maintained by Origin.
// Include myOtherHeader.h located in the "OriginC\X-Functions" // folder of the "User Files" folder. #include "myOtherHeader.h"
If you specify an absolute path between double quotes, then that file will be included regardless of where the file is located.
Auto Compile Dependent Files

In X-Function Builder's Tree View there is an option named Auto Compile Dependent Files. When this option is turned on it will cause the compiler to check for a .c or .cpp file sharing a name with an included .h file. If a .c or .cpp file is found then it will be loaded and compiled too.
// Include graph_utils.h located in the "OriginC\Originlab" folder // If Auto Compile Dependent Files is turned on // then graph_utils.c, located in the same folder, will be loaded and compiled #include <..\Originlab\graph_utils.h>
Define Internal Functions

In order to provide more clarity and readability, to make your code easier for future understanding and maintenance, it is recommended that you break a long function into functionally independent and well-structured short functions, which is also proposed in some other programming languages. In an X-Function, you can add these short functions in as internal functions with the keyword static after the following line.
//put your own support static functions here
188
X-Functions
For example, in many X-Functions with lots of interaction from the GUI, many codes will be needed in xfname_event1( ), and then you can add a static function, similiar to Origin's interp1 X-Function.
static void _update_method_show(TreeNode& trGetN)
As you can see, it is also recommended that you use an underscore to separate the components in a function name.
Main Function
The main function is where you put all the code that performs the primary tasks of your XFunction. Your X-Function's main function will have the same name you gave your X-Function in XFunction Builder. For example, if you named your X-Function myXFunc then the main function will also be named myXFunc. The arguments passed to the main function are the variables listed in the X-Function Builder dialog. All the variables set as Input are passed in as constant references while the variables set as Output or Input/Output are passed in as writable references.
Event Handling Functions

Your X-Function's source code contains functions used for handling various events. The name of each event handler function is prefixed with the X-Function's name followed by an underscore character followed by the event name. For example; if your X-Function's name is myXFunc then the before_execute event handler function will be named myXFunc_before_execute. The following is a list of events: before_execute event1 event1_ex make_tree By default all the event handler functions are empty. You only need to add code to an event handler function when you want to change the default behavior or do some additional processing during an event. The following sections provide more details about each of the event handler functions including their purpose, parameters passed in, and return type.
before_execute
This function will be called before execution of the main function and will be called two or three times. Prototype
void xfname_before_execute(TreeNode& trGetN, int nGetNDialog, int& nRet, int dwCntrl)
X-Functions
189
Parameters trGetN A TreeNode containing the variables passed to the X-Function. nGetNDialog An integer value indicating when the function is being called. A value greater than zero indicates the function is being called before showing its dialog. This happens when choosing Open Dialog from a menu, programmatically calling the X-Function with the -d option, or choosing Change Parameters for a manual recalculate.
Value 1 2 3 Simple GetNBox GetNGraphBox with Preview GetNImageBox Before Opening Dialog for...
A value of -1 indicates the dialog was closed by the user clicking the OK button. A value of zero indicates the main function is about to be called. nRet This option can control the execution states of the X-Function.
XFEVT_PROCEED XFEVT_ABORT XFEVT_PROCEED_NO_DLG = 0 // Follow with normal execution = 1 // Abort execution = 2 // Execute silently without opening dialog.
dwCntrl This option can be used to determine how this X-Function is accessed. Possible values are enumerated as:
LTXF_FROM_GUI_MENU LTXF_FROM_GUI_PROMPT LTXF_FROM_AUTO_UPDATE LTXF_FROM_FUNCTION LTXF_THEME_USED LTXF_CHANGE_PARAM // // // // // // Accessed Accessed Accessed Accessed Theme is Accessed from menu from command window for Auto-update from Origin C function used for Change Parameters
The following example shows how to check if the X-Function is accessed from the command window and a theme is also used (type xfname -t themename in the command window).
if(!(dwCntrl & LTXF_FROM_GUI_PROMPT) && (dwCntrl & LTXF_THEME_USED)) { // handle this case }
make_tree
This function is called once for each TreeNode variable passed to the X-Function. The calls occur before the before_execute function is called.
190 X-Functions
Prototype
int xfname_make_tree(TreeNode& tr, LPCSTR lpcszVarName)
Return Return zero to update the dialog or -1 to not update the dialog. The default behavior returns -1. Parameters tr The TreeNode to be created, which should have been defined as an input TreeNode type variable of the X-Function. lpcszVarName The name of the TreeNode variable.
event1 and event1_ex

These are the primary event handling functions. They will be called by any event, such as dialog initialization, changes to any settings in the dialog, button clicking, and more. These functions are only used in X-Functions with a simple GetN dialog. X-Functions with a graph preview or an image preview use a different set of event handler functions and are discussed in a later section. Prototype
int xfname_event1(TreeNode& trGetN, int nRow, int nEventID, DWORD& dwEnables, LPCSTR lpcszNodeName, WndContainer& DynaCntrlContainer, string& strAux, string& strErrMsg)
Return If returning true, the dialog will be updated. Parameters trGetN This is the tree node of the variables defined in the X-Function. nRow The index of the row of the value-changed control node in TreeNode trGetN. The value will be 1 when the event is not 'control value changed'. nEventID Event type ID. For example, GETNE_ON_INIT, GETNE_ON_THEME. dwEnables This parameter is used to enable or disable the OK, Apply or other custom button. It is true by default, and will usually be set to false when the user's settings are invalid, so as to disable the OK or Apply button. lpcszNodeName If the event is generated by a control change in the dialog, it will be the variable name of this control. Otherwise, it will be an empty string. DynaCntrlContainer X-Function dialog window container.
X-Functions 191
strAux This parameter is the auxiliary string, which is for advanced usage. Please refer to the header file <Origin Installation Directory>\OriginC\System\GetNBox.h for more details like the following definition.
#define DLG_NEED_CHANGE_GRID "GETN_CHANGE_GRID" #define GETN_CHANGE_GRID set_aux_value(strAux, DLG_NEED_CHANGE_GRID);
strErrMsg This is the string message that will be shown in the bottom of the dialog. It is usually used to notify the user of any errors that occurred during the input of variable values.
GetNGraphPreview Event Handler Functions

The event1 and event1_ex event handler functions are not used by X-Functions that have a graph preview dialog. Instead you use the GetNGraphPreview functions.
GetNGraphPreview_OnInitGrid This event function is used to initialize the controls on the dialog. GetNGraphPreview_OnInitGraph This event function is used to initialize the preview graph. GetNGraphPreview_OnUpdateGraph This event function is used to update the preview graph on other events, for example, GUI changed. GetNGraphPreview_OnChange Any change will trigger this event function, and this function will decide whether to update the preview graph or update the dialog on this change. GetNGraphPreview_OnDialogSetup GetNGraphPreview_OnDestroy GetNGraphPreview_OnCustomButton
See the Creating Graph Preview GetN Dialog section for an example of how to create an XFunction with a graph preview dialog.
GetNImageBox Event Handler Functions

The event1 and event1_ex event handler functions are not used by X-Functions that have an image preview dialog. Instead you use the GetNImageBox functions.
GetNImageBox_OnInit The event function called when the image GetN dialog is open. The function can decide whether to update the dialog, enable/disable the OK button or show an error message on the bottom of the dialog after calling. GetNImageBox_OnChange The event function called whenever any control on the dialog is modified by the user. This function can decide whether to update the dialog, update the image preview, enable/disable the OK button, or show an error message on the bottom of the dialog.
See the Creating Image GetN Dialog section for an example of how to create an X-Function with an image preview dialog.
192
X-Functions
Error Handling
Display an Error Message in the Dialog
When a user passes a bad value to your X-Function and also passes the -d option, or enters a bad value in the X-Function's dialog, you can display an error message in the dialog by setting the strErrMsg argument passed into the event handler function. Which event handler function is called depends on the GetN Dialog your X-Function uses.
GetN Dialog Used Simple GetNBox GetNGraphBox with Preview GetNImageBox Event Handler Function xfname_event1 GetNGraphPreview_OnChange GetNImageBox_OnChange
Let us assume we have an X-Function that accepts an integer variable named x1. The following code snippet, inserted into the appropriate event handler function, checks the x1 variable's value to see if it is less than zero or greater than 100. If it is then it sets the strErrMsg to an appropriate message to display in the dialog, and also disables the OK button. If the value is within the accepted range then it simply makes sure the OK button is enabled.
if( trGetN.x1.nVal < 0 || 100 < trGetN.x1.nVal ) { strErrMsg = "x1 is out of range. Must be from zero to 100."; bOKEnable = false; } else bOKEnable = true;
Output Error Message

When an X-Function is being called programmatically and its dialog is not going to be shown, then you need another way to notify the user of any errors that may occur. Origin C has defined macros to output an error message to the Results Log, Command Window or Script Window. It is strongly recommended that you use these macros instead of out_str or printf. The XF_WARN macros are used to output warning messages and do not terminate execution. All three macros accept a string as the first argument, containing the warning message. The two macros that accept additional arguments assume the warning message is also a format string for outputting one or two values.
// // // // XF_WARN(msg) XF_WARN_EX(msg, arg1) XF_WARN_EX2(msg, arg1, arg2) Assume the following: #define MIN_DATA_POINTS 5 int nNumPts = 3; string strWksName = "Book1";
X-Functions
193

XF_WARN("Too few data points."); XF_WARN_EX("Number of data points less than %d.", MIN_DATA_POINTS); XF_WARN_EX("Worksheet named %s was not found.", strWksName); XF_WARN_EX2("Only %d data points, need at least %d.", nNumPts, MIN_DATA_POINTS);
The XF_TRACE macro is similar to the XF_WARN macros in that it does not terminate execution. It also takes a message for the first argument, but it allows any number of additional arguments. XF_TRACE(msg, ...) // Assume the following: // #define MIN_DATA_POINTS 5 // int nNumPts = 3; // string strWksName = "Book1"; XF_TRACE("Only %d data points found in %s, need at least %d.", nNumPts, strWksName, MIN_DATA_POINTS); The XF_THROW macros terminate execution, but everything else about them is the same as the XF_WARN macros. All three macros accept a string containing the warning message as the first argument. The two macros that accept additional arguments assume the warning message is also a format string for outputting one or two values.
XF_THROW(msg) XF_THROW_EX(msg, arg1) XF_THROW_EX2(msg, arg1, arg2) // Assume the following: // #define MIN_DATA_POINTS 5 // int nNumPts = 3; // string strWksName = "Book1"; XF_THROW("Too few data points."); XF_THROW_EX("Number of data points less than %d.", MIN_DATA_POINTS); XF_THROW_EX("Worksheet named %s was not found.", strWksName); XF_THROW_EX2("Only %d data points, need at least %d.", nNumPts, MIN_DATA_POINTS);
17.1.4 Creating Graph Preview GetN Dialog

This section shows how to create an X-Function graph preview GetN dialog , including how to initialize a preview graph, how to update the preview graph on a GUI change, and how to update the GUI on the rectangle moving on the graph.
194
X-Functions
Create an Empty GetN Graph Preview Dialog

Press F10 to Open X-Function Builder. Type "PrevBox" into the X-Function EditBox as the X-Function name. Add a second variable by right-clicking on the Variables list and choosing "Add variable". Change the variable names, labels, and other values to match the settings in the dialog below.
Click Tree View button in X-Function Builder, open the branch Usage Context -> Menu, set Auto GetN Dialog to GetNGraphBox with Preview, then click the Save button to save this X-Function. Close X-Function Builder, and run "PrevBox -d" in Command window. A GetN graph preview dialog will show.
X-Functions
195
Coding X-Function in Code Builder
Open Origin Code Builder, in the menu choose File -> Open, locate the X-Function saved above, make sure the Add to Workspace check box is checked in the Open dialog, and click OK. PrevBox.XFC is added to the User folder in Origin C Workspace view and shows the function body in Edit view. Add the additional header file after the line //put additional include files here. For example: //put additional include files here #include <..\Originlab\grobj_utils.h>
Initialize Preview Graph

The GetNGraphPreview_OnInitGraph function is used to initialize a preview graph. Copy the following codes and paste them into the function, then click the Compile button. When the preview dialog box opens, a rectangle will display on the preview graph. Click Compile and run "PrevBox -d" in the Command window.
// cast pgTemp from PageBase class object to GraphPage object GraphPage gp(pgTemp); // load this template to the graph in order to contain zoom // in/out button on the graph. If this is not required, // remove this line. page_load(gp, "CurvePreview"); // get active graph layer in the graph page GraphLayer gl = gp.Layers(); // add a rectangle, set x position reference to xfrom and xto // variables GraphObject go; add_rect(gl, go, trGetN.xfrom.dVal, 0, trGetN.xto.dVal, -1, SYSCOLOR_BLUE, 2, LN_VERTICAL, true, false);
Update Preview Graph on GUI Change
To cause the preview graph to be updated, you need to include the UPDATE_GRAPH_CHANGED bit in the dwUpdateGraph variable in the GetNGraphPreview_OnChange function. For example: // include the bit to call GetNGraphPreview_OnUpdateGraph // to update graph if( !(dwUpdateGraph & UPDATE_GRAPH_CHANGED) ) dwUpdateGraph |= UPDATE_GRAPH_CHANGED;
Add the following code into the GetNGraphPreview_OnUpdateGraph function to update the graph. Click the Compile button and run "PrevBox -d" in the Command window. // cast pgTemp from PageBase class object to GraphPage // object
196
X-Functions

GraphPage gp(pgTemp); GraphLayer gl = gp.Layers(); // get active graph layer GraphObject go = gl.GraphObjects("Rect"); double x0 = trGetN.xfrom.dVal; double x1 = trGetN.xto.dVal; // update x position of rectangle on GUI vector vv(4); vv[0] = x0; vv[1] = x1; vv[2] = x1; vv[3] = x0; Tree tr; tr.Root.Data.X.dVals = vv; go.UpdateThemeIDs(tr.Root); go.ApplyFormat(tr, true, true); // refresh graph window gp.Refresh(TRUE);
Update GUI on Graph Object Event

If you want to update the GUI when you move/resize the rectangle on the preview graph, you need to:
Add the following to the GetNGraphPreview_OnInitGraph function after the add_rect function. // set event script to notify preview dialog when rectangle // is moved or resized. For other event types see the GRCT_* // in oc_const.h file. set_LT_script(go, "run -oc notify_dlg_on_move_obj;", GRCT_SIZEMOVE);
Add the following code to GetNGraphPreview_OnChange to update the new position of the rectangle to the GUI. Click the Compile button and run "PrevBox -d" in the Command window. if( bChangedByGraph ) { // get rectangle x from/to and update GUI GraphPage gp(pgTemp); GraphLayer gl = gp.Layers(); GraphObject goRect = gl.GraphObjects("Rect"); Tree tr;
X-Functions
197

tr = goRect.GetFormat(FPB_DATA, FOB_ALL, TRUE, TRUE); vector vv; vv = tr.Root.Data.X.dVals; trGetN.xfrom.dVal = vv[0]; trGetN.xto.dVal = vv[1]; // to include UPDATE_GRID_* bits to update GUI if( !(dwUpdateGrid & UPDATE_GRID_SIMPLE) ) dwUpdateGrid |= UPDATE_GRID_SIMPLE; }
Add Preview buttons

To add a Preview button and an Auto Preview check box, please see X-Functions: Customizing an X-Function: Adding Custom Button on Dialog: Show Preview Button on Graph Preview GetN Dialog
17.1.5 Creating Image GetN Dialog

This section shows how to create an X-Function GetN dialog with a matrix image data preview as in the following dialog, including how to initialize an image preview and dialog controls, and how to update the image preview or dialog controls on any control change in the dialog performed by the user.
198
X-Functions
17.1.5 Creating Image GetN Dialog
Create an Empty GetN Image Preview Dialog

1. 2. 3. Press F10 to Open X-Function Builder. Type "ImageBox" into the X-Function EditBox for X-Function name. Add more variables by right-clicking on the Variables list and choosing "Add variable". Change the variable names, labels, and other values to match the settings in the dialog below.
4. 5. 6.
on X-Function Builder, open the branch Usage Context -> Click the Tree View button Menu, set Auto GetN Dialog to GetNImageBox, then click the Save button to save this XFunction. Close X-Function Builder, open a new matrix window, choose menu File -> Import -> Image, select an image file, and click Open to import the image into a matrix window. Keep the matrix window active, and run "ImageBox -d" in the Command window. An image preview GetN dialog will show.
Coding X-Function in Code Builder

1. Open Origin Code Builder, in the menu choose File -> Open, locate the X-Function saved above, make sure the Add to Workspace check box is checked in the Open dialog, and click OK. ImageBox.XFC is added to the User folder in Origin C Workspace view and shows the function body in Edit view. Add the additional header file after the line //put additional include files here as in the following. //put additional include files here #include <image_utils.h> #include <..\Originlab\matdata_utils.h> 3. Add a static function, like the following, under the line //put your own support static functions here. //put your own support static functions here static bool _adjust_image_brightness_ex(BITMAPHANDLE* pPreviewBitmap, TreeNode& trGetN, bool& bOKEnable, string& strErrMsg)
2.
X-Functions
199

{ int nRet = adjust_image_brightness(pPreviewBitmap, trGetN.level.nVal); if( SUCCESS != nRet) { bOKEnable = false; // disable OK button if adjust image failed strErrMsg = "Fail to adjust image brightness"; // error message string return false; } return true; }
GetNImageBox_OnInit Event Function

This event function is called when the GetN image preview dialog is open. It can be used to initialize an image preview, initialize dialog controls and enable/disable the OK button. For this example, add the following code into the GetNImageBox_OnInit function to adjust the image brightness according to the value of the Level control.
// Get bitmap handle pointer from image preview control pBITMAPHANDLE pPreviewBitmap = pimgCntrl->GetBitmapHandlePtr(); // call internal function to adjust image _adjust_image_brightness_ex(pPreviewBitmap, trGetN, bOKEnable, strErrMsg);
GetNImageBox_OnChange Event Function

This event function is called whenever any controls in the grid are modified by the user. It can be used to update the image preview on a dialog control change, update a dialog control on another control change, or update the OK button's enable/disable status. Add the following code into the GetNImageBox_OnChange function.
// call internal function to adjust image, return true to update image preview. bUpdatePreview = _adjust_image_brightness_ex(pPreviewBitmap, trGetN, bOKEnable, strErrMsg);
Main Function
The main function has the same name as its corresponding X-Function. Add the following code into the main function and click the Compile button.
// Copy bitmap handle pointer from the input image to the output image bool bCopy = true; oimg.SetLBmp(iimg.GetLBmp(), bCopy); // Get bitmap handle pointer from the output image pBITMAPHANDLE phBmp = oimg.GetLBmp(); // adjust adjust_image_brightness(phBmp, level);
200
X-Functions
17.1.6 Creating Custom Dialog
Using X-Function
1. 2. 3. Run "ImageBox -d" in the Command window to open this X-Function dialog. Change the value of the Level control, and the brightness of the image preview will be changed. Click the button to open the theme context menu, choose Save As, type "mylevel" into the Theme Name box, then click OK to save the theme file. Click Cancel to close the XFunction dialog. Run "ImageBox -d -t mylevel" in the Command window to open the X-Function dialog with the specified theme.
17.1.6 Creating Custom Dialog

X-Functions support custom dialog created in a dialog builder as interface. If the user wants to use the customized dialog, and also wants to support Auto Update in the dialog, or wants to open the dialog from the Origin menu, then they can use an X-Function custom dialog. The following shows how to create an X-Function custom dialog. The dialog used in this example is an Origin built-in dialog resource; the user can generate the customized dialog according to the Dialog Builder chapter.
Creating X-Function
1. 2. Press F10 to open X-Function Builder. Type "CustomDlg" as the X-Function name and set the X-Function variables as below:
3.
Click the Tree View button to switch to Tree View, and choose Usage Context -> Menus -> Auto GetN Dialog to Custom. Then type the custom dialog function name, for example to "OpenCustomDlg", into the Custom Dialog Function edit box. Click the Save button save this X-Function and then close X-Function Builder. Create a new header file named CustomDlg.h and save it to the OriginExeFolder\OriginC\Originlab folder. Type the following code into this file. The code in the CustomDialog construct function is used to show how to get the X-Function settings from
4.
X-Functions
201

the X-Function to the dialog, and how to set back the settings from the dialog to the XFunction by way of the Origin C TreeNode variable. #include <xfutils.h> // needed for okxf_resolve_string_get_origin_object function #include <..\Originlab\DialogEx.h> class CustomDialog : public ResizeDialog { public: // IDD_SAMPLE_SPLITTER_DLG is the dialog resource ID. // ODlg8 is the name of the dialog resource DLL file. // It is Origin buildin file and located in // OriginExeFolder\OriginC\Originlab folder. // To specify DLL filename without file path as below means the location of // DLL file is same with this file - CustomDlg.h. CustomDialog(TreeNode& trXFSettings) : ResizeDialog( IDD_SAMPLE_SPLITTER_DLG, "ODlg8" ) { // Get the input column object from X-Function setting tree, // find the next column and assign the next column back to //X-Function setting tree. Column col; okxf_resolve_string_get_origin_object(trXFSettings.in.strVal, &col); if( col ) { Worksheet wks; col.GetParent(wks); Column colNext(wks, col.GetIndex()+1); if( colNext ) { string strColRange; colNext.GetRangeString(strColRange); trXFSettings.in.strVal = strColRange; } } } }; 5. Open Origin Code Builder, in the menu choose File -> Open, select your X-Function, make sure the Add to Workspace check box is checked in the Open dialog, and click OK. CustomDlg.XFC is added to the User folder in Origin C Workspace view and shows the function body in Edit view. Add the additional header file after the line //put additional include files here, as in the following. //put additional include files here
6.
202
X-Functions
17.1.7 Creating Wizard Dialog

#include <..\Originlab\CustomDlg.h> 7. Add a function to open the custom dialog after the line //put your own support static functions here, as below. The function name is input into the Tree View Custom Dialog Function edit box. The function interface, return type, and argument list should remain the same, as in the following. //put your own support static functions here bool OpenCustomDlg(TreeNode& tr, PEVENT_FUNC pfn, LPCSTR lpcszTitle, LPCSTR lpcszDescription, HWND hWndParent) { CustomDialog dlg(tr); if( dlg.DoModal(GetWindow()) ) { tr.AutoUpdate.nVal = AU_AUTO; // Default is 2(Manual) return true; } else // click Cancel button on dialog { return false; // will not call main function } } 8. Put the following code into the X-Function's main function. out = in; 9. Click the Compile button.
Using X-Function
1. 2. 3. 4. 5. Create a new worksheet with two columns, and fill the two columns with different data. Highlight column A and run "CustomDlg -d" in the Command Window. Click the Cancel button to close the dialog (there is no OK button in the sample dialog resource, so click Cancel here). A new column will be created with an Auto Update lock and the data of column B. The column selection has been changed in the custom dialog construct function to the next column from the original one. Changing any data in column B will trigger Auto Update to update the output column.

X-Functions support wizard dialogs. To create a wizard dialog, you need n+1 X-Functions, where n is the number of wizard pages. One is the main X-Function. The main X-Function is used to construct wizard pages and then open the wizard dialog if script mode is off, or run without dialog when script mode is on.
X-Functions
203
Creating a Wizard
The following shows how to create a two page wizard. Page 1 is used to select an XY range, and to specify the sub x range of the selected data range. Page 2 is used to add a rectangle with the specified fill color onto the source graph. The left x and right x of this rectangle are equal to the values of x from/to in Page 1.
1. Add a header file, wizDlg.h, under the UFF\OriginC\ folder. Put the following code into this header file to derive subclasses from Origin C built-in X-Function wizard classes. The XFunction basic wizard classes are: o XFCore, which is used to save and pass values in each page. o XFWizTheme, which is used to arrange theme settings for each wizard page. o XFWizInputOutputRange, which is used to arrange input and output ranges for each page. o XFWizManager, which is very important and must have a user-defined subclass derived from it. It is used to decide the steps in the wizard. #ifndef __WIZ_DLG_H__ #define __WIZ_DLG_H__ #include <..\OriginLab\XFWiz.h> #include <..\OriginLab\XFCore.h> #include <..\OriginLab\WizOperation.h> #include <..\OriginLab\XFWizNavigation.h> #include <..\OriginLab\XFWizManager.h> #include <..\OriginLab\XFWizScript.h> #include <..\OriginLab\XFWizDlg.h> #include <..\OriginLab\XFWizard_utils.h> /////////////////////////////////////////////////////////////////////////// class WizDlgCore : public XFCore { public: WizDlgCore() { } void SetXRange(double from, double to) { m_dFrom = from; m_dTo = to; } void GetXRange(double& from, double& to) {
204
X-Functions

from = m_dFrom; to = m_dTo; } private: double m_dFrom; double m_dTo; }; /////////////////////////////////////////////////////////////////////////// class WizDlgTheme : public XFWizTheme { }; /////////////////////////////////////////////////////////////////////////// class WizDlgInputOutputRange : public XFWizInputOutputRange { }; /////////////////////////////////////////////////////////////////////////// class WizDlgManager : public XFWizManager { public: WizDlgManager(LPCSTR lpcszThemeName = NULL, const XFWizTheme *pXFWizTheme = NULL, const XFWizInputOutputRange *pXFWizIO = NULL, DWORD dwUIDOp = 0); protected: virtual XFCore* virtual XFWizTheme* { return new WizDlgInputOutputRange; } virtual string GetClassName() { return "WizDlgExample"; } }; #define STR_XFNAME_PAGE_1 #define STR_XFNAME_PAGE_2 #define STR_LABEL_XFNAME_PAGE_1 #define STR_LABEL_XFNAME_PAGE_2 "wizPage1" "wizPage2" "Page 1" "Page 2" CreateXFCore() { return new WizDlgCore; } CreateXFWizTheme() { return new WizDlgTheme; }
virtual XFWizInputOutputRange* CreateXFWizInputOutputRange()
X-Functions
205

WizDlgManager::WizDlgManager(LPCSTR lpcszThemeName, const XFWizTheme *pXFWizTheme, const XFWizInputOutputRange *pXFWizIO, DWORD dwUIDOp) // = NULL, NULL, NULL, 0 : XFWizManager(lpcszThemeName, pXFWizTheme, pXFWizIO, dwUIDOp) { StringArray saMapXFNames = {STR_XFNAME_PAGE_1, STR_XFNAME_PAGE_2}; StringArray saMapXFLabels = {STR_LABEL_XFNAME_PAGE_1, STR_LABEL_XFNAME_PAGE_2}; m_saMapXFNames = saMapXFNames; m_saMapXFLabels = saMapXFLabels; ASSERT( m_saMapXFNames.GetSize() == m_saMapXFLabels.GetSize() ); m_saDefaultXFNames = saMapXFNames; } /////////////////////////////////////////////////////////////////////////// int run_wiz_nodlg(LPCSTR lpcszThemeName = NULL, const XFWizTheme *pXFWizTheme = NULL, const XFWizInputOutputRange *pXFWizIO = NULL, DWORD dwOPUID = 0) { TEMPLATE_run_wiz_nodlg(WizDlgManager, lpcszThemeName, pXFWizTheme, pXFWizIO, dwOPUID) } int open_wiz_dlg(LPCSTR lpcszThemeName = NULL, const XFWizTheme *pXFWizTheme = NULL, const XFWizInputOutputRange *pXFWizIO = NULL, DWORD dwOPUID = 0) { TEMPLATE_open_wiz_dlg(WizDlgManager, lpcszThemeName, pXFWizTheme, pXFWizIO, dwOPUID) } #endif 2. //__WIZ_DLG_H__
Press F10 to open X-Function Builder, to create a main X-Function as below.
206
X-Functions
3.
Click the button to save this X-Function. Close X-Function Builder. Open Code Builder, open the wizDlg.OXF file and add it to the current workspace. Add the following header files after the line //put additional include files here. #include <..\OriginLab\XFWiz.h> #include <event_utils.h> #include <..\OriginLab\WksOperation.h> #include <..\OriginLab\WizOperation.h> #include <..\OriginLab\XFCore.h> #include <..\OriginLab\XFWizNavigation.h> #include <..\OriginLab\XFWizManager.h> #include <..\OriginLab\XFWizScript.h> #include <..\OriginLab\XFWizDlg.h> #include <..\OriginLab\XFWizard_utils.h> #include <..\Originlab\wizDlg.h> // user added header file for this example
4.
Add the following code to the main function wizDlg WizDlgInputOutputRange objXFWizIO; if(!xfwiz_construct_input_range(&objXFWizIO, STR_XFNAME_PAGE_1, { XF_THROW(XFERR_FAIL_TO_UPDATE_GETN_TREE); } if( script ) { run_wiz_nodlg(theme, NULL, &objXFWizIO); } else iy))
X-Functions
207

{ open_wiz_dlg(theme, NULL, &objXFWizIO); } 5. Press F10 to open X-Function Builder and create the X-Function wizPage1 for the wizard page 1 as below.
6.
Add the following user-defined header file after the line //put additional include files here, as below. #include <..\Originlab\wizDlg.h> // user added header file for this example
7.
Put the following code into the page 1 main function wizPage1. WizDlgCore* pWizCore = (WizDlgCore*)get_xf_core_handler(NODE_NAME_XF_WIZ_CORE_POINTER); ASSERT(pWizCore); // Set X From/To to WizCore class object pWizCore->SetXRange(xfrom, xto);
8.
Add the following code to the wizPage1 X-Function _event1 function wizPage1_before_execute, to initialize the xfrom and xto controls according to the input data range. if( PDS_AUTO == okutil_cvt_str_to_predefined_type(trGetN.xfrom.strVal) || PDS_AUTO == okutil_cvt_str_to_predefined_type(trGetN.xto.strVal) ) { DataRange dr; TreeNode trRange = trGetN.iy; okxf_resolve_tree_construct_range(&trRange, &dr); vector vx; dr.GetData(DRR_GET_DEPENDENT, 0, NULL, NULL, NULL, &vx);
208
X-Functions

double from, to; vx.GetMinMax(from, to); trGetN.xfrom.dVal = from; trGetN.xto.dVal = to; } 9. Open X-Function Builder to create the X-Function wizPage2 for page 2. Set up the XFunction name and variables as below and click the Save button to save.
10. Open the wizPage2.OXF file in Code Builder, and add it to the current workspace to include header files, as below. //put additional include files here #include <..\Originlab\wizDlg.h> #include <..\Originlab\grobj_utils.h> 11. Find the main function wizPage2 and put the following code into it. The code is used to add a rectangle according to the xfrom and xto values assigned in page 1. WizDlgCore* pWizCore = (WizDlgCore*)get_xf_core_handler(NODE_NAME_XF_WIZ_CORE_POINTER); ASSERT(pWizCore); // Get the x from/to values that are specified in Page 1 double xfrom, xto; pWizCore->GetXRange(xfrom, xto); // To get input range. XFWizNavigation* pXFWizNavg = (XFWizNavigation*)(pWizCore->GetXFWizNavigation()); WizDlgInputOutputRange* pwizInputOutputRange = (WizDlgInputOutputRange*)(pXFWizNavg->GetXFWizInputOutputRange()); // Get input ranges from Page 1 Array<DataRange&> arrdr;
X-Functions
209

if( pwizInputOutputRange->Get(&arrdr, STR_XFNAME_PAGE_1, true) ) { DataRange& dr = arrdr.GetAt(0); vector<uint> vUIDs; DataPlot dp; if( dr.GetPlots(vUIDs) > 0 ) { // Get source graph layer from input range dp = (DataPlot)Project.GetObject(vUIDs[0]); GraphLayer gl; dp.GetParent(gl); // To add rectangle to graph GraphObject go; add_rect(gl, go, xfrom, 0, xto, 0, color, 2, LN_VERTICAL, true, false); } }
Using X-Function
Before running the example wizard, you need to create a new worksheet, fill two columns with data, and plot a line graph with two columns.
Run with wizard dialog

1. 2. 3. 4. 5. Keep the graph window active. Run "wizDlg" in the Command window. In the dialog that appears, change the values of the xfrom and xto controls. Click the Next button. In the next page, change the Fill Color control to Blue. Click the theme button , choose Save As, type in theme1 as the name, and click OK. Click the Finish button. The wizard dialog closes and a blue rectangle will be added to your source graph.
Run with script mode without dialog

Keep the graph window active. Run "wizDlg s:=1 t:=theme1" in the Command window. No dialog opens and a rectangle will be added to the active graph with the settings specified in the theme file.
17.1.8 Creating a Gadget Tool with X-Function

Origin offers some gadgets that operate on graphs. You can find them in the Gadgets menu when a graph is active.
210 X-Functions
When you choose one of the gadgets, Origin adds a rectangle to the graph, allowing you to choose the region of data to be analyzed. After selecting the region of interest (ROI), you can button and using the preference dialogs or themes open the context menu by clicking the to set up the analysis and output the results to desired destinations.
Origin allows users to add a user-defined gadget tool with an X-Function, and then add this tool to the Origin Gadgets menu.
Major Processes
To create a gadget tool, you need to do the three processes listed below:
1. 2. Creating an X-Function. The X-Function is used to include the dialog theme and add the feature to the Origin menu. Adding a user defined class derived from GraphObjCurveTool. GraphObjCurveTool is an Origin C building class, declared in the OriginExeFolder\OriginC\Originlab\GraphObjTools.h file. This class is used to create ROI(Region of Interested) objects and arrange events, including 'ROI moving' and the events from the ROI context menu. Adding event functions. The name of the global event function needs to be in the xfname_events format, where xfname is the name of the X-Function. A function arguments list must follow, as below. void xfname_events(string strGrName, int nEvent, int nMsg = 0);
3.
The following sections will introduce the details of each of the above processes.
Creating an X-Function
1. Press F10 to open X-Function Builder. Set up the X-Function name and variables, as in the following:
X-Functions
211
2. 3. 4.
Click the
button to save the X-Function.
Click the button to open the X-Function functions in a Code Builder window. To include the following header files, add them in after the line //put additional include files here, as below. //put additional include files here // to include graph object global functions #include <..\Originlab\grobj_utils.h> #include <..\Originlab\GraphObjTools.h> // to include GraphObjCurveTool class
5.
Find the function named quick_curve_stats_make_tree and add code to make a GUI tree in the function body, as the following demonstrates. if( 0 == strcmp(lpcszVarName, "trGUI") ) { GETN_USE(tr) GETN_OPTION_BRANCH(GETNBRANCH_OPEN) // default to open branch int nUserID = GET_USER_DATAID(0); int nBranchID = 1; GETN_STR(toolname, STR_TOOLNAME, "Quick Curve Stats")GETN_ID(nUserID++) // the option to add a checkbox control with editbox GETN_CONTROL_OPTION_BOX(1) GETN_COLOR(rectColor, "Rectangle Fill Color", SYSCOLOR_LTYELLOW) GETN_ID(nUserID++) GETN_COLOR_CHOICE_OPTIONS(COLORLIST_CUSTOM | COLORLIST_SINGLE) // quantities branch, for output result options GETN_BEGIN_BRANCH(quantities, "Quantities") GETN_ID(nBranchID++) GETN_OPTION_BRANCH(GETNBRANCH_OPEN|GETNBRANCH_CHECK_CONTROL)
212
X-Functions

GETN_CHECK(dataname, "Dataset Name", true) GETN_ID(nUserID++) GETN_CHECK(n, "Total Number", true) GETN_ID(nUserID++) GETN_CHECK(sum, "Sum", true) GETN_ID(nUserID++) GETN_CHECK(mean, "Mean", true) GETN_ID(nUserID++) GETN_CHECK(sd, "Standard Deviation", false) GETN_ID(nUserID++) GETN_CHECK(se, "SE of Mean", false) GETN_ID(nUserID++) GETN_END_BRANCH(quantities) // the end of quantities branch // output branch, the options for output destination GETN_BEGIN_BRANCH(output, "Output To") GETN_ID(nBranchID++) GETN_CHECK(script, "Script Window", true) GETN_ID(nUserID++) GETN_CHECK(reslog, "Results Log", false) GETN_ID(nUserID++) GETN_CHECK(outputwks, "Output to Worksheet", false) GETN_ID(nUserID++) GETN_END_BRANCH(output) // the end of output branch } return 0; 6. Click the button to compile the codes. After compiling is done, click the button to go back to X-Function Builder. 7. 8. button to save the X-Function again, then close X-Function Builder. Click the Run "quick_curve_stats -d" in the Command window. The following dialog will display.
X-Functions
213
Adding the Derived Class from GraphObjCurveTool

1. 2. In Code Builder, in the menu, click File -> New to open the New File dialog, and add a header file named QuickCurveStatsTool. Keep Location as the default path UFF\OriginC\, then click the OK button. In the QuickCurveStatsTool.h file, add the codes as follows, to include needed header files, define macros and add the user-defined class QuickCurveStatsTool, derived from the Origin building class GraphObjCurveTool. #include <..\originlab\grobj_utils.h> #include <..\Originlab\GraphObjTools.h> #define XF_NAME "quick_curve_stats" _L("Statistics")
#define TOOL_PREFERENCES_TITLE
class QuickCurveStatsTool : public GraphObjCurveTool { protected: string string string GetXFName() { return XF_NAME; } GetSignature() { return "xf_addtool_quick_curve_stats"; } GetPreferenceTitle(){ return TOOL_PREFERENCES_TITLE; }
// Will rewrite this function in Adding Event Functions section below. bool DoOutput(bool bUpdateLastOutput) { out_str("DoOutput"); return true; } }; 3. Open quick_curve_stats.XFC in Code Builder, to include QuickCurveStatsTool.h, as below. //put additional include files here // to include graph object global functions #include <..\Originlab\grobj_utils.h> #include <..\Originlab\GraphObjTools.h> #include "QuickCurveStatsTool.h" 4. Go to the X-Function main function, and use the class defined above to create a ROI on the graph. QuickCurveStatsTool curveTool(); int nErr = curveTool.Create(XF_NAME, LN_VERTICAL, trGUI); if(nErr) error_report("quick_curve_stats failed to Init!"); 5. Activate a graph window with a curve, and run "quick_curve_stats -d" in the Command window. A rectangle with top text, a title and two mini buttons will be added on the graph.
214
X-Functions
Adding Event Functions

Basic global event function
1. Open quick_curve_stats.XFC in Code Builder, and add the event function as below, after the line //put your own support static functions here //put your own support static functions here void quick_curve_stats_events(string strGrName, int nEvent, int nMsg = 0) { QuickCurveStatsTool sTool; graphobjtool_events(sTool, strGrName, nEvent, nMsg); } 2. Run this X-Function, "quick_curve_stats -d", in the Command window again, and click the OK button to close the dialog. Click the button, attached to the ROI, to open the context menu. Click New Output, and DoOutput will be printed on the Script window. Choose Preference, and a dialog with X-Function GUI settings shows. Change the color in the Rectangle Fill Color control, and update the text in the Show Tool Name control in the opening dialog, then click OK. The fill color and title text of the rectangle will be changed.
Overload virtual event functions

Run this X-Function, "quick_curve_stats -d", in the Command window to add a ROI. If you move the ROI on a graph, the Origin status bar on the left will show the current x from/to values and the width of the ROI. The following three steps will show you how to overload the OnMove virtual method to refresh the ROI top text with the curve statistics results, on 'ROI moving'.
1. Declare the following two methods in the QuickCurveStatsTool.h file. protected: BOOL OnMove(); private: string 2. getResult(TreeNode& trResult = NULL); Create a new QuickCurveStatsTool.cpp file under the UFF\OriginC folder. Add the implementation of the OnMove and getResult methods to this file, as below. /////////////////////////////////////////////////////////////////////////// // Include your own header files here. #include <GetNbox.h> #include "QuickCurveStatsTool.h" /////////////////////////////////////////////////////////////////////////// // Start your functions here. BOOL { string strTopText = getResult(); UpdateTopLabel(strTopText, true); QuickCurveStatsTool::OnMove()
X-Functions
215

return true; } string { // Get the data in ROI selected vector vx, vy; GetData(vx, vy); // Calculate statistic on data int npts; double sum, mean, sd, se; vy.Sum(sum); if( 0 != ocmath_basic_summary_stats(vy.GetSize(), vy, &npts, &mean, &sd, &se) ) { return "Error in calculation!"; } // Get output options from GUI Tree trGUI; GetGUITree(trGUI); bool bDatasetName = trGUI.quantities.dataname.nVal, bPoints = trGUI.quantities.n.nVal, bSum = trGUI.quantities.sum.nVal, bMean = trGUI.quantities.mean.nVal, bSD = trGUI.quantities.sd.nVal, bSE = trGUI.quantities.se.nVal; string strDatasetName; if( bDatasetName ) { m_dp.GetRangeString(strDatasetName); } // Put result to string string strText; string strNumDec = "*", strNextLine = "\r\n"; if( bDatasetName ) strText += "Dataset Name: " + strDatasetName + strNextLine; if( bPoints ) strText += "N = " + npts + strNextLine; if( bSum ) strText += "Sum = " + ftoa(sum, strNumDec) + strNextLine; QuickCurveStatsTool::getResult(TreeNode& trResult)
216
X-Functions

if( bMean ) strText += "Mean = " + ftoa(mean, strNumDec) + strNextLine; if( bSD ) strText += "SD = " + ftoa(sd, strNumDec) + strNextLine; if( bSE ) strText += "SE = " + ftoa(se, strNumDec) + strNextLine; strText.TrimRight(strNextLine); // Put result to tree if( trResult && trResult.IsValid() ) { GETN_USE(trResult) if( bDatasetName ) { GETN_STR(DatasetName, "Dataset Name", strDatasetName) GETN_CURRENT_SUBNODE.SetAttribute(STR_TYPE_ATTRIB, TNVAL_TYPE_CSTRING); } if( bPoints ) { GETN_NUM(N, "Number of Points", npts) } if( bSum ) { GETN_NUM(Sum, "Sum", sum) } if( bMean ) { GETN_NUM(Mean, "Mean", mean) } if( bSD ) { GETN_NUM(SD, "SD", sd) } if( bSE ) { GETN_NUM(SE, "SE", se) } } return strText; } 3. 4. Run the X-Function to add a ROI on your graph. Move the ROI, and the top text will be updated with the current statistics results of the selected Y data. The following shows how to make the context menu items "New Output" and "Go to Report Worksheet" work. You need to overload the DoOutput and GetReportWorksheet virtual
X-Functions
217

functions in the derived class QuickCurveStatsTool, and add a private function, acessBinaryInfo, to set and get the report worksheet name in the rectangle's binary storage. If you fail to get the report worksheet name from the rectangle, or the report worksheet name represents an invalid worksheet, the "Go to Report Worksheet" context menu item will be gray. Declare the following methods in the QuickCurveStatsTool.h file. protected: bool DoOutput(bool bUpdateLastOutput); BOOL GetReportWorksheet(Worksheet& wksReport); private: bool acessBinaryInfo(bool bGet, string& strInfo); 5. Add the implementation of the above three methods in the QuickCurveStatsTool.cpp file. bool { Tree trGUI; GetGUITree(trGUI); // Get output result to string and treenode Tree tr; TreeNode trResult; if( trGUI.output.outputwks.nVal ) trResult = tr.AddNode("Result"); string strResult = getResult(trResult); // Output to Script window, optional if( trGUI.output.script.nVal ) { LT_execute("type -a"); // to open Script window if closed out_str(strResult); } // Output to Result Log, optional if( trGUI.output.reslog.nVal ) { Project.OutStringToResultsLog(strResult); } // Output to worksheet, optional if( trGUI.output.outputwks.nVal ) { // To check output worksheet if already existed Worksheet wks; string strOutputWks; bool bCreateNew = true; if( acessBinaryInfo(true, strOutputWks) ) QuickCurveStatsTool::DoOutput(bool bUpdateLastOutput)
218
X-Functions

{ wks.Attach(strOutputWks); bCreateNew = !wks.IsValid(); } // If it doesn't exist, you need to create a new one, // then put worksheet name into rectangle binary storage if( bCreateNew ) { wks.Create(NULL, CREATE_HIDDEN); wks.SetSize(-1, 0); wks.GetRangeString(strOutputWks); acessBinaryInfo(false, strOutputWks); } out_tree_to_wks(trResult, wks); } return true; } BOOL { string strWks; if( acessBinaryInfo(true, strWks) ) { wksReport.Attach(strWks); return wksReport.IsValid(); } return false; } bool { string strStorageName = "Info"; Tree tr; if( bGet ) { // To get output worksheet name from rectangle binary storage if( m_go.GetBinaryStorage(strStorageName, tr) && tr.OutputWks && !tr.OutputWks.IsEmpty() ) { strInfo = tr.OutputWks.strVal; QuickCurveStatsTool::acessBinaryInfo(bool bGet, string& strInfo) QuickCurveStatsTool::GetReportWorksheet(Worksheet& wksReport)
X-Functions
219
17.2 Customizing an X-Function

return true; } return false; } else { // Save output worksheet name to rectangle binary storage tr.OutputWks.strVal = strInfo; return m_go.PutBinaryStorage(strStorageName, tr); } } 6. Prepare a graph with a data plot set as active, and run "quick_curve_stats -d" in the Command window to add a ROI. Move the ROI to an interesting area on the graph, open the context menu, and choose Preferences to open a dialog. Select all the check boxes in the Quantities and Output To branch, and click OK to close the dialog. Open the context menu again, and notice the Go to Report Worksheet menu item is gray. Click the New Output menu, and the result string will be outputted to a Script window and a Result Log, and a hidden worksheet will be created. Choose the Go to Report Worksheet menu, and the report worksheet displays. The columns in the worksheet hold the results.

17.2.1 Putting an X-Function in the Product Menu
Putting an X-Function into the Origin menu involves the following two steps: Modifying basic settings in the X-Function Builder Tree View Putting the X-Function into the specified main menu and sub menu Then, in the menu, choose Format:Menu:Full Menus, or restart Origin to auto-scan the changes for all X-Functions and add the newly added X-Function to the menu. Please refer to X-Function Builder's documentation for more details.
Setup in Tree View

To make your X-Function show properly in the menu, the following settings in X-Function Builder are required:
1. 2. Open the X-Function in X-Function Builder. Switch to Tree View mode, in the Usage Context branch. o Choose Main Menus for Menus. o Check the Windows check box. o Check one or several window types: Worksheet, Graph, or Matrix.
220
X-Functions
17.2.1 Putting an X-Function in the Product Menu
Menu Accessible
Once the X-Function is set up in Tree View, you can put the X-Function into the specified menu. Origin enables the user's X-Function to be accessible from the two kinds of menus: Default menu (This mechanism has a few limitations: you need to put the X-Function into the specified file folder, and the X-Function name needs to follow the specified prefix. Also, it is not easy to control its location in the menu. The next mechanism, a user defined menu, will solve all these problems.)
User defined menu
Default Menu
X-Functions are accessible from a specified default menu if they are saved in the proper subfolder of the X-Functions folder under the User folder.
All X-Functions in the subfolders below will be shown in the menu. Folder Signal Processing\ Spectroscopy\ Mathematics\ Statistics\ Menu Analysis: Signal Processing Analysis: Spectroscopy Analysis: Mathematics Statistics
All X-Functions with the specified prefix in the subfolders below will be shown in the menu.
Folder
Prefix imp* File: Import File: Export Worksheet Column
Menu
Import and Export\ exp* w* Data Manipulation\ col* Database Access\ db*
File: Database Access
X-Functions
221
The X-Functions in the Miscellaneous, Data Exploration, and Utilities folders will never be shown in the menu, except if the user directly modifies the XML file, the process for which will be described in the next section.
User Defined Menu

In addition to adding X-Functions to default menus, the user is able to put X-Functions into user-defined menus by editing the XML files under the OriginExePath\Themes\Menus folder. There are two XML files under this folder: ConfMenus.xml is used to control the Origin main menu, and ContextMenus.xml is for the context menu. Example The following is a complete example that shows how to add all X-Functions under the XFunctions\OC Guide\ folder to a new sub menu, OC Guide Tools, under Origin's Analysis main menu. The user-defined menu is the mid in Analysis:Fitting and Analysis:Signal Processing.
1. 2. 3. 4. 5. Open the X-Functions under the X-Functions\OC Guide folder in X-Function Builder. Switch to Tree View, in the Usage Context branch, set Menus as Main Menus, check the Windows check box, and check the Worksheet check box under the Windows branch. Type some text into the Description edit box, for example, "&Custom Dialog". & is used to access the quick selection menu with the keyboard. Click Save to save changes to the XFunction and close X-Function Builder. Open ConfMenus.xml in an XML editor, for example, XML Marker. Choose wks -> wksAnalysis -> wfit in the left panel. Copy the following and paste it into the right panel after <wfit...></wfit>, then click Save.
<testmenu1 Label = "OC Guide Tools" popup = "1"> <efg Label = ""> <name>*</name> <auxopts>2162688.</auxopts> <catsubcat DataID = "74">OC Guide</catsubcat> </efg> </testmenu1> 6. Close Origin and restart. Activate a worksheet and, in the menu, choose Analysis. Menu Test:Custom Dialog will display.
222
X-Functions
17.2.2 Adding Documentation to an X-Function
17.2.2 Adding Documentation to an X-Function

Documentation is necessary for an X-Function to be complete. In the documentation, the XFunction creator needs to tell the user something like how to use it, or how it is implemented. Now documentation, which can be written in four languages: English, Japanese, German, and Chinese, can be packaged into the X-Function. To do this, there are two X-Functions that can be used: xf2doc, and doc2xf. Note that these two X-Functions cannot be found from the menu, and can only be accessed from script. The X-Function xf2doc will unpack the help from the .oxf file and generate a Microsoft Word document to the specified path (If the option chm is checked, either from the dialog or using script xf2doc chm:=1, a document with the same structure as the chm help will be generated. This is useful when you need to preview the help). Then the document can be edited with Microsoft Word. After the documentation is finished, you need to save the document and then use doc2xf to package the document into the .oxf file. When documentation is finished for an X-Function that meets the specifications and can run compatibly, smoothly, and robustly, an integrated X-Function is born. Now you can share the X-Function with others simply through the .oxf file.
17.2.3 Adding Custom Button on Dialog

Adding Custom Button on Dialog
The following example shows how to add two custom buttons: the Reset button and the Apply button, to an X-Function dialog, as well as an event1 function to catch what button is being clicked.
1. 2. 3. Press F10 to open X-Function Builder. Type "CustomButton" into the X-Function edit box as the X-Function name. button to switch to the Tree View panel, and type "Reset|Apply" in the GetN Click the Dialog Custom Buttons edit box. Click Save to save this X-Function. Open the X-Function in Code Builder, and put the following code in the CustomButton_event1 function, then click the if( nEventID == GETNE_ON_CUSTOM_BUTTON1 ) { out_str("Reset click"); } if( nEventID == GETNE_ON_APPLY ) { out_str("Apply click"); } if( nEventID == GETNE_ON_OK ) button.
X-Functions
223

{ out_str("OK click"); } 4. 5. Run CustomButton -d in the Command window to open the dialog of this X-Function. There should be four buttons: Reset, Apply, OK and Cancel. Click the Reset button, and "Reset click" gets printed in the Command window. If you click the Apply button, "Apply click" is printed and the Cancel button is changed to a Close button. Click OK, and "OK click" is printed and the dialog is closed.
Show Preview Button on Graph Preview GetN Dialog

X-Function framework supports a Show Preview button and an Auto Preview check box on the Graph Preview GetN dialog. These two controls are used to update the preview automatically (keep the Auto Preview check box checked) or manually (click the Preview button). The following steps demonstrate how to add the two controls. The following five steps illustrate the process to add Preview button controls.
1. 2. Press F10 to open X-Function Builder. Type "PreviewButtons" into the X-Function edit box as the X-Function name. In the Variables table, set up a variable as below and then click the Save button to save this X-Function. Name: gp Label: Graph Input/Output: Input Data Type: string Control: ...Graph 3. 4. 5. Run the command PreviewButtons -d to open this X-Function dialog. There are only two buttons: OK and Cancel. Click Cancel to close the dialog. In X-Function Builder, click the button to switch to the Tree View panel, set Usage Context -> Menus -> Auto GetN Dialog as GetNGraphBox with Preview, and check the Show Preview Button check box. Save this X-Function. Run PreviewButtons -d to open the dialog again. Now there are two more controls displayed on the dialog: an Auto Preview check box and a Preview button.
The steps below show how to auto-update the dialog's preview graph according to the selection of the gp variable. For more details about the GetN Graph Preview Dialog, see XFunctions: Creating an X-Function: Creating Graph Preview GetN Dialog.
6. Open this X-Function in Code Builder, copy the following code, and paste it into the GetNGraphPreview_OnChange function. //include the bit to call GetNGraphPreview_OnUpdateGraph to update graph if( !(dwUpdateGraph & UPDATE_GRAPH_CHANGED) ) dwUpdateGraph |= UPDATE_GRAPH_CHANGED; 7. Copy the codes below into the GetNGraphPreview_OnUpdateGraph function. string strGraph = trGetN.gp.strVal; GraphPage gpSource(strGraph); GraphPage gpDest(pgTemp);
224
X-Functions
17.3.1 Calling X-Functions from Script

page_clone(gpSource, gpDest); 8. 9. Click the open the dialog. button. Then run PreviewButtons -d in the Command window to
button to In the dialog, type the graph page name into the Graph control, or click the choose one graph page via the Graph Browser dialog. Click the Auto Preview check box or the Preview button, and the specified graph will display on the preview panel. See the picture below.
17.3 Using X-Functions

17.3.1 Calling X-Functions from Script
X-Functions can be called from LabTalk by default. This means that by default you can call an X-Function from the Command Window, Script Window, and anywhere else LabTalk script can be executed. This includes .OGS files, toolbar buttons, and more. The LabTalk setting for an X-Function can be changed by doing the following:
1. 2. 3. Open the X-Function in X-Function Builder. Activate Tree View by choosing it on the Tools menu or by clicking the Tree View toolbar button. Expand the Usage Context branch to show the LabTalk setting.
When the check box is checked, it means the X-Function can be used from LabTalk.
Call an X-Function and show it's variables dialog

Passing the -dialog or -d option to an X-Function will open the X-Function's variables dialog. This dialog will allow you to set variables using the dialog's interface. The following will open the smooth X-Function variables dialog using all the default values.
smooth -d;
X-Functions
225
17.3 Using X-Functions
You can set some variables in the command line and still open the variables dialog. The variables that were not set in the command line will use their default values.
smooth (1,2) method:=2 -d;
Call an X-Function and do not show it's variables dialog

The variables dialog is not necessary to set variables. All variables can be set in the command line. Again, any variables that are not set in the command line will use their default values. The following will call the smooth X-Function to smooth the data in columns 1 and 2 using the "Savitzky-Golay" method, with a 5-point window and the boundary condition set to "reflect".
smooth (1,2) npts:=5 method:=SG b:=1;
The variable assignment can be done in multiple ways:

By variable index. Assign values without a variable name. For example, (1,2) assigns the data in the active Worksheet columns 1 and 2 to the iy variable. iy is the first variable. Use the default value. No assignment is necessary to use the default value. Here if you do not assign a value to the weight variable, the default value is 0. By the variable's full name. For example, npts:=5, assigns a numeric value of 5 to the npts variable; method:=SG, assigns enumeration to the method variable. By the first letter of the variable. For example, b:=1. This usage is very simple and can avoid having to remember the long variable names, but you need to make sure the first letter of each of the variables is unique.
Call an X-Function and set variables with a theme

The variable settings for an X-Function can be saved into a theme. You can call an X-Function and have it use a saved theme by using the -theme or -t option.
smooth (1,2) -t mytheme; // Call smooth and use the 'mytheme' theme smooth -t mytheme -d; // Open dialog and load the 'mytheme' theme
For more details please see the X-Functions: Accessing X-Functions from Script chapter in Origin's Help.
17.3.2 Calling X-Functions in Origin C

Origin comes with many X-Functions for handling a variety of tasks. X-Functions can be called from both LabTalk and Origin C. This Section will show you how to call X-Functions from Origin C using Origin C's XFBase class. This mechanism also can be used in calling one X-Function in another X-Function. The XFBase class is declared in the XFBase.h header file located in the Origin C System folder. The XFBase.h header file is not included in the Origin.h header file and must be included separately in any Origin C file that uses the XFBase class.
#include <XFBase.h>
Calling the impFile X-Function From Origin C

The following Origin C code defines a general function for importing files into Origin. The function takes two arguments: a data file name and an import filter file name. The function first
226 X-Functions
17.4.1 Construct Controls on X-Function GUI
creates an instance of the XFBase class, constructed with the name of the X-Function to be called. In this case, the X-Function name is impFile. It then sets the X-Function arguments using the SetArg method, and finally calls the X-Function using the Evaluate method.
bool call_impFile_XF(LPCSTR lpcszDataFile, LPCSTR lpcszFilterFile) { string strDataFile = lpcszDataFile; string strFilterFile = lpcszFilterFile; // Create an instance of XFBase using the X-Function name. XFBase xf("impFile"); if (!xf) return false; // Set the 'fname' argument. if (!xf.SetArg("fname", strDataFile)) return false; // Set the 'filtername' argument. if (!xf.SetArg("filtername", strFilterFile)) return false; // Call XFBase's 'Evaluate' method to execute the X-Function if (!xf.Evaluate()) return false; return true; }
The following Origin C code shows how to call our call_impFile_XF function defined above. We will call it to import an image file.
// Lets import the Car bitmap located in Origin's Samples folder. string strImageFile = GetAppPath(TRUE) + "Samples\\Image Processing and Analysis\\Car.bmp"; // Lets import the bitmap using the Image import filter. string strFilterFile = GetAppPath(TRUE) + "Filters\\Image.oif"; // Let's call our general function that will call the impFile X-Function. call_impFile_XF(strImageFile, strFilterFile);
17.4 X-Function Examples

Summary
This example demonstrates how to construct controls in an X-Function GetN dialog by TreeNode variable. This mechanism is used to avoid adding controls by multiple variables. This is an example X-Function dialog:
X-Functions 227
You will learn

1. 2. 3. How to create different controls by make_tree. How to update a GUI on a specified control event. How to check and ask for valid input.
Steps
1. 2. Select Tools: X-Function Builder to open the X-Function Builder dialog, select File: New X-Function Wizard to create an X-Function with only one Input Variable named GUI of TreeNode type, and save it as gui_controls.oxf. Open the X-Function in Code Builder, and add the following code into the gui_controls_make_tree function. if ( strcmp("GUI", lpcszVarName) == 0 ) // check variable by name { // ID should be unique int nBranchID = 0x0001; int nUserID = GET_USER_DATAID(0); //NodeID to enable Theme support GETN_USE(tr) //use this node as current node
//begin of sub branch GETN_BEGIN_BRANCH(UserInfo, "User Information") // string edit box GETN_STR(UserName, "Name", "Unknown") GETN_ID(nUserID++) GETN_ID(nBranchID++)
228
X-Functions

// pass word edit box GETN_PASSWORD(Password, "Password", "") GETN_ID(nUserID++) GETN_END_BRANCH(UserInfo) //end of sub branch //begin of sub branch GETN_BEGIN_BRANCH(Detail, "Details") GETN_ID(nBranchID++) // editable drop-down list GETN_STRLIST(Language, "Language", "English", "|English|German") GETN_ID(nUserID++) // radio buttons GETN_BEGIN_BRANCH(lGender, "Gender") GETN_ID(nBranchID++) GETN_RADIO_INDEX(Gender, 0, "Male|Female") GETN_ID(nUserID++) // the format of radio buttons GETN_OPTION_DISPLAY_FORMAT(DISPLAY_EDITOR_LEFT) GETN_END_BRANCH(lGender) //numeric edit box, age must be Integer, so use format "%d" GETN_NUM(Age, "Age", 18) GETN_OPTION_NUM_FORMAT("%d") GETN_ID(nUserID++) //check box with event handling function GETN_CHECK(iEmail, "Have Email", 0) GETN_ID(nUserID++)//check box GETN_OPTION_EVENT(_show_email) //event of iEmail checkbox // string edit box GETN_STR(Email, "Email", "") GETN_ID(nUserID++) GETN_END_BRANCH(Detail) //end of sub branch } 3. Add the following event handling functions after the line //put your own support static functions here. static bool _show_email(TreeNode& tr, int nRow, int nType, Dialog& Dlg) { TreeNode trDetail = tr.GUI.Detail; if ( !trDetail ) return false; int nShow = trDetail.iEmail.nVal; //if check, show, else hide. trDetail.Email.Show = (nShow == 1); return true; } static bool _check_email(LPCSTR lpcszEmail)
X-Functions
229

{ string strEmail(lpcszEmail); if ( strEmail.Count('@') != 1 ) return false; //should contains '@' and only one. int nSep = strEmail.Find('@'); string strLeft = strEmail.Left(nSep); string strRight = strEmail.Right(strEmail.GetLength() - nSep - 1); if ( strLeft.GetLength() == 0 ) return false; if ( strRight.GetLength() == 0 ) return false; LPCSTR lpcszInvalid = "~!#$%^&*()+ -=|\\/><,`"; if ( strEmail.FindOneOf(lpcszInvalid) >= 0 ) return false; return true; } 4. Add error checking code into the gui_controls_event1 function. if ( strcmp(lpcszNodeName, "Email") == 0 ) { string strVal = trGetN.GUI.Detail.Email.strVal; if ( !_check_email(strVal) ) { strErrMsg = "Invalid Email Address! Please correct it"; //disable OK button, should not continue when there is error. bOKEnable = false; } } 5. 6. Change the return value from return false (default) to return true to force a GUI change. In the X-Function body, we just print out the user settings by tree. Click the Compile button to compile and save changes. out_tree(GUI);
Run the X-Function

1. 2. 3. 4. Run the gui_controls -d command in the Script Window. Click the Have Email check box on the dialog, and an email edit box will display. If you input an invalid email address to the email edit box, for example, type in abc, an error message will show on the bottom of the dialog and the OK button will be disabled. Click OK. The setting tree will be outputted to the Script Window.
230
X-Functions
17.4.2 Open Graph Browser Dialog in X-Function
17.4.2 Open Graph Browser Dialog in X-Function

Summary
This example demonstrates how to add a button to open the Graph Browser dialog to pick a graph in the X-Function GetN dialog, and then how to customize the Graph Browser dialog by filter function.
You will learn

1. 2. How to add a button to open a Graph Browser in the X-Function dialog. How to customize the Graph Browser dialog by filter function.
Steps
The following three steps will show how to add a button in the X-Function dialog to open a Graph Browser dialog without the use of a filter function. This is the simplest process, and all settings in the Graph Browser dialog will be set to their defaults.
1. Select Tools: X-Function Builder from the Origin menu. Create an X-Function GraphFilterTest as follows.
2. 3.
4.
Note the control string is ...Graph GraphBrowserFilter. Click Edit X-Function in the Code Builder toolbar, and type out_str(pages); in the main function, GraphFilterTest. Click the Compile button and then click Return to Dialog. Click the Save OXF File toolbar button to save. Run GraphFilterTest -d in the Command window, and when a dialog shows, click the ... button to choose a graph, then click OK to close the dialog. The name of the selected graph window will be printed in the Command window. If you do NOT want to customize the Graph Browser Dialog, then there is no need to go on; the following steps are all about customizing the Graph Browser dialog, for example, setting the default view mode to Tree view. Create a GraphFilter.c file and save it in <Origin installation folder>\OriginC\OriginLab. The source file should include the following code. #include <..\Originlab\GraphFilter.h> // this is an Origin built-in file int GraphBrowserFilter(int nMsg, Page& pg = NULL) {
X-Functions
231

switch(nMsg) { case GBFM_IS_USE_PAGE: // return 1 for true. if(!pg) return -1; // filter page including multiple layers return pg.Layers.Count() > 1? 0 : 1; case GBFM_SHOW_EMBED_PAGE_CHKBOX: // see other options in GraphFilter.h return EMBED_CHECKBOX_ENABLE; case GBFM_SHOW_SWITCH_MODE: // see other options in GraphFilter.h return VIEW_MODE_BOTH_WITH_TREE_DEFAULT; case GBFM_SORT_PAGES: return 1; // return 0 or 1 } return -1; // error } 5. 6. Create a header file named MyGraphFilter.h and save it in <Origin installation folder>\OriginC\OriginLab. Open this X-Function in X-Function Builder, and click the Edit X-Function in Code Builder button, to include the newly created header file, from above. Note that MyGraphFilter.c and MyGraphFilter.h can also be put in another folder, but you have to make sure that they are in the same folder as each other. If they are in another folder, an absolute path should be used to include the header file, e.g. //Case 1. if header file is located in the OriginC\Originlab\ folder //put additional include files here #include <..\Originlab\MyGraphFilter.h> //Case 2. if header file is NOT located in the OriginC\Originlab\ folder //put additional include files here #include "D:\MyFolder\MyGraphFilter.h" 7. Run GraphFilterTest -d in the Command Window, and click the Browse button in the GraphFilterTest dialog. You can see that the Show Embedded Graph check box is enabled and selected, and the embedded graph is listed in the tree browser.
232
X-Functions
17.4.3 X-Function ReportTree Example
8.
Open MyGraphFilter.c from <Origin installation folder>\OriginC\Originlab\ with the Code Builder. Change the return value from EMBED_CHECKBOX_ENABLE to EMBED_CHECKBOX_DISABLE_EMBEDDING_PAGE_NEVER_ENABLE for the GBFM_SHOW_EMBED_PAGE_CHKBOX case. Click the Compile button to compile MyGraphFilter.c. Then run GraphFilterTest -d in the Command Window again. The Show Embedded Graph check box is disabled and unchecked now, and the embedded graph is not listed in the tree browser.
9.
You can try to use other enum values in <Origin installation folder>\OriginC\Originlab\GraphFilter.h as the return value for other cases in MyGraphFilter.c. Please remember to compile MyGraphFilter.c after each change. 10. The built-in X-Functions containing Graph Browsers (e.g. Import and Export X-Function expGraph) can be customized using the same method.

Summary
In this example, we will show how to do statistics on the selected data in a worksheet, and generate a report in a new hierarchy sheet. The selected data can be one column, multiple columns, or any one subrange in the worksheet.
X-Functions 233
As the output data type is ReportTree, the dialog will have a Recalculate combo box, which can set the recalculate mode of the report sheet to "Manual", "Auto Update" or "None".
You will learn

1. 2. 3. How to get data from the selected data range. How to do error handling in event1, before_execute and the main function. How to generate report tables in a hierarchy sheet with a recalculation lock.
Steps
1. Hit F10 to open X-Function Builder, enter the X-Function name and variables, as in the following picture, and then click Save. .
2.
Open this X-Function in Code Builder to edit the source code. First include the needed header file, as below. #include <ReportTree.h> // needed for ReportTable class
3.
Add error checking code into StatsReport_event1 to check the input data range, like in the following. DataRange drInput; drInput.Create(trGetN.iy.strVal); // if input is invalid, show error message // on the bottom of dialog // and disable OK button if ( !drInput.IsValid() || drInput.GetNumRanges() < 1 ) { strErrMsg = "Please select valid data for input"; bOKEnable = false; }
4.
Add error checking code in report_stats_before_execute. DataRange drInput;
234
X-Functions

drInput.Create(trGetN.iy.strVal); // if input is invalid, print out error message // and abort the X-Function execution if ( !drInput.IsValid() || drInput.GetNumRanges() < 1 ) { out_str("Invalid Input Data"); nRet = XFEVT_ABORT; } 5. Add a static function to check the input range after the line //put your own support static functions here static { int nRanges; if ( !iy.IsValid() ) return false; nRanges = iy.GetNumData(DRR_COLUMN_INDEX | DRR_NO_FACTORS); if ( nRanges <= 0 ) return false; return true; } 6. Add any needed macros under the static function. The macros will be used in the X-Function main function. // ID can be any value, but must be unique. #define TABLE_ID_BEGIN #define ROW_ID_BEGIN 7. 0x1000 0x0001 bool _check_input(const Range& iy)
In the X-Function main function StatsReport, add the following code to get the data from the specified data range, do statistics, and generate a report sheet. if ( !_check_input(iy) ) { // if input is not valid, // show error message and // abort X-Function execution. XF_THROW("Invalid input data"); return; } //create table to show statistics summary.
X-Functions
235

ReportTable rt = report.CreateTable("Summary",_L("Summary"), TABLE_ID_BEGIN); //report table's column headers. const vector<string> vsColLabels = { "N", "Number of Missing", "Mean", "SD", "SEM", "Sum", "Variance" }; int nRowID = ROW_ID_BEGIN; int nRanges = iy.GetNumData(DRR_COLUMN_INDEX | DRR_NO_FACTORS); for ( int nRange = 0; nRange < nRanges; nRange++ ) { // get the subrange - one column DataRange drOne; iy.GetSubRange(drOne, DRR_COLUMN_INDEX | DRR_NO_FACTORS, nRange); // get range string, like [Book1]Sheet1!A string strDataLabel; drOne.GetRangeString(strDataLabel); vector vInput; drOne.GetData(&vInput, 0); if ( vInput.GetSize() == 0 ) { // print out warning message when column is empty // and then go to the next column warning_msg_box( strDataLabel + ", empty column found.", false, 'W'); continue; } int N, Missing; double dMean, dSum, dVariance, dSD, dSE; int nRet = ocmath_basic_summary_stats(vInput.GetSize(), vInput,
236
X-Functions

&N, &dMean, &dSD, &dSE, &dVariance, &dSum, NULL, NULL, NULL, NULL, NULL, NULL, &Missing); if ( STATS_NO_ERROR != nRet ) { // print out warning message when // statistics function failed. warning_msg_box( strDataLabel + ", statistics fails.", false, 'W'); continue; } vector vResults(vsColLabels.GetSize()); vResults[0] = N; vResults[1] = Missing; vResults[2] = dMean; vResults[3] = dSD; vResults[4] = dSE; vResults[5] = dSum; vResults[6] = dVariance; //add new row to report table. string strName = "Data" + nRange; rt.AddRow(strName, vResults, strDataLabel, vsColLabels, NULL, nRowID++); }
Run the X-Function

Keep one Worksheet active with some data, highlight two columns, and type StatsReport -d in the Script Window to open the X-Function dialog.
X-Functions
237
Click OK , and a new report sheet will be generated.
17.4.4 X-Function ReportData Example

Summary
This example demonstrates how to get multiple XY data sets, do linear fitting on each XY, and put the fitted data into a new result sheet. As the output data type is ReportTree, the dialog will have a Recalculate combo box, which can set the recalculate mode of the report sheet to "Manual", "Auto Update" or "None".
You will learn

1. 2. How to work on multiple XY data sets. How to report data in a new result sheet with a recalculation lock.
Steps
1. Hit F10 to open the X-Function Builder, enter the X-Function name and variables, as in the following picture, and then click Save. .
2.
Open this X-Function in Code Builder to edit the source code. First include the needed header file, as below.
238
X-Functions
17.4.4 X-Function ReportData Example

#include <ReportTree.h> // needed for ReportTable class 3. Add any needed macros under the line //put your own support static functions here. The macros will be used in the X-Function's main function. // ID can be any value, but must be unique. #define TABLE_ID #define SUBNODE_ID_BEGIN 4. 1000 1
In the X-Function's main function, FitLinearReport, add the following code to get the XY data from the specified data range, do linear fitting on each XY, and generate a report sheet. // create report table ReportTable rt; rt = rd.CreateTable("ReportData", "Fitted Data", TABLE_ID); int nSubID = SUBNODE_ID_BEGIN; DWORD dwRules = DRR_GET_DEPENDENT | DRR_NO_FACTORS; int nNumData = iy.GetNumData(dwRules); for(int nRange = 0; nRange < nNumData; nRange++) { DataRange drOne; iy.GetSubRange(drOne, dwRules, nRange); vector vx, vy; drOne.GetData(dwRules, 0, NULL, NULL, &vy, &vx); // there are two parameters in linear fitting FitParameter sFitParameter[2]; if( STATS_NO_ERROR == ocmath_linear_fit(vx, vy, vy.GetSize(), sFitParameter) ) { // add fitted X data to report table string strName = "X" + (nRange+1); string strLongName = "X"; rt.AddColumn(vx, strName, nSubID++, strLongName, OKDATAOBJ_DESIGNATION_X); // calculate fitted Y data double dIntercept = sFitParameter[0].Value; double dSlope = sFitParameter[1].Value; vector vFitY; vFitY = vx * dSlope + dIntercept; // add fitted Y data to report table
X-Functions
239

strName = "Y" + (nRange+1); string strRange; strRange = drOne.GetDescription(GETLC_COL_LN_ONLY); strLongName = "Fitted data on " + strRange; rt.AddColumn(vFitY, strName, nSubID++, strLongName, OKDATAOBJ_DESIGNATION_Y); } }
Run the X-Function

1. 2. Import Linear Fit.dat from OriginExePath\Samples\Curve Fitting to a Worksheet. Highlight all columns and run FitLinearReport -d in the Script window, and then you can see the dialog below.
3.
Accept the default settings, and click the OK button. A report sheet will be generated with three group-fitting XY data sets.
240
X-Functions
18
Accessing External Resources
Origin C can access external DLLs and, in addition, applications outside of Origin can be added using automation (COM) server capability.
18.1 Access an External DLL

Origin C can make calls to functions in external DLLs created by C, C++ or Fortran compilers. To do this, you need to provide the prototype of a function in a header file and tell Origin C which DLL file contains the function body. Assume the functions are declared in a header file named myFunc.h. You should include this file in your Origin C file where you want to call those functions, like:
#include <myFunc.h> //in the \OriginC\System folder #include "myFunc.h" //in the same folder as your Origin C code #include "C:\myFile.h" //in specified path
Then you should tell Origin C where to link the function body, and you must include the following Origin C pragma directive in the header file myFunc.h, just before your external DLL function declarations. Assume your DLL file is UserFunc.dll:
#pragma #pragma #pragma #pragma dll(UserFunc) //in the same folder as your Origin C code dll(C:\UserFunc) //in specified path dll(UserFunc, header) //in the same folder as this .h file dll(UserFunc, system) //in the Windows system folder
The Origin C compiler supports three calling conventions: __cdecl(default), __stdcall and __fastcall. These calling conventions determine the order in which arguments are passed to the stack as well as whether the calling function or the called external function cleans the arguments from the stack. Notes: you don't need to include the .dll extension in the file name. And all function declarations after the pragma directive will be considered external and from the specified DLL. This assumption is made until a second #pragma dll(filename) directive appears, or the end of the file is reached. A good and complete example of how to access an external DLL is Accessing SQLite Database. There are other Origin sample projects demonstrating how to call a function from a C dll or a Fortran dll in Origin C. They can be found in the \Samples\Origin C Examples\Programming Guide\Calling Fortran and \Samples\Origin C Examples\Programming Guide\Calling C DLL subfolders of Origin.
241
18.2 Access an External Application

The Microsoft Component Object Model (COM) is a software architecture that allows applications to be built from a binary software component, and it makes the development of software much easier and more effective. Origin provides the capability for COM client programming, and it is supported only in OriginPro. This mechanism uses Object type to represent all COM (automation server) objects. All COM objects can be initialized in two ways:
//by the CreateObject method Object oExcel; oExcel = CreateObject("Excel.Application"); //by initialization from an existing COM object. Object oWorkBooks; oWorkBooks = oExcel.Workbooks;
Origin C also provides a class to access Matlab, which enables communication between Origin and Matlab.
#include <Origin.h> #include <externApps.h> //required header for the MATLAB class void test_Matlab() { Matlab matlabObj(true); if(!matlabObj) { out_str("No MATLAB found"); return; } //defines 3x5 matrix named ma string strRet; strRet = matlabObj.Execute("ma=[1 2 3 4 5; 4 5 6 7 8;10.3 4.5 -4.7 -23.2 -6.7]"); out_str(strRet);// show str from MATLAB // put matrix into Origin matrix MatrixLayer matLayer; matLayer.Create(); Matrix mao(matLayer); //Transfer MATLAB's matrix (ma) to Origin's mao matrix. BOOL bRet = matlabObj.GetMatrix("ma", &mao); }
COM client programming in Origin C can be used to programmatically exchange data with MS Office applications. There is a comprehensive example demonstrating how to read data from Excel worksheets, plot a graph in Origin, and place it in a Word document. This example can be found in the \Samples\COM Client\MS Office subfolder in Origin. (Origin C COM programming can also be used to communicate with databases by accessing an ActiveX Data Object (ADO), and there is a sample file demonstrating that SQL and Access databases can be imported to a worksheet, and subsequent data modifications returned to the
242
database. For more information, see the file ADOSample.c in the Samples\COM Clients\ADO subfolder of Origin.
243
19
Reference
19.1 Class Hierarchy

The following schematic diagram shows the hierarchy of built-in Origin C classes.
245
19.1 Class Hierarchy
246
Reference
19.2 Collections
19.2 Collections
The Collection class provides a template for holding multiple objects of the same type. In Origin C, an instance of a Collection is read-only. You cannot add items to, or delete items from, a collection. There are a number of Origin C classes that contain data members which are instances of a Collection. For example, the Project class contains a data member named WorksheetPages. The WorksheetPages data member is a collection of all the existing WorksheetPage objects in the project. The table below lists each of the Origin C Collections, along with the class that contains the collection and the item types in the collection.
Class Folder Folder GraphLayer GraphLayer GraphPage Layer MatrixLayer Page Project Project Project Project Pages SubFolders DataPlots StyleHolders Layers GraphObjects MatrixObjects Layers DatasetNames GraphPages LayoutPages LooseDatasetNames Data Member PageBase Folder DataPlot StyleHolder GraphLayer GraphObject MatrixObject Layer string (loose and displayed datasets) GraphPage LayoutPage string (loose datasets) Collection of
Reference
247
19.2 Collections
Project Project Project Project Selection TreeNode Worksheet Worksheet MatrixPages Notes Pages WorksheetPages Objects Children Columns EmbeddedPages MatrixPage Note PageBase WorksheetPage OriginObject TreeNode Column Page
Examples List all graph pages in the current project.

foreach(GraphPage gp in Project.GraphPages) { out_str(gp.GetName()); }
List all worksheet pages in the current project.

foreach(WorksheetPage wksPage in Project.WorksheetPages) { out_str(wksPage.GetName()); }
List all matrix pages in the current project.

foreach(MatrixPage matPage in Project.MatrixPages) { out_str(matPage.GetName()); }
List all data plots.

GraphLayer gl = Project.ActiveLayer(); foreach(DataPlot dp in gl.DataPlots) { string strRange; dp.GetRangeString(strRange, NTYPE_BOOKSHEET_XY_RANGE); printf("%d, %s", dp.GetIndex()+1, strRange); }
248
Reference
19.3 X-Function Option Strings

19.3.1 A - Recalculate Mode
Recalculate Options enable you to control the Recalculate mode of an X-Function. By default, when the X-Function includes one of the following Origin Object types as an input or output variable: XYRange, XYZRange, vector, Column, matrix and MatrixObject, it allows you to use Manual, Auto or None as the Recalculate mode (the default mode is Manual). Please note that if the variable is used as both an input and output variable, the Recalculate mode is forbidden, and the Recalculate combo box will be hidden.
A:0x00
Hides the Recalculate combo box from the X-Function dialog. Example
1. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
2.
Run this X-Function with the command OptionStringA -d; in the Command Window. In the dialog that opens, you will not see the Recalculate combo box.
Reference
249
A:0x01
Sets None as the default Recalculate mode. This mode is available for both input variables and output variables. Example
2.
Run this X-Function with the command OptionStringA1 -d; in the Command Window. In the dialog that opens, the Recalculate combo box shows with None selected.
A:0x02
Allows sorting on the output columns with the Recalculate mode. It works for output variables only. Example
250
Reference
2.
Create a new worksheet with one column and fill this column with row numbers. Then highlight the column and run the X-Function with the command OptionStringA2 -d; in the Command window. After clicking the OK button, two empty output columns with locks will show, as below.
3.
Click on the header of column B to highlight it, then move the mouse to the Sort Worksheet item of the right-click menu. The sub context menu is available for sorting the output columns.
A:0x04
Allows the Recalculate mode, but the Recalculate combo box will be hidden in the X-Function dialog.
Reference 251
19.3.2 B - Browser Dialog Options

Browser Dialog Options control the settings in the Page/Graph Browser dialog, which is opened by a button in the X-Function dialog. They can also be used to filter the opened dialog. Please refer to the example about X-Function Graph Browser dialog.
B:0x0001
Sorts all pages in the Page/Graph Browser once the dialog opens.
B:0x0002
Excludes 3D graphs from the Graph Browser.
19.3.3 C - Miscellaneous Options

C:0x0001
Disables composite ranges from assigning column designation. Take an output variable with XYRange type, for example. If this option string is not specified for the variable, there will be two output columns, one with X designation and the other with Y designation. Otherwise, the two columns will both have the default Y designation.
C:0x0002
Creates a new page with hidden state.
C:0x0004
Makes an X-Function non-undoable.
C:0x0010
By default, if a variable with double type is missing a value, this variable will show nothing (empty cell). This option string is used to show this kind of empty variable as "--".
C:0x0100
This option string is only available for output variables of Range type. If the output variable is set to <new>, a valid Origin C Range object will be created, but without a new column for it. This option string helps the user prepare rows and columns for the output range objects inside the X-Function body.
252
Reference
C:0x0200
This option string is only available for output variables of Range type. If the output variable is set to <new>, it will replicate the input Range, with the same number of columns and rows.
19.3.4 E - Execution Control

E:V Used in the X-Function wizard and X-Function bar to keep the real value of a variable. The destination created by the first Apply button will be used by the subsequent Apply buttons.
19.3.5 F - Dialog Numeric Display Format

F:*6* Provides a format string for displaying numeric values with double type. The standard LabTalk numeric format notation, such as *(Origin global numeric format setting), .2(two decimal digits), etc., can be used.
19.3.6 FT - Data Plot Selection Filter

FT:str1|str2 Specifies the tags for the action filter of data selection from a graph. If a data object contains tags str1 or str2, it will be ignored when selecting the data hunting menu item Add all plots in active page/layer. Example This example will show how to use the FT option string to exclude the data plot with tag name TestCurves when selecting all plots from a graph.
1. Create a new X-Function with the name and variables shown in the following image. Then to save the X-Function in <User Files Folder>\X-Functions\OC click the Save button Guide\ (if this folder does not exist, create it).
Reference
253

2. Open this X-Function in Code Builder, then copy the following code and paste it into the body of the main function, OptionStringFT, then click the Compile button . // Put data to output XYRange vector vx, vy; vx.Data(1, 10, 1); vy = vx; oy.SetData(&vy, &vx); // The specified name should be the same as options string "FT" of iy tag_columns_in_data_range(oy, "TestCurves"); // Get source range graph, and plot results on this graph vector<uint> vnIDs; if( iy.GetPlots(vnIDs) > 0 ) { DataPlot dp; dp = (DataPlot)Project.GetObject(vnIDs[0]); GraphLayer gl; dp.GetParent(gl); gl.AddPlot(oy); } 3. Import the file <Origin Installation Folder>\Samples\Curve Fitting\Multiple Gaussians.dat to a new worksheet. Highlight all columns and make a graph with line plots. Activate the newly created graph and run OptionStringFT -d; in the Command Window, then click the OK button to generate the output XY columns in the source worksheet and add its plot to the source graph. Activate the graph and run OptionStringFT -d; again to open the X-Function dialog. In the Input XY branch, the newly outputted data plot from above is not there, because of the tag name TestCurves of this data plot.
4.
19.3.7 FV - Specify the Source of Output Variable

FV:varname specifies the name of the input variable for each output variable. Then the information of this variable's book/sheet/object will be traced and shared with the output variable when the output variable is set by <input>/<same>. For example, suppose an XFunction contains three XYRange variables: the first two are input variables and the last one is an output variable. If the name of one input variable is set to the output variable by this option string, the output columns will be the same as the specified input columns when output is set as <input> or <same>. Otherwise, the output columns will be the same as the first input columns.
254
Reference
19.3.8 G - Grouping Controls on GUI

Used to group related variables in the X-Function dialog. Add G:Group Name in the Option String field of the variable for the beginning of the group, and G in the Option String field of another variable for the end of the group. G:Group The beginning of the group. By default, the branch of the group is closed. To set the branch as open for the first time, open the dialog and add a dash before Group Name, like G:-Group Name. Then the dialog will remember the branch status when opened next time. G The end of the group. Example
1. Press F10 to open X-Function Builder. Create an X-Function as the following image shows to save it into <Origin User Files Folder>\Xand then click the Save button Functions\OC Guide\ (if this folder does not exist, create it).
2.
Run OptionStringG -d; in the Command window. The dialog that opens will look like the one below.
Reference
255
19.3.9 H - Setting Result Tables Shown Style

2.
Open this X-Function in Code Builder, and add the following needed header file after the line //put additional include files here. #include <ReportTree.h>
3.
Copy the following code into the main function, OptionStringH, which is used to do basic statistical analysis on the selected data and then prepare the report sheet for the results. // Get data from Data Range object matrix mData; if( rng.GetData(mData) <= 0 ) { XF_THROW("No data is selected"); } // Calculate the basic statistics on each column vector vPoints, vSum, vSD; for(int index = 0; index < mData.GetNumCols(); index++) { vector vData; mData.GetColumn(vData, index); int nPoints; double dSum, dSD; ocmath_basic_summary_stats(vData.GetSize(), vData, &nPoints, &dSum, &dSD); vPoints.Add(nPoints);
256
Reference

vSum.Add(dSum); vSD.Add(dSD); } // Create data table int nID = 0; // ID should be unique ReportTable rTable = rt.CreateTable("Report", "Report Table", ++nID, 0, 1); rTable.AddColumn(vPoints, "N", ++nID, "Points", OKDATAOBJ_DESIGNATION_Y); rTable.AddColumn(vSum, "Sum", ++nID, "Sum", OKDATAOBJ_DESIGNATION_Y); rTable.AddColumn(vSD, "SD", ++nID, "SD", OKDATAOBJ_DESIGNATION_Y); // Set this attribute as 0 not to specify any format. // Many bits GETNBRANCH_* defined in oc_const.h to set table display format. rTable.SetAttribute(TREE_Table, GETNBRANCH_TRANSPOSE); 4. Create a new worksheet with five columns, then fill all the columns with uniform random data (by highlighting all columns and selecting context menu item Fill Columns With: Uniform Random Numbers). Run OptionStringH -d; in the Command window to open the dialog. In the dialog, make sure that all the columns are selected for Input Data and <new> is selected for Report. Click the OK button and the report sheet will be displayed in the normal format (H:0).
5.
Open the X-Function in the X-Function Builder again and change H:0 to H:1. Then save it. Run OptionStringH -d; in the Command window again. This time the report sheet will display in hierarchical table format (H:1).
Reference
257
19.3.10 I - Restrict the Behavior of Input Range Control

Restricts the input data range and modifies the behavior of the interactive controls. This Option String only works for the following input data types: Range, XYRange, XYRangeComplex, XYZRange, vector, vector<string>, and vector<complex>.
I:0x0001
Allows multiple data selection in the 1st subrange.
I:0x0002
Allows multiple data selection in the 2nd subrange.
I:0x0004
Allows multiple data selection in the 3rd subrange.
I:0x0008
Allows multiple data selection in all subranges.
I:0x0010
(Obsolete) Restricts to one data set. This is default behavior, no need to set.
I:0x0020
Supports Y error, XYRange only.
258
Reference
I:0x0040
Supports label area in Range. By using this Option String, the output range will not clear the data before execution, which is similar to I:0x00040000.
I:0x0080
The <input> option will disappear from the pop-up menu of the output variable.
I:0x0100
The <new> option will disappear from the pop-up menu of the output variable.
I:0x0200
The (<input>,<new>) options will disappear from the pop-up menu of the output variable, XYRange only.
I:0x0400
Gets rid of the button for the pop-up menu.
I:0x0800
Gets rid of the interactive button.
I:0x1000
Valid for input variables with vector and Column type only. When the string for data selection is obtained, Columns are identified by indices, but not the short names of the columns.
I:0x2000
This Option String will make the vector variable only use the Y column while initializing.
I:0x4000
Shows the Column Browser button.
I:0x8000
Sets variable as read-only, both I:0x0400 and I:0x0800 together will also work.
I:0x00010000
Gets rid of row selection while initializing, Column variable only.
Reference 259
I:0x00020000
Replaces the range string of the whole sheet with column notation. For example, if a worksheet in Book1 named Sheet1 contains two columns, then the range string [Book1]Sheet1 will be replaced with [Book1]Sheet1!1:2.
I:0x00040000
This Option String makes the output range not clear the data before finishing the execution. Without this Option String, if there is no overlap in the input data ranges, columns in the output ranges will be cleared before using new data. Example
2.
Open this X-Function in Code Builder, then copy the following code, which will copy data from the input column to the output column, into the body of the main function, OptionStringI, and then click the Compile button orng = irng; .
3.
Create a new worksheet with two columns: column A and column B, then select the first 10 rows in column A and choose Fill Range with: Row Numbers from the right-click menu to fill these 10 rows with row numbers. Run OptionStringI -d; in the Command Window, choose column A as input and column B as output, then click the OK button. The result is that column B is now also filled with row numbers. Select the first 5 rows from column A, right-click them to open the context menu, and choose the Delete item to delete these 5 rows. The color of the lock on the header of column B changes from green to yellow. Click the lock and choose Recalculate from the pop-up menu. The result is that the original data in the last 5 rows of column B are kept there, as shown in the following image.
4.
260
Reference
I:0x00080000
Makes all columns show in the interactive pop-up menu.
I:0x00100000
If there are no selections in the active graph layer and the range variable is set by using <active>, the range variable will set to all plots in the active layer.
I:0x00200000
Uses the sampling interval as output X.
I:0x00400000 I:0x00800000
Makes the existing columns or plots show in the interactive pop-up menu.
I:0x02000000
If the output XYRange is set by using <auto>, this option creates a new X column.
I:0x04000000
The row range will be ignored, and only the single block range is valid. If there is no selection or the selection only includes one single cell, the selection will be considered to be the whole worksheet.
Reference
261
I:0x08000000
Creates the range string by using the first and last X values instead of the indices. The syntax is [BookName]SheetName!ColName[xFirstValue:LastValue]. It is very useful for monotonous data.
I:0x10000000
The Range variable will have no factor and no weight.
19.3.11 M - Support Multi-line String

M:m-n Makes a string variable support multi-line text. If the string variable is hidden, m lines of text are supported, if expanded, n lines are supported.
19.3.12 N - Setting the Default Name of Output Objects

Specifies the default name of an output object. ReportTree and ReportData N: "Name" Book:="Book Name" Sheet:="Sheet Name" MatrixObject N: "Name" Book:="Book Name" Sheet:="Sheet Name" X:="Object Name" MatrixLayer, Image, vector, Column N: "Name" XYRange N: X:="X Name" Y:="Y Name" XYZRange N: X:="X Name" Y:="Y Name" Z:="Z Name" Worksheet N: Book:="Book Name" Sheet:="Sheet Name"
19.3.13 O - Setting Output Object Action after Running XFunction

Specifies the action of the output variable after running successfully.
262
Reference
O:A
Activates the corresponding Origin object, no matter if the object is hidden or in a different folder.
O:C
Activates the corresponding Origin object only when the workbook is the active window.
O:N
Does not activate the corresponding Origin object.
19.3.14 P - Setting Control Editable on GUI

Specifies whether a variable is editable in the X-Function dialog.
P:0 or P:1
P:1 is the default Option String. Using this Option String, the output variable, which is of an Origin object type, such as column, worksheet, etc., will be non-editable when bringing up the X-Function dialog again via Change Parameters. The variables with other types need to specify the Option String as P:0 to do so.
P:2
Only shows the label, and the editable field is invisible.
P:4
Shows the variable as a separator in the X-Function dialog; valid for string type only. Example
1. Press F10 to open X-Function Builder, and create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the XFunction in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
Reference
263
2.
Click the Edit X-Function in Code Builder button to open this X-Function in Code Builder. Type the code out = in + var; into the body of the main function, OptionStringP, and then click the Compile button . Create a new worksheet and fill some data into column A. Run OptionStringP -d; in the Command window. In the dialog that opens, select column A as Input Column and column B as Output Column. Click the OK button, and the result is generated and stored in column B. Click the lock icon on the header of column B and choose Change Parameters from the context menu. The difference between the dialog opened by Change Parameters and the one opened by OptionStringP -d; is shown in the following image.
3.
4.
264
Reference
19.3.15 R - Restrict the Behavior of Dialog Combo Box

Used to control the value of the combo box in the X-Function when calling it via LabTalk script. It will not affect the dialog.
R:0
No restriction. Besides the values defined in the list in the combo box, other values can also be assigned to the combo box variable by using LabTalk script.
R:1
Default Option String. Only the values defined in the list in the combo box can be assigned to the combo box variable by using LabTalk script. Example
1. 2. 3. 4. Create a new X-Function (named OptionStringR) with a variable (named x1) of int type. In the Control column, set AA|BB|CC for this variable. Run OptionStringR x1:=5; in the Command window, and you will get an error: #Command Error!. Open this X-Function in X-Function Builder again, set R:0 for the int variable in the Option String column and save this X-Function. Run OptionStringR x1:=5; in the Command window again, and you will get no error.
19.3.16 S - Defining Default Data Selection for Input Variable

Defines the default data object for input variable. This Option String is only for variables of Range type.
S:0
All columns in the active worksheet are selected as the data range.
S:0x01
The first matrix object of the active matrix sheet, or the first column of the active worksheet, is selected as the data range.
S:0x10
Makes it so the <active> option gets nothing but the matrix object. For the output variables, the <active> option will be replaced with <new>, which will create a matrix page.
Reference
265
19.3.17 SV - Support String Item in X-Function Dialog Combo Box

Replaces the item values in a combo box with special values. For example, if a variable of int type is set as a combo box via the Begin|Mid|End string in the Control column, then the default item values for the combo box items are 0, 1, and 2, respectively. If the Option String SV:1|5|-1 is used for this variable, the return values of the items in the combo box are 1, 5, and -1, respectively.
19.3.18 T - Skipping the Variable from Theme

Controls whether a variable is remembered in the X-Function dialog theme file. This Option String is only valid during theme selection in Tree View, which is the default setting.
T:0
If the specified theme is selected, the theme value will be used as the variable value.
T:1
Does not use the theme value as the variable value, even if a theme is selected.
T:4
If the specified theme is selected, both the theme value and the attribute will be used by the variable. This option is mainly used on Origin internal objects, such as XYRange, Image, etc.
19.3.19 U - Specifying Output as Optional

Specifies whether the output variable is needed. This option string is only available for XFunctions with multiple output variables.
U:1
Adds a selected check box for the output variable. This is the default option.
U:0
Adds an unselected check box for the output variable.
U:n
Adds no check box for the output variable.
266 Reference
Example
2.
Click the Edit X-Function in Code Builder button to open this X-Function in Code Builder. Copy the following code into the body of the main function, OptionStringU. vector vv; vv.Data(1,10,1); if( xx ) // to check if output xx variable { xx = vv; } if( yy ) // to check if output yy variable { yy = vv; } zz = vv;
3.
Put the following code into the OptionStringU_event1 function, which will get the check box status of the output variables. Then click the Compile button foreach(TreeNode subnode in trGetN.Children) { string strVarName = subnode.tagName; int nUStatus, nOutput; .
Reference
267

// to check if is output variable if((subnode.GetAttribute(STR_XF_VAR_IO_ATTRIB, nOutput) && IO_OUTPUT == nOutput)) { // check Output check box status if(subnode.GetAttribute(STR_ATTRIB_DYNACONTROL_USE_CHECK, nUStatus)) { switch(nUStatus) { case 1: box.\n" , strVarName); break; case 0: box.\n" , strVarName); break; } } else { printf("%s variable NOT Output check box.\n", strVarName); } } } 4. Run OptionStringU -d; in the Command window, keep the default settings of the dialog, and click the OK button. This will create a new worksheet with two columns, and the check box status of each output variable will be printed in the Command window. printf("%s variable has Output unchecked check printf("%s variable has Output checked check
19.3.20 V - Specifying Control to be Invisible

Specifies whether a variable is visible or not in the X-Function dialog.
V:0
The variable will be invisible in the dialog.
V:1
The variable will be visible in the dialog.
268
Reference
V:2
The variable will be invisible when using Labtalk script.
19.3.21 Z - Adding Check Box to Set Editable or Disable for Variable Control
Adds a check box beside an input variable to specify whether it is editable or not. The syntax is Z:State|Label|Behavior.
State: 0 or 1, to specify the status of the check box. Label: label for the check box. If both Label and Behavior are unspecified, the label is Auto by default. Behavior: 0, the variable is always editable, no matter whether the check box is checked or not. 1, if checked, the input variable is disabled. 2, if unchecked, the input variable is disabled. Create a new X-Function with the name and variables shown in the following image. Then click the Save button to save the X-Function in <User Files Folder>\X-Functions\OC Guide\ (if this folder does not exist, create it).
Example
1.
2.
Click the Edit X-Function in Code Builder button to open this X-Function in Code Builder. Copy the following code into the OptionStringZ_event1 function, which will get the check box status of the int Type variable. Then click the Compile button . TreeNode trInt = trGetN.nn; int nAutoType = octree_get_auto_support(&trInt); switch(nAutoType)
Reference
269

{ case -1: out_str("Auto check box of int Type control is unchecked"); break; case 0: out_str("No auto check box for int Type control"); break; case 1: out_str("Auto check box of int Type control is checked"); break; } 3. Run OptionString -d; in the Command window, and a dialog like the one in the image below will open. Change the status of the TestOK check box, and a message about the status of this check box will output in the Command window.
270
Reference
Index
A Analysis Functions 125 Array, One-Dimensional 100 Array, Two-Dimensionals 5, 101 Auto Update 234, 238 B Baseline, Create 137 Baseline, Remove 137 Binning, 2D 131 break Statement 1312 Building by Script 43 Building on Startup 43 Building Origin C File with Project 42 Building Origin C Files under Workspace System Folder 42 Building with Dependent Files 43 Building, Handle Compiling and Linking Error 43 C C# Features 1 C++ Features 1 Caret Character 8 char Type 5 Class Hierarchy 245 Classes, Analysis Category 19 Classes, Application Communication Category 19 Classes, Data Types Category 20 Classes, Origin Objects Category 22 Classes, Predefined 15, 19 Classes, System Category 32 Classes, User Defined 15, 171, 174 Classes, User Interface Controls Category 32 Classes, Utility Category 36 Clone Page 54 Code Builder 1, 40 Collections 247 Color Palette 6 Color, Auto Color 7 Color, Check as RGB Value or Palette Index 7 Color, Convert RGB to Origin Color 7 Color, Extract Single Color from RGB 7 Column Designation 58 Column Properties 58 Column, Access Data Buffer 68 Column, Data Format 59 Column, Data SubFormat 59 Column, Get/Set Numeric Data 59 Column, Get/Set String Data 60 Column, Setting Value by Formula 61 COM 242 Comments Label 60 Comparison Operators 8 Compile and Link Source Files 41 Compiler, Generate Encrypted File 38 Compiler, Generate Pre-processed File 38 Compiler, Type of Pre-processed File 38 Complex Variable 101 Complex, Imaginary Component 5 Complex, Real Component 5 continue Statement 13 Contour Graph, Get/Set Z Levels of Colormap 88 Contour Graph, Set Line Style 88 Convolution 135 Copy Format 86 Correlation 135 Correlation Coefficient 131 Curve Fitting 132 D Data Comparison 72 Data Range, from Graph 103 Data Range, from Matrix 102 Data Range, from Worksheet 102 Data Reader 161 Data Selector 103 Data Types 5
271
Database 147 Database, SQL 242 DataPlot, Bar/Column 80 DataPlot, Contour 81 DataPlot, Error Bar 80 DataPlot, Image Type 82 DataRange, Construct XYZ Range 72 Dataset 59 Date Time, Convert String to Julian Date 106 Date Time, Custom Date Format 106 Date Time, Get Current Date Time 105 Debugging 44 Debugging, ASSERT Macro 44 Debugging, Breakpoints 44 Debugging, Using Macros 45 Descriptive Statistics 130 Develper Kit 165 Dialog Builder 165 Dialog, Add Button Controls 165 Dialog, Event Functions 177 Dialog, Open 178 Dialog, Resource DLL Created by Origin Dialog AppWizard 166 Dialog, Resource DLL Created by Visual Studio 2008 166 Dialog, Resource DLL Created by Win32 Dynamic-Link Library 166 Dialog, Use Resource DLL in Origin C 169 Differentiation 130 double Type 5 Duplicate Window 54 E Exception Handling 16 Exponentiate Operator 8 Export Data from Matrix to ASCII File 124 Export Data from Worksheet to ASCII File 123 Export Data to Database 148 Export Graph to Image File 123 Export Image from Matrix to Image File 124 External Application, Database 242 External Application, Execute Matlab Command 242 External Application, MS Word 242 External DLL, Access 241
272 Index
External Resources, Access 241 Extrapolation 12625 F FDF File 134 FFT 135 FFT Filtering 135 File Open Dialog 157 File SaveAs Dialog 157 File, Object File( .OCB) 38 File, Preprocessed File( .OP) 38 File, Workspace File( .OCW) 39 float Type 5 Flow Control Statements 10 Folder, Add Sub Folder 108 Folder, Get Path 108 Folder, Get Sub Folders 108 Folder, Move Window 109 Font, Convert from Index to DWORD 89 for Statement 12 foreach Statement 13, 110 Fortran 241 Frequency Count 130 Functions, Adding for Set Values Dialog F(x) menu 50 Functions, Calling Origin C Function from Script 46 Functions, Control LabTalk Access 47 Functions, Execution 3, 40, 46 Functions, List All LabTalk Callable Origin C Functions 47 Functions, Pass LabTalk Variable to Origin C by Value 47 Functions, Precedence Rules for the Same Name Functions 49 Functions, Predefined 14 Functions, User-defined 14 G Gadget Tool 210 GetN Apply Button 160 GetN Branch Macros 159 GetN Button Controls 158 GetN Data Selector Control 103 GetN Event Handling 160 GetN Graph Preview Dialog 194 GetN Option of Controls 159
Index
GetN Simple Dialog 158 GetN, Image Dialog 198 GETN_TREE Macro 158 goto Statement 13 Graph Browser 231 Graph Layer, Add Bar/Column Plot 80 Graph Layer, Add Data Marker 84 Graph Layer, Add Matrix Image Plot 82 Graph Layer, Add Worksheet Table 97 Graph Layer, Add YErr Data Plot 80 Graph Layer, Axis Label Properties 78 Graph Layer, Axis Properties 77 Graph Layer, Axis Tick Label Properties 79 Graph Layer, Axis Ticks Properties 79 Graph Layer, Dimension 93 Graph Layer, Double-Y Axes 82 Graph Layer, Fill Color 76 Graph Layer, Get Active Data Plot 80 Graph Layer, Get Format 76 Graph Layer, Get Format on DataPlot 85 Graph Layer, Grid Lines 77 Graph Layer, Legend 97 Graph Layer, List all Data Plots 248 Graph Layer, Refresh 78 Graph Layer, Rescale 80 Graph Layer, Scale Settings 77 Graph Layer, Set Color on DataPlot 85 Graph Layer, Set Data Marker 84 Graph Layer, Set Format on Grouping Plot 87 Graph Layer, Set Format on Line Plot 86 Graph Layer, Set Format on Scatter Plot 87 Graph Layer, Set Ticks and TickLabels as Auto Color 83 Graph Layer, Show Additional Lines 76 Graph Layer, Show/Hide Axis 78 Graph Object, Add Curve Arrow 94 Graph Object, Add Line 94 Graph Object, Add Rectangle 93 Graph Object, Add Text Label 93 Graph Object, Attach Property 95 Graph Object, Create 93 Graph Object, Disable Moving and Selection 96 Graph Object, General Properties 95 Graph Object, Position 95
Index
Graph Object, Programming Control 96 Graph Object, Set Line Position 94 Graph Page, Add Layer 91 Graph Page, Arrange Layers 83 Graph Page, Attach a User Defined Dialog to It 162 Graph Page, Background 76 Graph Page, Create 75 Graph Page, Delete 75 Graph Page, Get Format 76 Graph Page, Get the Existing Window 75 Graph Page, Gradient Control 76 Graph Page, Layer Arrangement 90, 91 Graph Page, Linking Layers 93 Graph Page, Move Layer 91 Graph Page, Plotting Separated Data in Multiple Layers 90 Graph Page, Rename 75 Graph Page, Resize Layer 92 Graph Page, Swap Layers 92 Graph Preview Dialog 171 Gridding 72 H Hello World Function 1 Hidden Page, Create 53 I if Statement 1110 if-else Statement 1110 Import ASCII Data File to Matrixsheet 118 Import ASCII Data File to Worksheet 117 Import Data with Filter 119 Import File, Get Storage Tree by Name 113 Import Image into Matrix 120 Import Image into Worksheet Cell 121 Import Image to Graph 121 Importing from a Database 147 Importing, Get Info from Image File 120 Improve OC Execution Speed 68 Input String 156 Integer Type 5 Integral, Multi-dimension 129 Integral, with Multiple Parameters 127 Integral, with One Integration Variable 126 Integration 126
273
L LabTalk Object, Use in Origin C LabTalk Script, Execution in Origin C LabTalk Variable, Get/Set in Origin C Language Basic Features Language Fundamentals Layer, Alignment Legend Update List Labtalk Callable Functions Logical Operators Long Name Label loop Statement LT_execute LT_get_str LT_get_var LT_set_str LT_set_var M Matlab matrix Matrix Book, Create Matrix Object, Add/Delete Matrix Object, Set Value By Formula Matrix Sheet, Data Format Matrix Sheet, Data/Image View Matrix Sheet, Get by Name Matrix Sheet, Get/Set Labels for XY Matrix Sheet, Get/Set Labels for Z Matrix Sheet, Set Internal Data Type Matrix, Dimension Matrix, Dot Multiply Matrix, Multiply with Constant Message Box Message Map Missing Values Modal Dialog Modulus Operator Multiple XY Datasets N NAG Callback Functions NAG Error Structure NAG Functions NAG Get Data From Origin NAG Header Files NAG, Memory Free
274
152 152 151 1 5 92 97 47 9 60 12 152 152 151 152 151 242 5 53 62 66 63 62 61 63 64 63 62 65 65 156 174 99 169 8 238 140 140 139 141 139 141
Index
NANUM 99 New a Source File 40 NLFit, Get Number of Parameters 132 NLFit, Set Parameter Values 133 NLFitSession Class 132 NLFitSession, Get Fitted Data 134 NLFitSession, Get Number of Iterations 134 NLFitSession, Run Code to Initialize Parameter Values 133 NLFitSession, Set Fitting Data 133 NLFitSession, Set Fitting Function 132 NLFitSession, Share Parameters 133 Nonlinear Fitting 132 Normality Test 132 Normalize 125 Numeric, Convert to String 100 Numeric, Data Comparison Data 99 O Operation, List All 114 Operators 7 Origin Object, Copy Format 86 Output to Notes Window 146 Output to Report Sheet 146 Output to Results Log 145 Output to Script Window 145 oxf File 223 P Package Files 51 Page, Get Name 75 Page, Get Path 109 Palette 6 Parameters Label 60 Path Browser Dialog 158 Peaks, Find 138 Peaks, Fit 139 Peaks, Integrate 139 Peaks, Verify Peaks by Minimum Height 138 Pick Data Points 161 Plotting, from Matrix 81 Plotting, from Virtual Matrix 66 Plotting, from Worksheet 79 Pointer 5 pragma 241 Progress Box 156
Index
Project, Add Tree Variable 111 Project, Append 107 Project, Get Active Folder 108 Project, Get the Active Layer 109 Project, Get the Active Page 109 Project, Get the Existing Window 109 Project, Get the Names of All Tree Variables 111 Project, Get Tree Variable 111 Project, List all Graph Pages 248 Project, List all Matrixbooks 248 Project, List All Operations 114 Project, List All Range Variables 110 Project, List all Workbooks 248 Project, Loop the Existing Windows 110 Project, Modified Flag 107 Project, New 107 Project, Open 107 Project, Root Folder 108 PropertyPage 169 R Recalculation 234 Remainder 8 Report Sheet, Get Result Tree 113 Report Sheet, Get the Specified Result 114 Report with Auto Update 238 RGB 7 S Screen Reader 161 Select Data Range 234 Share Code 50 short Type 5 Signal Processing 135 Smoothing 135 Source File, New 174 SQL 147 SQLite 149 Statistics Functions 130 STFT 135 string 5 String Array 5 String, Convert to Complex 104 String, Define Variables 103 String, Extract File Name from Full Path 105
Index
switch Statement 11 T Template 53, 75 Theme File 86 throw Statement 16 TreeNode 101 try-catch Statement 16 U Units Label 60 User Defined Labels 60 User File Folder 105 User Interface 155 V vector 5 void Return Type 5 W Wait Cursor 155 Wavelet 135 while/do-while Statement 12 Wizard Dialog 203 Wizard Dialog, Add Steps Map 17069 WizardSheet 169 Workbook, Activate a Sheet 54 Workbook, Create 53 Workbook, Delete One Sheet 54 Workbook, Get Name 54 Workbook, Get Page from Layer 55 Worksheet, Add Tree Variable 111 Worksheet, Alignment 56 Worksheet, Check If Hierarchy 114 Worksheet, Column Labels 60 Worksheet, Compare Data 71 Worksheet, Convert Data To Matrixsheet72 Worksheet, Delete All Columns 68 Worksheet, Embedded Graph 69 Worksheet, Extract Data 70 Worksheet, Find Data 70 Worksheet, Get Data from Specified Data Range 67 Worksheet, Get Sheet Name 55 Worksheet, Get the Names of All Storages 112 Worksheet, Get Tree Variable 112 Worksheet, Highlight Selection 70
275
Worksheet, Masking Data 70 Worksheet, Merge All Sheets 55 Worksheet, Merge Cells 57 Worksheet, Put Text to Cell 56 Worksheet, Set Color for the Selected Range 71 Worksheet, Set Column Width by LabTalk Command 152 Worksheet, Set Dimension 58 Worksheet, Set Display Range 68 Worksheet, Sorting Data 69 Workspace, Load Files 41 Workspace, Project Folder 39 Workspace, System Folder 40 Workspace, Temporary Folder 40 Workspace, User Folder 40 X XF_THROW macros 194 XF_TRACE macro 194 XF_WARN macros 193 XFBase Class 226 X-Function Builder 181, 183 X-Function Custom Dialog 201 X-Function Data Plot Selection Filter 253 X-Function Dialog Controls 185 X-Function Dialog Theme 186 X-Function Option Strings 186 X-Function Tree View 18786 X-Function Variable 183 X-Function Variable Type 184 X-Function Wizard Dialog 203 X-Function, Add Documentation 223 X-Function, Add Internal Functions 188 X-Function, Add to Origin Menu 220 X-Function, Auto Compile Dependent Files 188 X-Function, before_execute 189, 208 X-Function, Branch Check Box 269 X-Function, Browser Dialog Options 252 X-Function, Coding in Code Builder 187, 19695, 199 X-Function, Control Labtalk Accessing 182 X-Function, Create 181 X-Function, Data Selector Default Selection 265 X-Function, Dialog Combo Box 265
276 Index
X-Function, Dialog Numeric Display Format 253 X-Function, Dialog Theme 266 X-Function, Disable Auto Assigning Column Designatioin 252 X-Function, Disable Undo 252 X-Function, Display Error Message on Dialog 193 X-Function, Editable/Disable Control 263 X-Function, Error Handling 19392 X-Function, Event Handler Functions in Image Dialog 192 X-Function, Event Handler Functions in Preview Dialog 192 X-Function, Event Handling Functions 189 X-Function, event1 191, 223 X-Function, Execution 183, 201 X-Function, Execution Control 253 X-Function, Execution from Script 225 X-Function, Execution in Origin C 226 X-Function, Execution with Theme 210 X-Function, Execution with Wizard Dialog 210 X-Function, Execution without Dialog 225 X-Function, Fitting 239 X-Function, Grouping Controls on Dialog 255 X-Function, Handle Runtime Error 194 X-Function, Image Dialog Init Event Function 200199 X-Function, Image Dialog OnChange Event Function 200 X-Function, Include Header Files 188 X-Function, Input Range Control 258 X-Function, Main Function 189 X-Function, make_tree 190, 212 X-Function, Missing Data Display Format 252 X-Function, Multi-lines Text Control 262 X-Function, New Hidden Page 252 X-Function, Output Error Message 193 X-Function, Output Warning Message 193 X-Function, Recalculate Mode 249 X-Function, Set Control as Invisible 268 X-Function, Set Output as Optional 266 X-Function, Set Output Object Action 262
Index
X-Function, Set Output Range Dimension 252 X-Function, Set Parameters in Origin C 226 X-Function, Set Result Tables Shown Style 256 X-Function, Set the Default Name for Output Object 262
X-Function, Specify the Source of Output Variable 254 X-Function, Statistics 235 X-Function, Update Control Value on Dialog 230 X-Functions 181 XOR Operator 10
Index
277

Origin C Programming Guide

Uploaded by

Origin C Programming Guide

Uploaded by

Origin C Programming Guide

2.3 Statement Flow Control ................................................................................................10

2.4 Functions ......................................................................................................................14

2.5 Classes .........................................................................................................................15

2.6 Error and Exception Handling.......................................................................................16

3 Predefined Classes .............................................................................................. 19

4 Creating and Using Origin C Code ..................................................................... 37

Origin C Programming Guide

4.2 Compiling, Linking and Loading................................................................................... 41

4.4 Using Compiled Functions........................................................................................... 46

4.5 Distributing Origin C Code ........................................................................................... 50

5 Workbooks and Matrixbooks.............................................................................. 53

5.4 Matrices ....................................................................................................................... 62

5.5 Virtual Matrix ................................................................................................................ 66 5.6 Data Manipulation ........................................................................................................ 67

5.7 Data Transformation.....................................................................................................72

6.2 Adding Data Plots.........................................................................................................79

6.3 Customizing Data Plots ................................................................................................84

6.4 Managing Layers ..........................................................................................................90

Origin C Programming Guide

6.5 Creating and Accessing Graphical Objects ................................................................. 93

7 Working with Data ............................................................................................... 99

7.2 String Data ................................................................................................................. 103

7.3 Date and Time Data................................................................................................... 105

8.2 Managing Folders ...................................................................................................... 108

8.3 Accessing Pages ....................................................................................................... 109

8.4 Accessing Metadata ...................................................................................................110

8.5 Accessing Operations.................................................................................................114

9.2 Importing Images........................................................................................................120

10 Exporting ............................................................................................................ 123

11 Analysis and Applications ................................................................................ 125

11.2 Statistics .....................................................................................................................130

11.3 Curve Fitting ...............................................................................................................132

11.4 Signal Processing.......................................................................................................135

11.5 Peaks and Baseline....................................................................................................137

11.6 Using NAG Functions ................................................................................................ 139

12 Output Objects................................................................................................... 145

13 Accessing Database.......................................................................................... 147

14 Accessing LabTalk ............................................................................................ 151

15 User Interface..................................................................................................... 155

15.3 GetN Dialogs.............................................................................................................. 158

16 Dialog Builder .................................................................................................... 165

16.2 Wizard Dialog............................................................................................................. 169 16.3 Graph Preview Dialog................................................................................................ 171

16.4 Splitter Dialog .............................................................................................................173

17 X-Functions ........................................................................................................ 181

17.2 Customizing an X-Function ........................................................................................220

17.3 Using X-Functions ......................................................................................................225

17.4 X-Function Examples .................................................................................................227

18 Accessing External Resources......................................................................... 241

1.1 Basic Features

1.2 Hello World Tutorial

1.2 Hello World Tutorial

1.2 Hello World Tutorial

1.2 Hello World Tutorial

2.1 Data Types and Variables

Origin C Composite Data Types

2.1 Data Types and Variables

DWORD dwColor = SYSCOLOR_ORANGE;

Dividing an integer by another integer will give an integer result.

2.2.3 Logical Operators

Consider the following two examples:

2.3 Statement Flow Control

2.3 Statement Flow Control

2.3.1 The if Statement

// when bRet is false

The switch Statement

2.3 Statement Flow Control

The for Statement

The while Statement

2.3.6 The foreach Statement

The foreach Statement

2.5.1 Origin Defined Classes

Origin C functions can also be called from LabTalk.

Origin Defined Classes

User Defined Classes

2.6 Error and Exception Handling

2.6 Error and Exception Handling

Source (.c, .cpp, *.h)