Plot Pack Manual Version 2.1.2

The Standard in Industrial Automation and Scientific Components for Real-Time Applications

Version 2.1.2.0 [08/26/02 2:27 PM] Plot Pack Manual

This page intentionally left blank

ii Iocomp Components – Plot Pack Manual Copyright

Author Patrick Carroll Technical Reviewer Todd Oster Proofreader Cyrus Edson

No part of this publication may be reproduced, stored in a retrieval system or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from the publisher. Except for the limited warranty as described in the End User License Agreement, the information and material contained in this book are provided “As Is” without warranty of any kind, express or implied, including without limitation any warranty concerning the accuracy, adequacy, or completeness of such information or material or the results to be obtained from using such information or material contained within this manual or documentation. Neither Iocomp Software nor the author shall be responsible for any claims attributable to errors, omissions, or other inaccuracies in the information or material contained in this book, and in no event shall Iocomp Software or the author be liable for direct, indirect, special, incidental, or consequential damages arising out of the use of such information or material. Some states do not allow limitations of duration of any implied warranty, so the above limitations may not apply to you.

Trademarks Iocomp and the Iocomp Logo are registered trademarks of Iocomp Software Incorporated. Microsoft, Visual Basic, Visual C++, Visual FoxPro, Windows, Microsoft Office, and ActiveX are trademarks or registered trademarks of Microsoft Corporation. Borland, Delphi, Kylix, C++ Builder, VCL, and CLX are trademarks or registered trademarks of the Borland Corporation. Linux is a registered trademark of Linus Torvalds. All other names, products, or marks are trademarks or registered trademarks of their respective companies.

Initial Printing 03/2001

Manufactured in the United States of America

Iocomp Components – Plot Pack Manual iii Table of Contents

Table of Contents

PLOT PACK MANUAL...... I

TABLE OF CONTENTS...... IV

CHAPTER 1 - INTRODUCTION...... 1 SAMPLE CODE CONVENTIONS...... 1 VISUAL C++ SPECIAL COMPILER NOTE...... 1 BORLAND DELPHI, KYLIX, AND C++ BUILDER SPECIAL COMPILER NOTE ...... 2 COMPONENT NAMING CONVENTIONS ...... 3 SOURCE CODE UNIT NAMING CONVENTIONS ...... 3 CHAPTER 2 - DECIDING WHICH COMPONENT TO USE...... 4 IPLOT ...... 5 Properties (ActiveX) ...... 6 Properties (VCL/CLX)...... 6 Depreciated Properties...... 6 Methods (ActiveX) ...... 6 Methods (VCL/CLX)...... 8 Depreciated Methods (VCL)...... 8 Events...... 9 IXYPLOT ...... 9 Properties (ActiveX) ...... 10 Properties (VCL/CLX)...... 11 Depreciated Properties...... 11 Methods (ActiveX) ...... 12 Methods (VCL/CLX)...... 13 Depreciated Methods (VCL)...... 13 Events...... 14 CHAPTER 3 - OVERALL THEORY...... 15 GENERIC EXAMPLE:...... 16 SPECIFIC EXAMPLES: ...... 16 PLOT OBJECTS ...... 17 Plot Object Index...... 17 Plot Object Name...... 18 Get Plot Object Index By Name...... 18 Get Plot Object Name by Index ...... 18 CHAPTER 4 - AXES ...... 19 SPAN ...... 20 MIN AND MAX ...... 20 ROTATED AXES...... 20 LABEL FORMATS...... 21 REVERSE SCALES...... 21 iv Iocomp Components – Plot Pack Manual Table of Contents

SCALE TYPES ...... 22 Linear ...... 22 Logarithmic Base 10...... 22 LABELSEPARATION...... 22 LABELSMARGIN...... 23 LABELSMINLENGTH ...... 23 LABELSMINLENGTHAUTOADJUST ...... 24 STACKINGENDSMARGIN...... 24 TRACKING...... 25 USER INTERFACE ...... 25 CUSTOMIZING TICK LABELS ...... 26 Visual Basic Example ...... 26 Visual C++ Example...... 27 PROPERTIES ...... 28 METHODS...... 28 EVENTS...... 28 CHAPTER 5 - DATA VIEW...... 29 CHANNELS ...... 29 ANNOTATIONS ...... 30 DATA CURSORS ...... 30 LIMITS ...... 31 LAYER ORDER ...... 31 GRID LINES ...... 32 Major and Minor Lines ...... 32 Extended Grid-Line Customization ...... 33 STACKED AXES AND GRID LINES...... 34 PROPERTIES ...... 37 METHODS...... 37 EVENTS...... 37 CHAPTER 6 - CHANNELS...... 38 TRACE LINES ...... 39 DATA MARKERS ...... 40 INDIVIDUAL DATA MARKERS ...... 40 CHANNEL FILL...... 41 TRACKING...... 41 RING BUFFER ...... 42 BAR SUPPORT ...... 42 DATA STYLES ...... 43 DIGITAL CHANNEL SUPPORT ...... 45 ASYNCHRONOUS AND SYNCHRONOUS DATA ...... 45 CHANNEL DATA LOGGING ...... 46 FASTDRAW ...... 46 CHANNEL TYPES...... 46 iPlot Component Channel: iPlotChannel: ...... 47 iXYPlot Component Channel: iPlotXYChannel:...... 48 PROPERTIES ...... 50 METHODS...... 50

Iocomp Components – Plot Pack Manual v Table of Contents

EVENTS...... 50 CHAPTER 7 - LEGEND ...... 51 PREDEFINED COLUMNS...... 51 TURN ON AND OFF COLUMN TITLES...... 52 PROPERTIES ...... 53 METHODS...... 53 EVENTS...... 53 CHAPTER 8 - TOOLBAR...... 54 CONFIGURE INDIVIDUAL BUTTONS ...... 54 IMPLEMENTED EXTERNALLY ...... 55 BUTTON DESCRIPTIONS ...... 55 PROPERTIES ...... 56 METHODS...... 56 EVENTS...... 56 CHAPTER 9 - ANNOTATIONS ...... 57 ANNOTATION TYPES ...... 58 Text:...... 58 Text Rectangle:...... 58 Line:...... 58 Rectangle:...... 59 LineX: ...... 59 LineY: ...... 60 Bitmap Image: ...... 60 Bitmap Image List...... 61 ANNOTATION REFERENCE RELATIONSHIPS...... 62 DataView Reference ...... 62 Channel Reference...... 62 XDataViewYChannel Reference...... 63 XChannelYDataView Reference...... 63 MOVEABLE ANNOTATIONS ...... 63 RESIZABLE ANNOTATIONS...... 63 HOW TO ADD ANNOTATIONS ...... 63 Text Annotation Example...... 64 Line Annotation Example ...... 64 Rectangle Annotation Example ...... 64 LineX Example...... 64 LineY Example...... 64 HOW TO REMOVE ANNOTATIONS...... 65 ANNOTATION CLICK EVENT...... 65 PROPERTIES ...... 65 METHODS...... 65 EVENTS...... 65 CHAPTER 10 - DATA CURSORS...... 66 CURSOR TYPES ...... 66 Value X-Y Cursor [ValueXY] ...... 66 Value X Cursor [ValueX] ...... 67 vi Iocomp Components – Plot Pack Manual Table of Contents

Value Y Cursor [ValueY] ...... 67 Period Cursor [DeltaX] ...... 68 Peak-Peak Cursor [DeltaY] ...... 68 Frequency Cursor [InverseDeltaX] ...... 69 ADDING AND REMOVING CURSORS...... 69 DATA CURSOR EXAMPLE...... 70 ACCESSING INDIVIDUAL CURSOR PROPERTIES...... 70 Controlling User Popup Menu ...... 70 Controlling Hints...... 70 Controlling Cursor Pointers...... 70 IPLOT COMPONENT SPECIFIC NOTES...... 70 IXYPLOT COMPONENT SPECIFIC NOTES...... 71 CURSOR EVENTS...... 71 PROPERTIES ...... 71 METHODS...... 72 EVENTS...... 72 CHAPTER 11 - LIMITS...... 73 LINEX...... 73 LINEY...... 74 BANDX ...... 74 BANDY ...... 75 POLYBANDX ...... 75 POLYBANDY ...... 76 ADDING AND REMOVING LIMITS...... 76 SINGLE-LINE LIMIT EXAMPLES...... 76 BAND LIMIT EXAMPLES ...... 77 POLY BAND LIMIT EXAMPLES ...... 77 PROPERTIES ...... 78 METHODS...... 78 EVENTS...... 78 CHAPTER 12 - LABELS ...... 79 HOW TO ADD LABELS...... 79 HORIZONTAL LABEL EXAMPLE...... 80 VERTICAL LABEL EXAMPLE...... 80 HOW TO REMOVE LABELS ...... 80 PROPERTIES ...... 80 METHODS...... 80 EVENTS...... 80 CHAPTER 13 - VISUAL LAYOUT MANAGER...... 81 TUTORIAL ...... 82 How to Move Objects ...... 82 Resizing Plot Objects...... 83 How to Stack Axes ...... 84 Rotating X and Y-Axes...... 86 CHAPTER 14 - ADDING DATA ...... 87 ADDXY ...... 87

Iocomp Components – Plot Pack Manual vii Table of Contents

Complete AddXY Example...... 87 Visual Basic...... 87 Visual C++ [Disp Interface]...... 88 Visual C++ [High-Speed iDispatch Interface] ...... 88 C++ Builder ...... 89 Delphi/Kylix ...... 89 Internet Explorer...... 90 Special ActiveX Example:...... 91 Visual Basic...... 91 Visual C++ [Disp Interface]...... 92 Visual C++ [High-Speed iDispatch Interface] ...... 92 Internet Explorer...... 93 OTHER DATA ADDING METHODS ...... 93 AddYElapsedSeconds ...... 94 AddYElapsedTime...... 94 AddYNow ...... 94 AddYArray ...... 94 AddXYArray...... 95 AddXYArrays ...... 95 AddEmpty...... 95 AddXNull [iPlotX component only] ...... 95 AddNull [iXYPlotX component only] ...... 96 MODIFYING/READING DATA...... 96 Visual Basic...... 96 Visual C++...... 96 Borland Delphi ...... 96 Borland C++ Builder...... 97 RUNNING Y-VALUE MIN, MAX, AND MEAN...... 97 EMPTY AND NULL DATA POINTS ...... 98 CHAPTER 15 - CARTESIAN AXES...... 99 MASTER CARTESIAN AXES ...... 99 CHILD CARTESIAN AXES...... 100 CHAPTER 16 - TRANSLATION...... 102

CHAPTER 17 - NULL DATA HANDLING...... 104 ADDING A NULL Y DATA POINT AT A SPECIFIC X DATA POINT (IPLOT ONLY) ...... 104 ADDING A NULL X & Y DATA (IXYPLOT ONLY)...... 104 SETTING A NULL Y DATA POINT AT A SPECIFIC X DATA POINT...... 104 FULL SOURCE EXAMPLE ...... 105 Example: Visual Basic...... 105 Example: Visual C++ [Disp Interface] ...... 106 Example: Visual C++ [High-Speed iDispatch Interface] ...... 106 Example: Delphi/Kylix ...... 107 Example: C++ Builder...... 108 Example: VB.Net ...... 108 Example: C#.NET...... 109 Example: Internet Explorer...... 109 CHAPTER 18 - USER INTERFACE CONTROL...... 110 THE BUILT-IN TOOLBAR ...... 110 viii Iocomp Components – Plot Pack Manual Table of Contents

SCROLLABLE AND ZOOMABLE AXES ...... 110 ZOOMING TOOLS...... 111 SELECT TOOL...... 111 CURSOR TOOL...... 111 CONTEXT SENSITIVE RIGHT-CLICK MENUS (POPUP MENUS)...... 111 Axis Object...... 111 DataView Object...... 112 Toolbar Object...... 112 Legend Object...... 112 DataCursor Object ...... 112 RUNTIME PROPERTY EDITOR ...... 112 Right-Click on Plot Object ...... 112 Toolbar Runtime Property Editor Button...... 113 Preventing or Disabling UI Interaction ...... 113 Disabling All UI Interaction on a Plot Object ...... 113 Disabling Popup Menu on a Plot Object or On Entire Component...... 114 SPECIAL USER EVENTS ...... 114 CHAPTER 19 - TRACKING...... 116 TRACKING STYLES...... 117 TRACKING ALIGN FIRST STYLES...... 119 Min...... 119 Max ...... 119 Auto...... 120 None [All Axis Default] ...... 120 TRACKING SCROLL COMPRESS MAX ...... 120 ENABLING AND DISABLING TRACKING ...... 121 Channel Tracking Properties ...... 121 Axis Tracking Properties...... 121 User Interaction...... 121 MANUAL TRACKING ...... 121 CHAPTER 20 - INTERPOLATION...... 122 NONE ...... 122 STRAIGHT LINE...... 123 CUBIC SPLINE ...... 123 POLYNOMIAL ...... 124 RATIONAL...... 124 DIFFERENTIAL...... 125 CHAPTER 21 - LOADING AND SAVING DATA ...... 126 DATA FORMATS ...... 126 SaveDataToFile...... 126 LoadDataFromFile...... 127 SavePropertiesToFile ...... 127 LoadPropertiesFromFile...... 128 SaveAnnotationsToFile...... 128 LoadAnnotationsFromFile ...... 128 DATA LOG FORMATS ...... 128 LogFileName ...... 128

Iocomp Components – Plot Pack Manual ix Table of Contents

LogBufferSize ...... 129 LogActivate...... 129 LogDeactivate...... 129 ADDDATAARRAY EXAMPLE...... 130 IMAGE FORMATS...... 130 CHAPTER 22 - GRAPHICAL EXPORT...... 131 ENHANCED META FILE FORMAT...... 131 BITMAP ...... 131 JPEG ...... 131 PNG...... 131 CLIPBOARD TRANSFER METHOD ...... 132 GETBYTESJPEG METHOD...... 132 CHAPTER 23 - PRINTING...... 133 PRINTING OPTIONS...... 133 Page Orientation ...... 133 Printer Dialog ...... 133 Printer Document Name...... 133 Margins...... 133 SIMPLE CHART PRINT ...... 134 USING WITH EXTERNAL REPORTING PACKAGES OR CUSTOM CODE ...... 134 Clipboard Transfer...... 134 IPictureDisp Object Transfer ...... 135 PRINTING TIPS...... 135 CHAPTER 24 - PLOT PACK EVENTS...... 136 PRINTING EVENTS...... 136 OnBeforePrint ...... 136 OnAfterPrint ...... 136 DATAVIEW OBJECT EVENTS...... 137 OnClickAnnotation ...... 137 OnClickDataPoint ...... 137 OnLimitLine1PositionChange...... 138 OnLimitLine2PositionChange...... 138 DATA CURSOR OBJECT EVENTS...... 139 OnDataCursorChange ...... 139 AXIS OBJECT EVENTS ...... 139 OnXAxisCustomizeLabel ...... 139 OnXAxisMinChange ...... 140 OnXAxisSpanChange...... 141 OnYAxisCustomizeLabel ...... 141 OnYAxisMinChange ...... 142 OnYAxisSpanChange...... 143 PLOT OBJECT FOCUS EVENTS ...... 143 OnGotFocusChannel...... 143 OnGotFocusDataCursor ...... 144 OnGotFocusLegend...... 144 OnGotFocusXAxis ...... 145

x Iocomp Components – Plot Pack Manual Table of Contents

OnGotFocusYAxis ...... 145 OnLostFocusChannel ...... 145 OnLostFocusDataCursor ...... 146 OnLostFocusDataView...... 146 OnLostFocusLegend...... 146 OnLostFocusXAxis ...... 147 OnLostFocusYAxis ...... 147 STANDARD EVENTS ...... 147 OnMouseDown ...... 147 OnMouseMove...... 148 OnMouseUp...... 148 CHAPTER 25 - AUTOSCALE AND AUTOLABEL ...... 149 1-2-5 RULE ...... 149 LINEAR SCALE ...... 149 DATE/TIME SCALE...... 149 PRICE32NDS SCALE...... 150 LOG10 SCALE ...... 151 MODIFYING THE 1-2-5 RULE ...... 151 DesiredIncrement ...... 151 Desired Start...... 152 Tracking...... 153 CHAPTER 26 - VISUAL C++ DISP VS. IDISPATCH INTERFACE ...... 154 DISP INTERFACE [LATE BINDING, CLASS WIZARD DEFAULT] ...... 154 Disp Coding Example...... 154 iDispatch Interface [Early Binding, High-Speed]...... 155 CHAPTER 27 - USING WITH DATABASE ...... 157 INTEGRATED TEXT FILE SAVING AND LOADING ...... 157 SIMPLE X AND Y DATA ...... 157 TIME/DATE X AND Y DATA...... 157 CHAPTER 28 - LAYOUT CONTROL THROUGH CODE ...... 159 LAYOUT MANAGER ...... 159 LAYOUT OBJECT ZORDER ...... 159 LAYOUT OBJECT STARTPERCENT AND STOPPERCENT ...... 160 Horizontal Layout Object ...... 160 Vertical Layout Object...... 161 DATAVIEWZVERT AND DATAVIEWZHORZ...... 161 DataViewZVert ...... 161 DataViewZHorz...... 162 TOOLBAR AND LEGEND ...... 162 X AND Y-AXES...... 162 StackingEndsMargin ...... 162 Layout Object Horizontal ...... 163 PLOT COMPONENT OUTER MARGIN...... 164 FULL LAYOUT THROUGH CODE EAMPLE ...... 164 CHAPTER 29 - PERFORMANCE TUNING ...... 171

Iocomp Components – Plot Pack Manual xi Table of Contents

COMPONENT SIZE ...... 171 FRAME RATE...... 171 AutoFrameRate...... 171 UpdateFrameRate ...... 172 BeginUpdate ...... 173 EndUpdate...... 173 SYSTEM HARDWARE...... 173 Processor...... 173 Memory...... 173 Video Card...... 173 SPECIAL ACTIVEX EXAMPLE:...... 174 Visual Basic...... 174 Visual C++ [Disp Interface]...... 174 Visual C++ [High-Speed iDispatch Interface]...... 175 Internet Explorer ...... 176 VB.NET...... 176 C#.NET ...... 177 CHAPTER 30 - MEMORY UTILIZATION...... 178 DATA STORAGE ...... 178 MEMORY USAGE CALCULATIONS [STANDARD DATA SET STYLE]...... 179 2GB APPLICATION RAM BARRIER ...... 179 CHANNEL MEMORY STATISTICS ...... 180 DataPointSize...... 180 MaxDataPoints...... 180 Capacity...... 180 MemoryUsed...... 180 RESOURCE MEMORY VS. RAM MEMORY...... 180 RAM Memory...... 180 Resource Memory...... 181 RING BUFFER ...... 181 CHAPTER 31 - IMPLEMENTING TOOLBAR EXTERNALLY ...... 183

CHAPTER 32 - IMPLEMENTING LEGEND EXTERNALLY...... 185 CHANNEL NAME LISTING...... 185 CHANNEL TRACE LINE STYLE AND COLOR LISTING ...... 186 CHANNEL MARKER STYLE AND COLOR LISTING ...... 187 CHANNEL ASSOCIATED X-AXIS...... 188 CHANNEL ASSOCIATED Y-AXIS...... 188 CHANNEL CURRENT X/Y COORDINATE...... 188 CHAPTER 33 - ASP (ACTIVE SERVER PAGES)...... 190 MICROSOFT IIS SERVER ASP PAGE (VBSCRIPT) ...... 190 CHAPTER 34 - INTERNET EXPLORER (CLIENT SIDE) ...... 191 CREATING THE PLOT PACK ACTIVEX OBJECT IN YOUR WEB PAGE ...... 191 INSTALLING THE PLOT PACK ACTIVEX CONTROL ON THE CLIENT ...... 192 LICENSING THE PLOT PACK ACTIVEX CONTROL ...... 192 ACCESSING THE PLOT PACK ACTIVEX CONTROL FROM VBSCRIPT ...... 193 xii Iocomp Components – Plot Pack Manual Table of Contents

AddXY Example...... 193 FULL SOURCE EXAMPLE ...... 194 CHAPTER 35 - OPC (OLE FOR PROCESS CONTROL) ...... 195 IOCOMP COMPONENT OPC ADD-ON FEATURES ...... 195 DEVELOPER BENEFITS ...... 195 OPC TUTORIAL ...... 196 APPENDIX A - PLOT PACK PROPERTY EDITORS...... 200 CONTROL GENERAL...... 200 CONTROL TITLE ...... 202 CONTROL PRINT...... 203 CONTROL HINTS ...... 204 CONTROL IMAGES...... 204 CONTROL FILE I/O...... 205 TRANSLATION...... 206 ANNOTATION DEFAULTS ...... 207 VISUAL LAYOUT MANAGER ...... 208 CHANNELS GENERAL...... 209 CHANNEL TRACE ...... 211 INTERPOLATION ...... 212 CHANNELS MARKERS ...... 213 CHANNELS BAR ...... 215 CHANNELS FILL ...... 216 CHANNELS DIGITAL...... 217 CHANNEL FILE I/O...... 218 CHANNEL OPC ...... 219 CURSORS GENERAL ...... 220 CURSORS HINT...... 222 CURSORS MENU ITEMS ...... 223 LIMITS GENERAL ...... 224 LABELS ...... 228 AXES GENERAL...... 229 AXES TITLE...... 231 AXES LABELS ...... 232 AXES TRACKING ...... 234 AXES CURSOR...... 235 AXES SCROLL ...... 236 AXES SCALE ...... 237 AXES CARTESIAN...... 238 LEGEND ...... 239 TOOLBAR...... 241 DATA VIEW GENERAL ...... 243 DATA VIEW GRID LINES ...... 244 APPENDIX B - GETTING STARTED WITH MICROSOFT VISUAL BASIC 6.0 ...... 246 INTRODUCTION ...... 246 ADDING COMPONENT TO PROJECT...... 246 ADDING COMPONENT TO FORM...... 247

Iocomp Components – Plot Pack Manual xiii Table of Contents

CUSTOM PROPERTY EDITOR ...... 248 ACCESSING COMPONENT THROUGH CODE...... 249 Setting Properties and Calling Methods ...... 249 Events...... 249 APPENDIX C - GETTING STARTED WITH MICROSOFT VISUAL C++ 6.0 (DISP INTERFACE)...... 252 INTRODUCTION ...... 252 ADDING COMPONENT TO PROJECT ...... 252 ADDING COMPONENT TO FORM...... 255 CUSTOM PROPERTY EDITOR ...... 258 ACCESSING COMPONENT THROUGH CODE...... 259 Adding Member Variable ...... 259 Setting Properties and Calling Methods ...... 260 Fonts: Using the Disp (Late Binding, Slow-Speed, Member Variable) Interface...... 261 Event Handlers ...... 261 APPENDIX D - GETTING STARTED WITH MICROSOFT VISUAL C++ 6.0 (IDISPATCH) 264 INTRODUCTION ...... 264 ADDING COMPONENT TO PROJECT ...... 264 ADDING COMPONENT TO FORM...... 264 CUSTOM PROPERTY EDITOR ...... 265 ACCESSING COMPONENT THROUGH CODE...... 267 Adding CCOM Pointer Variable...... 267 Setting Properties and Calling Methods ...... 268 Fonts: Using the iDispatch (Early Binding, High-Speed) Interface ...... 269 Event Handlers ...... 269 APPENDIX E - GETTING STARTED WITH MICROSOFT .NET (C#.NET/VB.NET)...... 272 INTRODUCTION ...... 272 Visual Basic.NET Syntax...... 272 C#.NET Syntax ...... 272 ADDING COMPONENT TO PROJECT ...... 272 ADDING COMPONENT TO FORM...... 273 CUSTOM PROPERTY EDITOR ...... 275 ACCESSING COMPONENT THROUGH CODE...... 276 Setting Properties and Calling Methods ...... 276 Event Handlers ...... 277 APPENDIX F - GETTING STARTED WITH BORLAND DELPHI & KYLIX (PASCAL) ...... 279 INTRODUCTION ...... 279 ADDING COMPONENT TO DELPHI/KYLIX IDE...... 279 ADDING COMPONENT TO FORM...... 279 CUSTOM PROPERTY EDITOR ...... 280 ACCESSING COMPONENT THROUGH CODE...... 281 Setting Properties and Calling Methods ...... 281 Event Handlers ...... 282 APPENDIX G - GETTING STARTED WITH BORLAND C++ BUILDER & KYLIX (C++).... 284 INTRODUCTION ...... 284 xiv Iocomp Components – Plot Pack Manual Table of Contents

ADDING COMPONENT TO C++ BUILDER/KYLIX IDE ...... 284 ADDING COMPONENT TO FORM...... 284 CUSTOM PROPERTY EDITOR ...... 285 ACCESSING COMPONENT THROUGH CODE...... 286 Setting Properties and Calling Methods ...... 286 Event Handlers ...... 287 APPENDIX H - ACTIVEX HTML PROPERTIES AND EVENTS...... 289 HTML PAGE IMPORTANT NOTES ...... 289 Boolean Values:...... 289 Double Values: ...... 289 PROPERTIES ...... 289 VBSCRIPT EVENTS ...... 297 JAVASCRIPT EVENTS...... 300 LPK FILE TUTORIAL...... 307 Web Page ActiveX Licensing: What is an LPK File?...... 307 Steps to create an LPK File...... 307 STEPS TO INTEGRATE THE LPK FILE INTO YOUR WEB PAGE...... 310 APPENDIX I -- WHAT IS DATETIME FORMAT?...... 311 DATETIME FORMAT STRING ...... 312 Month (M)...... 312 Day (d)...... 313 Year (y) ...... 313 Special ...... 313 APPENDIX J -- FREQUENTLY ASKED QUESTIONS...... 314

INDEX...... 317

Iocomp Components – Plot Pack Manual xv Table of Contents

This page intentionally left blank

xvi Iocomp Components – Plot Pack Manual Chapter 1 - Introduction

Chapter 1 - Introduction

Welcome to the Iocomp Plot Pack Manual. This manual, in addition to our help files and example source code projects, provides a full suite of documentation for understanding how our Plot Pack components are constructed, operate, and are used to enhance the applications you develop.

The Plot Pack currently includes two components: the iPlot component which is designed for y = f(x) (Continuously Incrementing or Decrementing X Values) type data and the iXYPlot component which is designed for data that does not follow this equation and may have X-Values in any order.

This manual is divided into several chapters covering different aspects of the Plot Components. The components have been designed entirely on an object oriented approach, making them well suited for both simple and complex charting applications while leaving themselves open to the addition of many features and enhancements. The following icons are used throughout the manual for emphasis…

Important Note: ! Useful Tip: Reminder:

Sample Code Conventions All simple examples are formatted using a Visual Basic-like syntax. Depending upon your compiler, the syntax of accessing plot objects and properties may differ. Some specific examples for each major development environment are provided, formatted for that specific compiler. As an example, to access the Title property for the first X-Axis you would use the following syntax for these major development environments…

Microsoft Visual Basic/VBA/VBScript iPlotX1.XAxis(0).Title = "Sample Title 1"

Microsoft VB.NET AxiPlotX1.get_XAxis(0).Title = "Sample Title 1"

Microsoft C#.NET axiPlotX1.get_XAxis(0).Title = "Sample Title 1";

Microsoft Visual C++ (Disp Interface) m_iPlotX1.GetXAxis(0).SetTitle("Sample Title 1");

Microsoft Visual C++ (iDispatch Interface) m_iPlotX1->XAxis[0]->Title = "Sample Title 1";

Borland Delphi/Kylix iPlot1.XAxis[0].Title := 'Sample Title 1';

Borland C++ Builder iPlot1->XAxis[0]->Title = "Sample Title 1";

Visual C++ Special Compiler Note You will need to include several ActiveX wrapper header files in your include statements to access Plot Component sub objects…

Iocomp Components – Plot Pack Manual 1 Chapter 1 - Introduction

//include the following for iPlotX #include "iplotx.h" #include "iplotchannelx.h"

//include the following for iXYPlotX #include "ixyplotx.h" #include "ixyplotchannelx.h"

//include the following for iPlotX and iXYPlotX #include "iplotaxisx.h" #include "iplotlegendx.h" #include "iplottoolbarx.h" #include "iplotdataviewx.h" #include "iplotannotationx.h" #include "iplotlabelx.h" #include "iplotlimitx.h" #include "iplotdatacursorx.h"

Enumerated types of ActiveX controls are only supported by Visual C++ if you are using the high-speed iDispatch interface to an ActiveX control. Refer to the chapter on Visual C++ Disp vs. iDispatch Interface for more information on using the high-speed iDispatch interface. Refer to the help file for values associated with enumerated properties if you are using the Disp Interface.

Microsoft Visual C++ does not support integration of our help files into the Visual C++ IDE. You can view our help files through one of the following methods…

Click on your START menu button, select Programs, and then Iocomp. In this folder you will find links to our help files for our ActiveX and VCL/CLX components as well as links to release notes, website information, and a link to the directory where our products are installed. Navigate to the folder where you installed our products (generally c:\iocomp\product or c:\program files\iocomp\components). In this folder are our ActiveX and VCL help files which you can open directly as well as release notes, and the actual component binaries and source files.

Download one of the appendices listed in this manual for the ActiveX and VCL help. These appendices contain the same information in the ActiveX and VCL help files, but has been formatted for printing.

Borland Delphi, Kylix, and C++ Builder Special Compiler Note You will need to include the following files to your USE statement to access enumerated types of specific Plot Pack sub-objects that you will be using in your code…

iTypes iPlotAxis iPlotLegend iPlotToolbar iPlotDataView iPlotAnnotation iPlotLabel iPlotLimit iPlotDataCursor

2 Iocomp Components – Plot Pack Manual Chapter 1 - Introduction

Component Naming Conventions This manual covers the ActiveX, VCL, and CLX component versions of our components. Since these three component architectures differ in many ways, the actual class names of these components differ slightly.

If we are talking generically about a component, we will refer to the Plot Components as iPlot and iXYPlot. In the ActiveX version of the components, the actual class names are iPlotX and iXYPlotX. In the VCL and CLX versions, the class names are TiPlot and TiXYPlot.

You can extrapolate this to all of the components produced by Iocomp Software. All VCL and CLX components start with "Ti" and do not end in "X". All ActiveX components start with i and end in "X".

Source Code Unit Naming Conventions The source of our components is written in Borland Delphi for Windows, corresponding to the VCL and CLX versions of our components respectively. The source code is identical between these two component standards, minus some IFDEF differences that you will see in the source. The major difference is in the naming of the Unit files.

All VCL component Unit files start with "i". All CLX component Unit file names are the same with "Q" appended on the front. The class names of the components are still the same. Borland Delphi, C++ Builder, and Kylix can decipher the difference between the VCL and CLX versions due to their inheritance which is dictated by our iInclude.inc file and corresponding IFDEFs.

Iocomp Components – Plot Pack Manual 3 Chapter 2 - Deciding Which Component To Use

Chapter 2 - Deciding Which Component To Use

The Plot Pack includes several different components for your charting applications. Each component has been designed for a particular type of chart.

Feature iPlot iXYPlot Annotations (Text, Line, and Rectangle) Automated Data Logging to Disk Built in Toolbar and Legend Channel Ring Buffers Data Drill Down Data Point Markers Horizontal or Vertical orientation of Axes Intelligent AutoScale of Axes in human readable format (1-2-5 Rule) Linear and Logarithmic Scales OPC Channel Support (OLE for Process Control) Printing, Saving, Picture interface, and CopyToClipBoard Reversible Scales Stackable Scales (See Visual Layout Manager) Unlimited number of Channels Unlimited number of Data Cursors Unlimited number of Limits Unlimited number of X&Y-Axes Value, Prefix, Exponent, and Data/Time Scale Label styles Visual Layout manager (Design-Time and Run-Time) Single-Line and Dual-Line Cursors Data Fill Interpolation (Curve-Fitting) Bar Plot Support Optimized Drawing Routines for Large Data Sets Data Set restricted to y = f(x) Cross-Hair Cursor Out-of order Channel X-Value Data

Table 2.1

The iPlot component is designed to be used with Time-based data on the X-Axis. This means that data points must be added with ever increasing or decreasing X-Values. This assumption by our component allows us to dramatically speed up the drawing of data to the screen. If you must add data in decreasing X-Value or "random" X-Value order, use the iXYPlot component instead.

The following ActiveX, VCL and CLX components are included with the Plot Pack…

4 Iocomp Components – Plot Pack Manual Chapter 2 - Deciding Which Component To Use iPlot The iPlot component has been designed for y = f(x) based graphs (which comprises the vast majority of charts that are generated). Supports data with a continuously incrementing or decrementing X-Value. Typical uses are for Strip Chart, Chart Recorder, or Scrolling Chart types of plotting applications. This is the chart that should be used for almost all plotting applications.

FIGURE 2.1 A sample iPlot Component with various Channel formats

The Plot component also supports data fill (see Channel #1 example above) to a specified reference line, bars drawn to a specified reference line, as well as specialized AddData functions for time based data.

Drawing routines have been optimized in this component to provide high-speed access and drawing (paint and scroll) operations. This is made possible due to the fact that the data sets need to follow the for y = f(x) function.

The iPlot main interface contains several properties, methods, and events that affect the overall appearance and operation of the entire component.

Iocomp Components – Plot Pack Manual 5 Chapter 2 - Deciding Which Component To Use

Properties (ActiveX) AnnotationDefaultBrushColor AnnotationDefaultBrushStlye AnnotationDefaultFontColor AnnotationDefaultFont AnnotationDefaultPenColor AnnotationDefaultPenStlye AnnotationDefaultPenWidth Annotation AutoFrameRate BackGroundColor BackGroundPicture BorderStyle Channel ClipAnnotationsToAxes ComponentHandle CopyToClipBoardFormat DataCursor DataView DataViewZHorz DataViewZVert EditorFormStyle HintsFontColor HintsFont HintsHidePause HintsPause HintsShow Labels Legend Limit LogBufferSize LogFileName LoggingActive OptionSaveAllProperties OuterMarginBottom OuterMarginLeft OuterMarginRight OuterMarginTop PrintDocumentName PrintMarginBottom PrintMarginLeft PrintMarginRight PrintMarginTop PrintOrientation PrintShowDialog ToolBar UpdateFrameRate UserCanAddRemoveChannels UserCanEditObjects XAxis XYAxesReverse YAxis

Properties (VCL/CLX) AnnotationDefaultBrushColor AnnotationDefaultBrushStlye AnnotationDefaultFont AnnotationDefaultPenColor AnnotationDefaultPenStlye AnnotationDefaultPenWidth Annotation AutoFrameRate BackGroundColor BorderStyle Channel ClipAnnotationsToAxes CopyToClipBoardFormat DataCursor DataView DataViewZHorz DataViewZVert EditorFormStyle GetTranslationOriginalString GetTranslationReplacementString HintsFont HintsHidePause HintsPause HintsShow Labels Legend Limit LoadTranslationsFromFile LogBufferSize LogFileName LoggingActive OPCItem OptionSaveAllProperties OuterMarginBottom OuterMarginLeft OuterMarginRight OuterMarginTop PrintDocumentName PrintMarginBottom PrintMarginLeft PrintMarginRight PrintMarginTop PrintOrientation PrintShowDialog SaveTranslationsToFile ToolBar UpdateFrameRate UserCanAddRemoveChannels UserCanEditObjects XAxis XYAxesReverse YAxis Refer to the Plot Object Sections for properties of the Plot Objects. These properties are only for the main plot interface. Refer to Appendix C & D for more detailed information about the iPlot main interface properties.

Depreciated Properties The following properties have been depreciated due to the inclusion of newer functionality provided. These properties are provided for backward compatibility only. TitleFontColor TitleFont TitleMargin TitleText TitleVisible

Methods (ActiveX) AddAnnotation AddChannel AddDataArray AddDataCursor AddDataView AddLabel AddLegend AddLimit AddToolBar AddTranslation AddXAxis AddYAxis AnnotationCount BeginUpdate ChannelCount

6 Iocomp Components – Plot Pack Manual Chapter 2 - Deciding Which Component To Use

ClearAllData CopyToClipBoard DataCursorCount DataViewCount DeleteAnnotation DeleteChannel DeleteDataCursor DeleteDataView DeleteLabel DeleteLegend DeleteLimit DeleteToolBar DeleteTranslation DeleteXAxis DeleteYAxis DisableAllTracking DisableLayoutManager EnableAllTracking EnableLayoutManager EndUpdate GetBytesJPEG GetChannelIndexByName GetNow GetOPCItemAutoConnect GetOPCItemComputerName GetOPCItemItemName GetOPCItemPropertyName GetOPCItemServerName GetOPCItemUpdateRate GetSnapShotPicture GetXAxisIndexByName GetYAxisIndexByName LabelCount LegendCount LimitCount LoadAnnotationsFromFile LoadDataFromFile LoadPropertiesFromFile Lock LogActivate LogDeactivate OPCAddItem OPCItemActivateSend OPCItemActivate OPCItemCount OPCItemDeactivate OPCItemLoaded OPCRemoveAllItems PrintChart RemoveAllAnnotations RemoveAllChannels RemoveAllDataCursors RemoveAllDataViews RemoveAllLabels RemoveAllLegends RemoveAllLimits RemoveAllToolBars RemoveAllTranslations RemoveAllXAxes RemoveAllYAxes RepaintAll SaveAnnotationsToFile SaveDataToFile SaveImageToBitmap SaveImageToJPEG SaveImageToMetaFile SavePropertiesToFile Save SetOPCItemAutoConnect SetOPCItemComputerName SetOPCItemItemName SetOPCItemPropertyName SetOPCItemServerName SetOPCItemUpdateRate ToolBarCount TranslationCount Unlock XAxisCount YAxisCount

Refer to the Plot Object Sections for methods of the Plot Objects. These methods are only for the main plot interface. Refer to the Appendix for more detailed information about the iPlot main interface methods.

Iocomp Components – Plot Pack Manual 7 Chapter 2 - Deciding Which Component To Use

Methods (VCL/CLX) AddAnnotation AddChannel AddDataArray AddDataCursor AddDataView AddLabel AddLegend AddLimit AddToolBar AddTranslation AddXAxis AddYAxis AnnotationCount BeginUpdate ChannelCount ClearAllData CopyToClipBoard DataCursorCount DataViewCount DeleteAnnotation DeleteChannel DeleteDataCursor DeleteDataView DeleteLabel DeleteLegend DeleteLimit DeleteToolBar DeleteTranslation DeleteXAxis DeleteYAxis DisableAllTracking DisableLayoutManager EnableAllTracking EnableLayoutManager EndUpdate GetBytesJPEG GetChannelIndexByName GetNow GetSnapShotPicture GetXAxisIndexByName GetYAxisIndexByName LabelCount LegendCount LimitCount LoadAnnotationsFromFile LoadDataFromFile LoadPropertiesFromFile Lock LogActivate LogDeactivate OPCAddItem OPCRemoveAllItems PrintChart RemoveAllAnnotations RemoveAllChannels RemoveAllDataCursors RemoveAllDataViews RemoveAllLabels RemoveAllLegends RemoveAllLimits RemoveAllToolBars RemoveAllTranslations RemoveAllXAxes RemoveAllYAxes RepaintAll SaveAnnotationsToFile SaveDataToFile SaveImageToBitmap SaveImageToJPEG SaveImageToMetaFile SavePropertiesToFile Save ToolBarCount TranslationCount Unlock XAxisCount YAxisCount Refer to the Plot Object Sections for methods of the Plot Objects. These methods are only for the main plot interface. Refer to the Appendix for more detailed information about the iPlot main interface methods.

Depreciated Methods (VCL) The following properties have been depreciated due to the inclusion of newer functionality provided. These properties are provided for backward compatibility only. Please use the OPCItem property instead to access these features. OPC does not function under our CLX version of the components. GetOPCItemAutoConnect GetOPCItemComputerName GetOPCItemItemName GetOPCItemPropertyName GetOPCItemServerName GetOPCItemUpdateRate OPCItemActivate OPCItemCount OPCItemDeactivate OPCItemLoaded OPCItemUpdateResume OPCItemUpdateSuspend SetOPCItemAutoConnect SetOPCItemComputerName SetOPCItemItemName SetOPCItemPropertyName SetOPCItemServerName SetOPCItemUpdateRate

8 Iocomp Components – Plot Pack Manual Chapter 2 - Deciding Which Component To Use

Events OnAfterPrint OnAnnotationCoordinatesChangeFinished OnAnnotationCoordinatesChange OnBeforePrint OnClickAnnotation OnClickDataPoint OnDataCursorChange OnGotFocusAnnotation OnGotFocusChannel OnGotFocusDataCursor OnGotFocusDataView OnGotFocusLegend OnGotFocusXAxis OnGotFocusYAxis OnKeyDown OnKeyPress OnKeyUp OnLimitLine1PositionChange OnLimitLine2PositionChange OnLostFocusAnnotation OnLostFocusChannel OnLostFocusDataCursor OnLostFocusDataView OnLostFocusLegend OnLostFocusXAxis OnLostFocusYAxis OnMouseDown OnMouseMove OnMouseUp OnPopupMenuAnnotation OnPopupMenuChannel OnPopupMenuDataCursor OnPopupMenuDataView OnPopupMenuLegend OnPopupMenuLimit OnPopupMenuXAxis OnPopupMenuYAxis OnXAxisCustomizeLabel OnXAxisMinChange OnXAxisSpanChange OnYAxisCustomizeLabel OnYAxisMinChange OnYAxisSpanChange Refer to the Appendix for more detailed information about the iPlot main interface events. iXYPlot The iXYPlot component has been designed for graphs that don’t have continuously incrementing x-values, and are not based on a y = f(x) function. Since we don’t restrict that the graph be based on a y = f(x) function, there are some features that are not included or are different between the iXYPlot component and the iPlot component such as…

Drawing Routines: the drawing routines in the iXYPlot component are not as optimized as in the iPlot component since each channel is not based on y = f(x). For large data sets, performance may be sluggish. Use the iPlot component whenever possible if your data is based on y = f(x) and you are using large data sets.

Channel Fill: Since there can be any number of Y values for a particular X value, it is not possible to fill below or above a curve that can fit to these data points.

Interpolation: Since there can be any number of Y values for a particular X value, it is not possible to perform interpolation or curve fitting functions to the channel data.

Speed: Special speed enhancements are included in the iPlot component that require the data added to it to be based on y = f(x) . The iXYPlot component will lose some speed improvements with large data sets.

The iXYPlot main interface contains several properties, methods, and events that affect the overall appearance and operation of the entire component.

Iocomp Components – Plot Pack Manual 9 Chapter 2 - Deciding Which Component To Use

FIGURE 2.2 A sample iXYPlot Component showing two channels.

Properties (ActiveX) AnnotationDefaultBrushColor AnnotationDefaultBrushStlye AnnotationDefaultFontColor AnnotationDefaultFont AnnotationDefaultPenColor AnnotationDefaultPenStlye AnnotationDefaultPenWidth Annotation AutoFrameRate BackGroundColor BackGroundPicture BorderStyle Channel ClipAnnotationsToAxes ComponentHandle CopyToClipBoardFormat DataCursor DataView DataViewZHorz DataViewZVert EditorFormStyle HintsFontColor HintsFont HintsHidePause HintsPause HintsShow Labels Legend Limit LogBufferSize LogFileName Logging Active OptionSaveAllProperties OuterMarginBottom OuterMarginLeft OuterMarginRight OuterMarginTop PrintDocumentName PrintMarginBottom PrintMarginLeft PrintMarginRight PrintMarginTop PrintOrientation PrintShowDialog ToolBar UpdateFrameRate UserCanAddRemoveChannels UserCanEditObjects XAxis XYAxesReverse YAxis

10 Iocomp Components – Plot Pack Manual Chapter 2 - Deciding Which Component To Use

Properties (VCL/CLX) AnnotationDefaultBrushColor AnnotationDefaultBrushStlye AnnotationDefaultFont AnnotationDefaultPenColor AnnotationDefaultPenStlye AnnotationDefaultPenWidth Annotation AutoFrameRate BackGroundColor BorderStyle Channel ClipAnnotationsToAxes CopyToClipBoardFormat DataCursor DataView DataViewZHorz DataViewZVert Depreciated Properties EditorFormStyle GetTranslationOriginalString GetTranslationReplacementString HintsFont HintsHidePause HintsPause HintsShow Labels Legend Limit LoadTranslationsFromFile LogBufferSize LogFileName LoggingActive OPCItem OptionSaveAllProperties OuterMarginBottom OuterMarginLeft OuterMarginRight OuterMarginTop PrintDocumentName PrintMarginBottom PrintMarginLeft PrintMarginRight PrintMarginTop PrintOrientation PrintShowDialog SaveTranslationsToFile ToolBar UpdateFrameRate UserCanAddRemoveChannels UserCanEditObjects XAxis XYAxesReverse YAxis Refer to the Appendix for more detailed information about the iXYPlot main interface properties.

Iocomp Components – Plot Pack Manual 11 Chapter 2 - Deciding Which Component To Use

Methods (ActiveX) AddAnnotation AddChannel AddDataArray AddDataCursor AddDataView AddLabel AddLegend AddLimit AddNull AddToolBar AddTranslation AddXAxis AddYAxis AnnotationCount BeginUpdate ChannelCount ClearAllData CopyToClipBoard DataCursorCount DataViewCount DeleteAllTranslations DeleteAnnotation DeleteChannel DeleteDataCursor DeleteDataView DeleteLabel DeleteLegend DeleteLimit DeleteToolBar DeleteTranslation DeleteXAxis DeleteYAxis DisableAllTracking DisableLayoutManager EnableAllTracking EnableLayoutManager EndUpdate GetBytesJPEG GetChannelIndexByName GetNow GetSnapShotPicture GetTranslationOriginalString GetTranslationReplacementString GetXAxisIndexByName GetYAxisIndexByName iPaintToDC LabelCount LegendCount LimitCount LimitCount LoadAnnotationsFromFile LoadDataFromFile LoadPropertiesFromFile LoadTranslationsFromFile Lock LogActivate LogDeactivate PrintChart RemoveAllAnnotations RemoveAllChannels RemoveAllDataCursors RemoveAllDataViews RemoveAllLabels RemoveAllLegends RemoveAllLimits RemoveAllToolBars RemoveAllXAxes RemoveAllYAxes RepaintAll SaveAnnotationsToFile SaveDataToFile SaveImageToBitmap SaveImageToJPEG SaveImageToMetaFile Save SavePropertiesToFile SaveTranslationsToFile ToolBarCount TranslationCount Unlock XAxisCount YAxisCount

12 Iocomp Components – Plot Pack Manual Chapter 2 - Deciding Which Component To Use

Iocomp Components – Plot Pack Manual 13 Chapter 2 - Deciding Which Component To Use

14 Iocomp Components – Plot Pack Manual Chapter 3 - Overall Theory

Chapter 3 - Overall Theory

The Plot Pack components are object-oriented components that are designed for very high speed plotting and ease of use by both the application programmer and application user.

The hierarchy of the Plot Pack components is shared among the many different types of plotting components that we offer. This allows programmers to use or Plot Components interchangeably since most of the properties, objects, and methods are common. There are several objects that make up the base for our Plot Components, and the hierarchy is as follows…

FIGURE 3.1 Plot Pack Hierarchy iPlot or iXYPlot

Plot Objects

DataView iPlotAxis ToolBar Channel Legend Annotation DataCursor Limit Label Translation

XAxis YAxis

There can be any number of Plot Objects associated with each Plot Component. This gives rise to our Multiple Axes, Multiple Annotations, Multiple Labels, and Multiple Channel features. To access one of these Plot Component sub-objects, you would need to specify the index value of that object. For example…

The iPlotAxis object is the ancestor of the iPlotXAxis and iPlotYAxis (Shown above as XAxis and YAxis) objects. It should not be accessed directly. To work with the X and/or Y-Axis, use the X-Axis and Y-Axis interfaces instead.

Iocomp Components – Plot Pack Manual 15 Chapter 3 - Overall Theory

Generic Example: iComponent1.PlotObject(0).Property = Value

Specific Examples: Visual Basic/VBA/VBScript iComponentX1.DataView(0).GridShow = TRUE iComponentX1.XAxis(0).Min = 100 iComponentX1.YAxis(0).Min = 100 iComponentX1.Channel(0).Name = "Channel 1" iComponentX1.Legend(0).Visible = TRUE iComponentX1.ToolBar(0).ShowEditButton = FALSE iComponentX1.Annotation(0).Text = "Sample Annotation" iComponentX1.DataCursor(0).Style = ipcsDeltaX iComponentX1.Limit(0).XAxisName = "X-Axis 1" iComponentX1.Labels(0).Caption = "Chart Y vs. Time"

VB.NET AxiComponentX1.get_DataView(0).GridShow = True AxiComponentX1.get_XAxis(0).Min = 100 AxiComponentX1.get_YAxis(0).Min = 100 AxiComponentX1.get_Channel(0).Name = "Channel 1" AxiComponentX1.get_Legend(0).Visible = True AxiComponentX1.get_ToolBar(0).ShowEditButton = False AxiComponentX1.get_Annotation(0).Text = "Sample Annotation" AxiComponentX1.get_DataCursor(0).Style = iPlotLibrary.TxiPlotDataCursorStyle.ipcsDeltaX AxiComponentX1.get_Limit(0).XAxisName = "X-Axis 1" AxiComponentX1.get_Labels(0).Caption = "Chart Y vs. Time"

Visual C++ (Disp Interface) m_iComponentX1.GetDataView(0).SetGridShow(TRUE); m_iComponentX1.GetXAxis(0).SetMin(100); m_iComponentX1.GetYAxis(0).SetMin(100); m_iComponentX1.GetChannel(0).SetName("Channel 1"); m_iComponentX1.GetLegend(0).SetVisible(TRUE); m_iComponentX1.GetToolBar(0).SetShowEditButton(FALSE); m_iComponentX1.GetAnnotation(0).SetText("Sample Annotation"); m_iComponentX1.GetDataCursor(0).SetStyle(3); //ipcsDeltaX m_iComponentX1.GetLimit(0).SetXAxisName("X-Axis 1"); m_iComponentX1.GetLabels(0).SetCaption("Chart Y vs. Time");

Visual C++ (iDispatch Interface) iComponentX1->DataView[0]->GridShow = TRUE; iComponentX1->XAxis[0]->Min = 100; iComponentX1->YAxis[0]->Min = 100; iComponentX1->Channel[0]->Name = "Channel 1"; iComponentX1->Legend[0]->Visible = TRUE; iComponentX1->ToolBar[0]->ShowEditButton = FALSE; iComponentX1->Annotation[0]->Text = "Sample Annotation"; iComponentX1->DataCursor[0]->Style = ipcsDeltaX; iComponentX1->Limit[0]->XAxisName = "X-Axis 1"; iComponentX1->Labels[0]->Caption = "Chart Y vs. Time";

16 Iocomp Components – Plot Pack Manual Chapter 3 - Overall Theory

C#.NET axiComponentX1.get_DataView(0).GridShow = true; axiComponentX1.get_XAxis(0).Min = 100; axiComponentX1.get_YAxis(0).Min = 100; axiComponentX1.get_Channel(0).Name = "Channel 1"; axiComponentX1.get_Legend(0).Visible = true; axiComponentX1.get_ToolBar(0).ShowEditButton = false; axiComponentX1.get_Annotation(0).Text = "Sample Annotation"; axiComponentX1.get_DataCursor(0).Style = iPlotLibrary.TxiPlotDataCursorStyle.ipcsDeltaX; axiComponentX1.get_Limit(0).XAxisName = "X-Axis 1"; axiComponentX1.get_Labels(0).Caption = "Chart Y vs. Time";

C++ Builder iComponent1->DataView[0]->GridShow = TRUE; iComponent1->XAxis[0]->Min = 100; iComponent1->YAxis[0]->Min = 100; iComponent1->Channel[0]->Name = "Channel 1"; iComponent1->Legend[0]->Visible = TRUE; iComponent1->ToolBar[0]->ShowEditButton = FALSE; iComponent1->Annotation[0]->Text = "Sample Annotation"; iComponent1->DataCursor[0]->Style = ipcsDeltaX; iComponent1->Limit[0]->XAxisName = "X-Axis 1"; iComponent1->Labels[0]->Caption = "Chart Y vs. Time";

Delphi/Kylix iComponent1.DataView[0].GridShow := TRUE; iComponent1.XAxis[0].Min := 100; iComponent1.YAxis[0].Min := 100; iComponent1.Channel[0].Name := 'Channel 1'; iComponent1.Legend[0].Visible := TRUE; iComponent1.ToolBar[0].ShowEditButton := FALSE; iComponent1.Annotation[0].Text := 'Sample Annotation'; iComponent1.DataCursor[0].Style := ipcsDeltaX; iComponent1.Limit[0].XAxisName := 'X-Axis 1'; iComponent1.Labels[0].Caption := "Chart Y vs. Time";

The index values are all zero based, meaning the first object’s index is 0, the second is 1, the third is 2, and so on. Currently only one Data View, one Legend, and one Toolbar object is supported at this time and is left open for future expansion. The Axes object is not ! accessed directly. Access the X-Axis and Y-Axis objects through the individual X-Axis and Y-Axis object interfaces.

Plot Objects As shown above, the plot component is made up of many sub objects, referred to in this manual as plot objects. Plot Objects allow for the multiple axis, multiple channel, multiple limit, multiple label, and multiple data cursor features of the component by allowing an unlimited number of plot objects. Note that some plot objects currently only support one object of their type, such as the DataView, Legend, and Toolbar, but will be upgraded in the future.

Plot Object Index To access a specific plot object, such as the third channel for example, you need to use the index of that plot object. Note that a plot object indices start at 0…

Iocomp Components – Plot Pack Manual 17 Chapter 3 - Overall Theory

iComponent1.Channel(2).Property = Value iComponent1.Channel(2).Procedure

Plot Object Name All plot objects have a unique index value that is generated when they are created. You can also associate a name to a plot object using the Name starting property of each plot object.

Each plot object is referenced by its index, but you can also use the name of a plot object when referencing. This allows you to use your own system of referencing multiple channels or axes without using the index values. Also, some properties used by other plot objects to reference other plot objects require the name of the plot object instead of the index.

iComponent1.Channel(0).Procedure iComponent1.Channel(iComponent1.GetChannelIndexByName("Channel 1").Procedure iComponent1.DataCursor(1).ChannelName = "Channel 1" iComponent1.DataCursor(1).ChannelName = iComponent1.Channel(0).Name

Get Plot Object Index By Name You can retrieve the index of a channel or axis by using the following procedure and passing the name of the object…

Index = iComponent1.GetChannelIndexByName("Channel 1") Index = iComponent1.GetXAxisIndexByName("XAxis 1") Index = iComponent1.GetYAxisIndexByName("YAxis 1")

Get Plot Object Name by Index You can retrieve the name of any plot object as follows…

NameString = iComponent1.Channel(Index).Name NameString = iComponent1.XAxis(Index).Name NameString = iComponent1.YAxis(Index).Name NameString = iComponent1.DataCursor(Index).Name NameString = iComponent1.Limit(Index).Name NameString = iComponent1.Labels(Index).Name

If you plan on deleting objects during your program execution, keep in mind that all object indexes above the item you deleted will have their indexes shifted. We recommend that you access subobjects by name… e.g. Index = iComponent1.GetXAxisIndexByName(“Time Axis”) iComponent1.XAxis(Index).Span = 100

18 Iocomp Components – Plot Pack Manual Chapter 4 - Axes

Chapter 4 - Axes

The Axes Plot Object refers to both the X-Axis and Y-Axis Plot Objects. You need to have at least one X-Axis and one Y-Axis to be able to display data in the chart. Every channel that contains data will need to be associated with one X-Axis and one Y-Axis to be able to display data.

Many of the operations of a chart are handled through the axes. The axis object not only provides a visual display of the X-Axis and Y-Axis scales, but are dynamic in that they allow the user to scroll the plot data that is displayed, zoom in and out, and otherwise have complete control over the data displayed in the chart even while you are adding data in real-time! The Axes also have built-in scrolling and scaling capabilities that make implementing a very professional chart very easy. This automated scrolling and scaling is referred to as “Tracking”, and is fully automated. Refer to the chapter entitled “Tracking” for more information on fine-tuning and configuring the tracking features.

FIGURE 4.1 Plot Pack Layout Manager Showing X and Y-Axis Objects

Axis Objects

As you will notice above, there is one X-Axis and actually two Y-Axis. This is useful if you have several data channels where you would like to have a shared, common X-Axis but want to have separate, independent Y-Axis with different scales. The above examples show the Y-Axes stacked. You can also have them oriented side by side if you wish.

To move, resize, and stack axes and other plot objects show above, refer to the chapter entitled “Visual Layout Manager” for more information about using the Visual Layout Manager. If you need to dynamically modify the chart layout at runtime or through your program code, refer to the chapter entitled “Layout Control Through Code”

Iocomp Components – Plot Pack Manual 19 Chapter 4 - Axes

Both the X-Axis and Y-Axis objects support multiple axes, so you can have as many Y-Axes of each type as you wish. Each channel, however, can only be associated with one X and one Y-Axis at any one time.

Below you will find explanations of some of the features supported by both the X and Y-Axes…

Span To set the breadth of values that are displayed on the axis, set the Span property. The Span property specifies the value displayed between the min and maximum values of the axis. For example, if you wish the axis to display 1000 units of data, set the Span property to 1000. If the user scrolls the axis, they are modifying the Min property of the scale, but the span will always be constant. If the user zooms the axis, then the Span value will change according to the ZoomFactor. (i.e. if the user zooms in by a factor of 2, then the Span will be reduced in half from 1000 to 500)

iPlot1.XAxis(0).Span = 1000 iPlot1.YAxis(0).Span = 1000

Min and Max The Min property is used to set the minimum value of the axis that is currently visible. The Max property is read only and is simply a calculation of Max = Min + Span.

iPlot1.Min = 10

'Max is a read-only value MaxValue = iPlot1.Max

...is the same as...

MaxValue = iPlot1.YAxis(0).Min + iPlot1.YAxis(0).Span

The minimum and maximum values that the axes support are as follows... Maximum Value: +1x10300 or +1E300 Minimum Value: -1x10300 or -1E300 Data Precision: 15 places

Rotated Axes The X and Y-Axes can be rotated so that you can plot both horizontally and vertically based upon your application needs. Refer to the Visual Layout Manager chapter for more information or use the XYAxesReverse property from the main plot component interface.

iPlot1.XYAxesReverse = True

You can easily rotate the X and Y-Axes without using code in your application by using the Visual Layout Manager inside of our custom property editor. Refer to the chapter “Visual Layout Manager” for more information on using the Visual Layout Manager.

20 Iocomp Components – Plot Pack Manual Chapter 4 - Axes

Label Formats All Axes support the following label format styles..

Simple Values 198678.567 2578

Exponential Values 2.35E+002 245.34564E-128

Prefix Values 2.2K 3.4M

Date/Time Values 3 Jan 01 5:23pm 01/31/2001

Price32nds 100.231

Price32nds is for use in the Bond and Securities Market. The value is displayed where 23 is in 32nds and 1 is in 256ths. Therefore, in decimal the price above is: 100 +23/32 + 1/256 = 100.72265625. Pass the actual double value of 100.72265625 to display it as Price32nds format as 100.231 to your application end-user.

Reverse Scales All Axes can be reversed. By default, the axes increase in value from left to right or bottom to top. This can be reversed by setting a simple property called ReverseScale.

iPlot1.XAxis(0).ReverseScale = TRUE

Iocomp Components – Plot Pack Manual 21 Chapter 4 - Axes

FIGURE 4.2 Example of Log base 10 and Reversed Scales.

Log Scale

Reversed Scale

Scale Types All Axes support the following scale types…

Linear This is the standard type of scale that most programmers will use in their charts. Scales can range from values between –1x10300 to 1x10300

Logarithmic Base 10 Supports logarithmic base-10 type data. Scales can range from base-10 log values of 1x10-300 to 1x10300.

You can use the ZoomToFit method or the right-click, context-sensitive menu on the axis to zoom all the channel data on that axis to fit the viewable area of the component.

LabelSeparation Use LabelSeparation to get or set the minimum separation between scale labels. LabelSeparation represents the percentage of a character size and is based on the LabelsFont used for the axis. A value of 0.5 is equal to half the size of a character. The actual separation maybe greater due to the AutoScale reducing the number of major ticks to keep the scale labels in a human readable format (1-2-5 Rule).

iPlot1.XAxis(0).LabelSeparation = 2 iPlot1.YAxis(0).LabelSeparation = 2

22 Iocomp Components – Plot Pack Manual Chapter 4 - Axes

FIGURE 4.3 Example showing the how the LabelSeparation property affects label layout.

LabelSeparation

LabelsMargin Use LabelsMargin to get or set the spacing between the major tick and major tick labels. LabelsMargin represents the percentage of a character size and is based on the LabelsFont used for the axis. A value of 0.5 is equal to half the size of a character.

iPlot1.XAxis(0).LabelsMargin = 0.25 iPlot1.YAxis(0).LabelsMargin = 0.25

FIGURE 4.4 Example showing how the LabelsMargin property affects label layout.

LabelsMargin

LabelsMinLength Use LabelsMinLength to get or set the minimum label length used in calculating the number of scale labels (Major Ticks) during AutoScale for horizontal layout objects.

For vertical layout objects, this is used in calculating the minimum width of the layout object. Set this value larger to ensure that the vertical layout object is of a minimum width to accommodate larger values without needing to increase in size.

This property prevents common “oscillations” that occur when the scale flips between, for example, 4 digits at the top of the scale to three digits. To prevent oscillations in this example,

Iocomp Components – Plot Pack Manual 23 Chapter 4 - Axes

set the min length to 4 so that when the top of the scale goes down to three digits, the width is kept at four digits.

AutoScale automatically calculates the number of scale labels based on the LabelsFont, LabelSeparation, and LabelsMinLength properties to ensure labels that are in a human readable format (1-2-5 Rule).

iPlot1.XAxis(0).LabelsMinLength = 5 iPlot1.YAxis(0).LabelsMinLength = 10

All margins use units of characters. This allows the component to dynamically adjust the scales based upon the font used instead of using rigid pixel specifications. A value of 0.25 would be equivalent to ¼ the size (width or height, depending on if the margin relates to a ! horizontal or vertical margin) of a single character from the font being used in the layout object.

FIGURE 4.5 Example showing how the LabelsMinLength property affects label layout.

LabelsMinLength LabelsMinLength

LabelsMinLengthAutoAdjust Use LabelsMinLengthAutoAdjust to specify whether the LabelsMinLength property is automatically adjusted as the minimum required label length increases.

While plotting, or user scrolling/zooming, the actual minimum label length may become greater than the LabelsMinLength property value. This will result it the axis growing in size to accommodate the wider label. If the plotting data or user changes the displayed data causing the label width to vary, it may cause an annoying oscillation of the display plot objects sizes. To prevent this oscillation, set this property to TRUE.

iPlot1.XAxis(0).LabelsMinLengthAutoAdjust = True

StackingEndsMargin Use StackingEndsMargin to get or set the margin at the end of the axis when stacked. StackingEndsMargin represents the percentage of a character size and is based on the LabelFont used for the axis. A value of 0.5 is equal to half the size of a character.

24 Iocomp Components – Plot Pack Manual Chapter 4 - Axes

Note that this feature currently only supports the Axes layout objects. Also note that the stacking margin only applies to layout objects that touch each other and only affects the ends that touch.

In the following example, the first Y-Axis (on the bottom) has a starting percent of 0 and ending percent of 50. The second Y-Axis (on top) has a starting percent of 50 and an ending percent of 100. The Stacking Ends Margin allocates additional space to separate the two stacked axes. The total spacing is 0.5 characters in this example, with the StackingEndsMargin values being cumulative. The StackingEndsMargin will have no effect on the ends of the axes unless they touch another axis.

iPlot1.YAxis(0).StartPercent = 0 iPlot1.YAxis(0).StopPercent = 50 iPlot1.YAxis(0).StackingEndsMargin = 0.25

iPlot1.YAxis(1).StartPercent = 50 iPlot1.YAxis(1).StopPercent = 100 iPlot1.YAxis(1).StackingEndsMargin = 0.25

FIGURE 4.6 Example showing how the StackingEndsMargin property affects label layout.

StackingEndsMargin (0.5 Total = 0.25 + 0.25)

Tracking Tracking refers to the Auto-Scale and Auto-Scroll features of the axes. The axes have the capability to adjust their scales and scroll dynamically at runtime according to several properties that you setup. This makes it easy to implement a chart that looks and functions the way that you would like without complex coding on your part. Refer to the chapter on Tracking for more detailed information.

User Interface By default, the component is setup to allow scrolling and zooming of the axes by your application user. The application user is also able to edit the axis properties either through a popup menu or through the run-time menu button on the toolbar. You can control the user interface by using the Enabled and PopupEnabled properties of the axes to control whether the user can scroll/zoom or be able to bring up the popup menu for the axis to edit properties of that axis.

Iocomp Components – Plot Pack Manual 25 Chapter 4 - Axes

If you are using stacked axes, you may notice that the grid appears to be drawn funny in the DataView area. To fix this, assign the grid to the special value “” so that major ticks for all axes are used to draw the grid lines.

e.g. iComponent.DataView(0).GridYAxisName = “”

Customizing Tick Labels The X and Y Axis scales are automatically configured for you using the AutoScale and AutoLabel (1-2-5 Rule) features of the Plot Components. However, you may wish to customize all or some of the displayed labels with your own text.

For example, let's replace all of the X-Axis labels with their string equivalents. We will use the OnXAxisCustomizeLabel event. This event will fire each time a label above is painted on the X- Axis, passing the Index of the Axis being painted, the current Value of the label being painted in double format, and a pointer to the actual Label in String format. We will modify the Label variable which will then be displayed in place of the original value.

Here is the chart before using the event. We have six labels, one through ten...

FIGURE 4.7 Example output from the Visual C++ Customizing Tick Labels Example.

Visual Basic Example Private Sub iPlotX1_OnXAxisCustomizeLabel(ByVal Index As Long, ByVal Value As Double, ALabel As String) 'Examine the Value passed in the event. This event will fire for each 'label in the Axis (Index of the Axis is passed in the Index parameter), 'passing the Value of the Label in the Value parameter. Modify the 'ALabel string that is passed to change the label to any desired string. Select Case Value Case 0: ALabel = "Zero" Case 2: ALabel = "Two" Case 4: ALabel = "Four" Case 6: ALabel = "Six" Case 8: ALabel = "Eight" Case 10: ALabel = "Ten" End Select End Sub

26 Iocomp Components – Plot Pack Manual Chapter 4 - Axes

Visual C++ Example void CPlotcustomizelabeltestDlg::OnXAxisCustomizeLabel_m_iPlotX1(long Index, double Value, BSTR FAR* ALabel) {

//Examine the Value passed in the event. This event will fire for each //label in the Axis (Index of the Axis is passed in the Index parameter), //passing the Value of the Label in the Value parameter. Modify the //ALabel string that is passed to change the label to any desired string. if (Value == 0) { *ALabel = ::SysAllocString(L"Zero"); }; if (Value == 2) { *ALabel = ::SysAllocString(L"Two"); }; if (Value == 4) { *ALabel = ::SysAllocString(L"Four"); }; if (Value == 6) { *ALabel = ::SysAllocString(L"Six"); }; if (Value == 8) { *ALabel = ::SysAllocString(L"Eight"); }; if (Value == 10) { *ALabel = ::SysAllocString(L"Ten"); }; }

Here is the chart after using the OnXAxisCustomizeLabel event...

FIGURE 4.8 Example output from the Visual Basic Customizing Tick Labels Example.

Warning! Many development languages do not support Case statements even evaluating Double values. The example above uses a Case Statement for simplicity only. If you are ! using any language besides Visual Basic, you will need to use IF statements instead.

Iocomp Components – Plot Pack Manual 27 Chapter 4 - Axes

Properties CartesianChildRefAxisName CartesianChildRefValue CartesianStyle CursorPrecision CursorScaler DateTimeFormat DesiredIncrement DesiredStart Enabled GridLinesVisible Height Horizontal InnerMargin LabelSeparation LabelsFontColor LabelsFont LabelsFormatStyle LabelsMargin LabelsMinLengthAutoAdjust LabelsMinLength LabelsPrecision LabelsPrecisionStyle LabelsVisible MajorLength MasterUIInput Max Min MinorCount MinorLength Name OuterMargin PopupEnabled RestoreValuesOnResume ReverseScale ScaleLinesColor ScaleLineShow ScaleType ScrollMax ScrollMin ScrollMinMaxEnabled Span StackingEndsMargin StartPercent StopPercent TitleFontColor TitleFont Title TitleMargin TitleShow TrackingAlignFirstStyle TrackingEnabled TrackingScrollCompressMax TrackingStyle Visible Width ZOrder Refer to the Appendix for more detailed information about this plot object’s properties.

Methods GetLabelText NewTrackingData PercentToPosition PixelsToPosition PositionToPercent PositionToPixels ResetFirstAlign UpdateResumeValues ValueOnScale Zoom ZoomToFit Refer to the Appendix for more detailed information about this plot object’s methods.

Events OnXAxisCustomizeLabel OnXAxisMinChange OnXAxisSpanChange OnYAxisCustomizeLabel OnYAxisMinChange OnYAxisSpanChange

! All events are on the main component interface and not on the sub-object interface.

28 Iocomp Components – Plot Pack Manual Chapter 5 - Data View

Chapter 5 - Data View

The Data View object is the center-point of the Plot Pack components. This is the area where your data points, trend lines, data cursors, limits, annotations, and Cartesian Axes are displayed. All grid lines are also displayed and configured within this object.

Currently, only one data view is available. The Data View only displays graphical representations of the Channel data. In a future release, a grid data view object will be made available to show numerical representations of your chart data.

FIGURE 5.1 The DataView object where all channels, limits, annotations, and Cartesian axes are drawn.

Data View Object

Channels The channels objects are configured by using the properties and methods of the channel object. To add a channel, execute the AddChannel method from the main interface. To add data or to configure a particular channel, use the index of the channel with the channel sub-interface…

Index = iComponent.AddChannel iComponent.Channel(Index).Procedure iComponent.Channel(Index).Property

Iocomp Components – Plot Pack Manual 29 Chapter 5 - Data View

Here are some specific examples…

iComponent.Channel(0).AddXY(12.3, 14.56432) Value = iComponent.Channel(0).GetXMean iComponent.Channel(0).Color = vbRed iComponent.Channel(0).MarkersStyle = ipmsSquare

Index = iComponent.GetChannelIndexByName("Channel 1") iComponent.Channel(Index).AddXY(12.3, 14.56432) Value = iComponentChannel(Index).GetXMean iComponent.Channel(Index).Color = vbRed iComponent.Channel(Index).MarkersStyle = ipmsSquare

Remember that one channel is added to the component by default when it is created. You can execute the RemoveAllChannels method in your form loading handler if you wish to ! remove all channels and start with a component with no channels.

Refer to the “Channels” Chapter for more information about using the Channels Object

Annotations Annotations are configured by using the properties and methods of the annotation object. To add an annotation, execute the AddAnnotation method from the main interface. To configure a particular annotation, use the index of the annotation with the annotation sub-interface…

Index = iComponent.AddAnnotation iComponent.Annotation(Index).Procedure iComponent.Annotation(Index).Property

Here are some specific examples…

iComponent.Annotation(0).ChannelName = "Channel 1" iComponent.Annotation(0).ChannelName = iComponent.Channel(0).Name iComponent.Annotation(0).BrushColor = vbRed iComponent.Annotation(0).X = 12.5 iComponent.Annotation(0).Y = 37.25 iComponent.Annotation(0).TextRotation = ira180

Refer to the “Annotations” Chapter for more information about using the Annotation Object

Data Cursors Data are configured by using the properties and methods of the DataCursor object. To add a data cursor, execute the AddDataCursor method from the main interface. To configure a particular data cursor, use the index of the data cursor with the data cursor sub-interface…

Index = iComponent.AddDataCursor iComponent.DataCursor(Index).Procedure iComponent.DataCursor(Index).Property

30 Iocomp Components – Plot Pack Manual Chapter 5 - Data View

Here are some specific examples…

iComponent.DataCursor(0).ChannelName = "Channel 1" iComponent.DataCursor(0).ChannelName = iComponent.Channel(0).Name iComponent.DataCursor(0).HintShow = False Value = iComponent.DataCursor(0).ValueX Value = iComponent.DataCursor(0).ValueY iComponent.DataCursor(0).Style = ipcsDeltaX

Remember that one data cursor is added to the component by default when it is created. You can execute the RemoveAllDataCursors method in your form loading handler if you wish to remove all data cursors and start with a component with no data cursors. Data Cursors are initially hidden by default(i.e. their visible properties are set to False). To show the data cursors, click on the data cursor button on the toolbar at runtime, set the Visible ! property of the data cursor to True, or execute the DoButtonClickCursor procedure from the toolbar object.

Refer to the “Data Cursors” Chapter for more information about using the Cursors Object

Limits Limits configured by using the properties and methods of the limit object. To add a limit, execute the AddLimit method from the main interface. To configure a particular limit, use the index of the limit with the annotation sub-interface…

Index = iComponent.AddLimit iComponent.Limit(Index).Procedure iComponent.Limit(Index).Property

Here are some specific examples…

iComponent.Limit(0).XAxisName = "XAxis 1" iComponent.Limit(0).YAxisName = "YAxis 1" iComponent.Limit(0).XAxisName = iComponent.XAxis(0).Name iComponent.Limit(0).YAxisName = iComponent.YAxis(0).Name iComponent.Limit(0).Line1Position = 25.0 iComponent.Limit(0).Line2Position = 37.2 iComponent.Limit(0).Style = iplsBandX

Refer to the “Limits” Chapter for more information about using the Limits Object

Layer Order Objects in the Data View area, such as the grid, channels, limits, annotations, and data cursors are draw in the following order from bottom to top…

• Grid • Channels • Limits • Annotations • Data Cursors

Iocomp Components – Plot Pack Manual 31 Chapter 5 - Data View

In a future release, the ability to change the layer order of the objects in the Data View area will be made available. Access to objects in the Data View area is obtained through the Channel, Annotation, and Limit objects, as the DataView object is just a container for these objects.

Grid Lines The grid lines you see beneath your plotted data in the DataView area can be configured by using the properties listed below or by using the built-in property editor. The grid lines are drawn with respect to a specified set of X and Y-Axis Major and Minor tick marks as well as around the DataView area. You can setup the grid lines to be drawn to any, all, or none of these lines as you desire.

FIGURE 5.2 Example showing DataView Grid Lines.

Grid Lines

Major and Minor Lines The GridLineShowXMajors and GridLineShowYMajors properties control whether a line is drawn with respect to the X and Y Major tick marks on your axis. The drawn lines will scroll with the axis when it is scrolled either by the application user or by the AutoScroll capability of the chart.

Similarly, the GridLineShowXMinors and GridLineShowYMinors properties control whether a line is drawn with respect to the X and Y Minor tick marks on your axis.

32 Iocomp Components – Plot Pack Manual Chapter 5 - Data View

If you need to draw grid lines that match up with all Axes or that scroll independently with their associated Axes, utilize the special “” axis which will instruct the grid lines to be drawn for all visible Axes of that type. For example, if you are stacking three Y-Axes, you will probably want the horizontal grid lines to match up with the major ticks of each axis. To do this, simply set the GridYAxisName property of the DataView object to “”. iComponent.DataView(0).GridXAxisName = "" iComponent.DataView(0).GridYAxisName = ""

FIGURE 5.3 Example showing DataView Major Tick and Minor Tick Grid Lines.

Major Tick Minor Tick Grid Line Grid Line

Extended Grid-Line Customization The following properties provide extended customization capabilities of the Data View Grid Lines such as setting custom X-Major, X-Minor- Y-Major, and Y-Minor grid line colors, width, and style properties…

GridLineXMajorCustom GridLineXMinorCustom GridLineYMajorCustom GridLineYMinorCustom These properties specify whether the custom properties below are applied to the grid line formatting, overriding the overall grid line color, width, and style properties. If this property is False, then the properties below will have no effect on the grid lines.

GridLineXMajorColor GridLineXMinorColor

Iocomp Components – Plot Pack Manual 33 Chapter 5 - Data View

GridLineYMajorColor GridLineYMinorColor These properties specify the color of the grid lines. This will override the overall color property of the grid lines specified by GridLineColor property..

GridLineXMajorWidth GridLineXMinorWidth GridLineYMajorWidth GridLineYMinorWidth These properties specify the width of the grid lines. There was no previous overall grid line width property to override.

GridLineXMajorStyle GridLineXMinorStyle GridLineYMajorStyle GridLineYMinorStyle These properties specify the style of the grid lines. This will override the overall color property of the grid lines specified by GridLineMajorStyle or GridLineMinorStyle property, depending on which type you are specifying.

Stacked Axes and Grid Lines When you use stacked axes in the plot components, the standard setting of one Y-Axis or X-Axis to draw the grid lines doesn’t always look correct. For example, the following grid lines do not work for this stacked-axes chart…

34 Iocomp Components – Plot Pack Manual Chapter 5 - Data View

FIGURE 5.4 Example showing DataView Grid Lines being drawn to a single Y-Axis.

The chart would look better if the Y-Axis grid lines were drawn to the ticks of all Y-Axis. To fix this, simply set the GridYAxisName property to the special value of “”…

iPlot1.DataView(0).GridYAxisName = ""

The resulting chart would look like the following…

Iocomp Components – Plot Pack Manual 35 Chapter 5 - Data View

FIGURE 5.5 Example showing DataView Grid Lines being drawn to all Y-Axis.

Grid Lines Drawn to All Y-Axes

36 Iocomp Components – Plot Pack Manual Chapter 5 - Data View

Properties BackgroundColor BackgroundTranparent Enabled GridLineColor GridLineMajorStyle GridLineMinorStyle GridLineShowBottom GridLineShowLeft GridLineShowRight GridLineShowTop GridLineShowXMajors GridLineShowXMinors GridLineShowYMajors GridLineShowYMinors GridLineXMajorColor GridLineXMajorCustom GridLineXMajorStyle GridLineXMajorWidth GridLineXMinorColor GridLineXMinorCustom GridLineXMinorStyle GridLineXMinorWidth GridLineYMajorColor GridLineYMajorCustom GridLineYMajorStyle GridLineYMajorWidth GridLineYMinorColor GridLineYMinorCustom GridLineYMinorStyle GridLineYMinorWidth GridShow GridXAxisName GridYAxisName Height Horizontal Name PopupEnabled StartPercent StopPercent Title Visible Width ZOrder Refer to the Appendix for more detailed information about this plot object’s properties.

Methods None. Open for future expansion.

Events OnBeforeZoomBox OnGotFocusDataView OnLostFocusDataView OnPopupMenuDataView Refer to the Appendix for more detailed information about this plot object’s events.

! All events are on the main component interface and not on the sub-object interface.

Iocomp Components – Plot Pack Manual 37 Chapter 6 - Channels

Chapter 6 - Channels

The Channel objects are the Plot Component objects that contain your Chart Data (Data Points) and provide the interface for adding data and sending tracking data to the associated axes.

There can be an unlimited number of channels in your chart. Each is addressed independently of all of the other channels in the chart. Each channel is associated with a particular X and Y-Axis so that it may draw its data in the Data View in relation to the X and Y Scales. Channels can be synchronous or asynchronous, depending on your needs. Display of digital data with fixed Digital-High and Digital- Low values are also supported.

By default, when you add data points to a chart, only trace lines connecting the points is actually drawn on the screen. You can, however, configure each individual channel to display one, all, or some of the following for each data point or groups or data points on the screen…

• Data Markers - these mark the position of the actual data point utilizing symbols or bitmaps • Trace Lines - these draw connecting lines between data points using your choice of interpolation styles: straight-line interpolation (i.e. connect the dots with straight-lines), rational interpolation, cubic spline interpolation, differential interpolation, and more interpolation types in future updates. You can even introduce “breaks” in trace lines by utilizing our null-data point feature. • Fill - this allows you to fill all the area from a specified “base-line” to the trace-line using your own customized fill color or pattern. • Bars - this allows you draw a bar type of chart with a bar drawn for each data point from a specified “base-line” to the Y-coordinate of each data point.

FIGURE 6.1 The Plot Pack Channel object with fill.

Channel Object

38 Iocomp Components – Plot Pack Manual Chapter 6 - Channels

If you open the run-time property editor and navigate to the channel’s tab, you will be able to access the Stats page which gives you current Point Count, Memory, and other important statistics about the selected channel.

FIGURE 6.2 Example showing the Run-Time Property editor Channel Stats Page.

Trace Lines Trace Lines are the lines drawn between data points on the graph. You can specify the line’s color, width, and style to help differentiate it from other trace lines in your chart. For graphs that don’t require lines drawn between data points, you can turn off the trace line by setting the TraceVisible property to False.

Curve fitting or Interpolation (e.g. Straight Line, Cubic Spline, Polynomial, Rational, Differential, etc) is also supported by the iPlot component channel object in addition to straight trace lines . Refer to the chapter entitled “Interpolation” for more information.

The following line styles are available…

Style Description iplsSolid A solid line. iplsDash A line made up of a series of dashes. iplsDot A line made up of a series of dots. iplsDashDot A line made up of alternating dashes and dots. iplsDashDotDot A line made up of a serious of dash-dot-dot combinations. Table 6.1

Iocomp Components – Plot Pack Manual 39 Chapter 6 - Channels

Since we use the Windows API (ActiveX and VCL components), trace line styles such as dashed, dot, and dot dash styles do not work with line widths greater than 1 (i.e. with line widths greater than 1, the trace line will always be solid.). Adding the ability to draw line widths greater than 1 using non-solid lines would seriously affect the speed of the component, so it is recommended that the data point markers and channel colors be used to differentiate between channels with line widths greater than 1.

Data Markers By default, when a data point is drawn on the plot component DataView area, nothing is actually draw on the screen. You can, however, use symbols or markers to denote a data point on the chart. This is useful in differentiating between channel data points and for highlighting true data points. The following types of markers are available.

Style Description Sample ipmsCircle Circle ipmsSquare Square ipmsDiamond Diamond ipmsCross Cross ipmsPlus Plus ipmsTriangleUp Triangle Pointing Up ipmsTriangleDown Triangle Pointing Down ipmsTriangleLeft Triangle Pointing Left ipmsTriangleRight Triangle Pointing Right ipmsVerticalLine Vertical Line ipmsHorizontalLine Horizontal Line Table 6.2

If you will be showing a large number of data points (100,000+) in the visible portion of the DataView, you may want to utilize the MarkersTurnOffLimit property to limit the number of visible data point markers. When this limit is reached, all data point markers for that channel will be hidden to prevent the overhead of drawing large numbers of overlapping data point markers.

Individual Data Markers By default, when data markers are drawn, the same data marker is used for all data points. You can specify different Data Markers for individual points. When the Data Marker is initially added to the channel, its properties are initially set to the default values specified for the channel. First, set the MarkersAllowIndividual property to True to allow individual specification of each data marker. You can then later use the following properties to modify a data marker.

'Setup Channel iPlot1.Channel(0).MarkersVisible = True iPlot1.Channel(0).MarkersStyle = ipmsDiamond 'The default style for all 'data markers iPlot1.Channel(0).MarkersAllowIndividual = True 'Data Point 1 index = iPlot1.Channel(0).AddXY (10, 75) 'We'll let this data marker

40 Iocomp Components – Plot Pack Manual Chapter 6 - Channels

'use the default values 'Data Point 2 index = iPlot1.Channel(0).AddXY (10, 75) iPlot1.Channel(0).DataMarkerShow(Index) = False 'Hide this specific 'data marker 'Data Point 3 index = iPlot1.Channel(0).AddXY (11, 72) iPlot1.Channel(0).DataMarkerStyle(index) = ipmsPlus 'Change the style 'of this data marker

Channel Fill The iPlot component supports the ability to flood fill an area between the trace line and a specified base line (either above or below the trace line). The Fill feature is not available with the iXYPlot component since its datasets are not based on y = f(x) .

To specify a baseline for the flood fill, use the FillReference property on a specific channel.

FIGURE 6.3 Example showing three channels with varying Channel Fill Reference Points.

ReferenceLine = 0 ReferenceLine = 60 ReferenceLine = 80

Tracking Tracking refers to the AutoScale and AutoScrolling features of the axes. When new data is added to the channel, X tracking data is sent to the associated X-Axis and Y tracking data is sent to the associated Y-Axis This data is used by the chart to automatically scale and scroll the axes and channel data.

By default, tracking data is sent to both the X and Y-Axes referred to by the channel’s XAxisName and YAxisName properties. You can enable or disable the sending of tracking data to a specific X or Y-Axis by using the XAxisTrackingEnabled and YAxisTrackingEnabled properties.

Iocomp Components – Plot Pack Manual 41 Chapter 6 - Channels

Ring Buffer By default, the chart will buffer all of the data points added to all channels into RAM. This buffered data makes it possible to scroll back to older data (history) and other related functions.

Remember that the RingBuffer properties are assigned to individual channels, and are independent of other channels.Also, Remember that the RingBuffer is specified as the number of data points that will be stored in the buffer.

The RingBuffer property allows you to control how much data is stored in available memory. If you set the RingBuffer property to 10,000, then memory will be allocated for 10,000 data points. After you add 10,000 data points, the oldest data will begin to be replaced by newly added data points. The Ring Buffer is a FIFO (First In First Out) type buffer. You can find more information on using the Ring Buffer feature in the chapter entitled “Memory Utilization”.

Bar Support Another option of the channels is to draw a bar from a base reference point to the Y-Axis value of each data point in the channel. For example, the below plot shows two channels with 9 data points visible in each channel. There are 9 bars drawn from the bar base line value of the channel (specified by the channel’s BarReference property) to the Y-Axis value of the each data point. Channel 1 has a base line value of 0. Channel 2 has a base line value of 75.

The width of all bars in a channel is specified by the BarWidth property of the channel.

FIGURE 6.4 Example showing two channels with various Bar Reference and Data Point Y Values.

42 Iocomp Components – Plot Pack Manual Chapter 6 - Channels

FIGURE 6.5 Bar Reference Data Point Y Value Example showing a single channel with both mixed trace line and bar representations of the data.

Bar Reference Data Point Y Value

Data Styles By default, the component is setup to utilize our Standard Data set type. This style of data allows for the storage of double-precision data, with each data point having it’s own unique X,Y coordinate pair. This Standard Data set style also allows for the utilization of our extended features such as Null Data Point Support, Empty Data Point Support, Individual Marker Hiding, and Individual Marker Styles.

In contrast, we have two new data styles: Compact and Compact Interval. These Compact Data set types allow for a greater number of data points to be added to the chart (up to approximately 175 million data points for Compact and 350 million data points for Compact Interval) at the expense of fewer extended features mentioned above and single-precision data. These styles also reduce the memory footprint of channels with large data sets and can reduce virtual memory swapping, though this is really only an issue with data sets that exceed millions of data points per channel or chart.

In a future version, we will have an extended Data Style which will consume more memory per data point, but will allow for an even greater number of extended features for each data point such as individual bar styles, etc. This style will be useful for those charts with limited numbers of data points, but require even more flexibility.

Below is a table showing the amount of data points and the bytes per data point used by each Data Style…

Iocomp Components – Plot Pack Manual 43 Chapter 6 - Channels

Bytes Maximum # Per Meaning of Data Value Data Points Point The original data style for the component. This data set supports all of the features of the component and stores values in double-precision format. This data set supports the following features 24 ipdsStandard 58,161,015 Empty Data Points bytes Null Data Points Individual Marker Hiding Individual Marker Styles A single-precision, compact data storage type that uses 8 bytes per data point. This data set does not support the following features...· 8 ipdsCompact Empty Data Points 174,483,045 bytes Null Data Points Individual Marker Hiding Individual Marker Styles An single-precision, extremely compact data storage type for fixed-interval data sets that uses 4 bytes per data point. The first and second data point x-values added to the channel determine the fixed- interval used for the entire data set. For example, if the first data point's X-Value is 1, and the second data point's X-Value is 6, then the X-Value interval between all data points in this channel will be fixed 4 ipdsCompactInterval at 5 (Interval = 6 - 1 = 5). All future X-Values will 348,966,092 bytes be ignored. This was done to keep backward compatibility with previous log files and data sets. This data set does not support the following features...· Empty Data Points Null Data Points Individual Marker Hiding Individual Marker Styles Table 6.3

Virtual Memory: if you will be using extremely large numbers of data points, you will need to investigate the total memory usage needed by your application and adjust your virtual memory settings in your operating system accordingly. The Maximum # of Data Points quoted is a theoretical maximum assumes that your application uses 0KB of memory. Since this is not the case, your actual maximum storage of data points will depend on the operating system limitations. In our research, the actual maximum memory that any component can utilize in a Windows 32-bit application is 1.3GB. Again, memory used by other parts of your application will affect this maximum value. Future versions of Windows may change this limitation.

44 Iocomp Components – Plot Pack Manual Chapter 6 - Channels

Digital Channel Support If your data sets contain binary data (0’s and 1’s, True and False, etc.), then you can set the DigitalEnabled property to True to enable Digital Channel support.

Some compilers treat True as –1 or 1, so any value that is not zero (0) is treated as a Digital ! High or Logic = True .

When Digital Channel Support is on, Y values that are 0 are plotted on the Y-Axis scale according to the DigitalReferenceLow value. Y values that are not equal to 0 are plotted on the Y-Axis scale according to the DigitalReferenceHigh value. The result is two possible values for Y on the Y-Axis. All data will be squared off, with a horizontal line drawn from the last data point to the next data point, and then a vertical line drawn between the last horizontal line to the next data point as shown below in Channel #2…

FIGURE 6.6 Data Points Example showing a digital channel and points out the position of the actual data points added.

Asynchronous and Synchronous Data The Plot Components are able to handle Asynchronous Data (several channels that don’t have synchronized X-Axis or Time data values) or Synchronous Data (several channels that have X- Axis or Time data values that are the same. i.e. there is one data point in each channel for any given X-Axis or Time data value).

The only difference between the two data set types relates to the use of the following features of the chart…

Iocomp Components – Plot Pack Manual 45 Chapter 6 - Channels

Using the Main Component AddDataArray Method: This method allows you to add data to multiple channels by passing a single array to the component’s main interface. The method assumes that all data is synchronous since you pass the interval between all data points in the XValue parameter . If you wish to add Asynchronous Data to the chart, utilize the Add Data Array methods available on the channel interface.

Using the Main Interface Data Logging: You must use the AddDataArray method which therefore requires that your data be synchronous.

If you need to determine the data point index of the data points in the viewable part of the channel (i.e. the data that is currently visible in the DataView), use the DrawStartIndex and DrawStopIndex properties. These properties give you the lowest index value and highest index value of the datapoints currently visible for a particular channel.

Channel Data Logging This feature is useful if you need an automated way of saving chart data to disk as it is being added in real-time. The saved data can be used by an external program or can be used to reload the data back into the chart at a later time.

Channel Data Logging can be setup for each individual channel. You can also setup the main interface for automatic Channel Data Logging of all channels to disk, but you must be using Synchronous Data.

Refer to the chapter entitled “Loading and Saving Data” for more detailed information.

The directory specified when using the channel data logging feature must exist on the target system and the application’s user must have permissions to write to that directory or ! file. Otherwise, an exception error will be generated.

FastDraw This feature, only available with the iPlot component, increases the drawing efficiency of the channel data when drawing large data sets to the Data View area. This is accomplished by reducing the number of drawing operations required to draw your channel data.

Benefits: Dramatically speeds up drawing of data points and trace lines to the screen when you are showing a large number of data points. Drawbacks: Can sometimes create aliasing effects while the chart is scrolling. However, it is guaranteed to show you the extremes of the data points at all times.

Channel Types Each component in the Plot Pack is setup to handle a specific plotting task using a channel type specific to that plot component. The channel type denotes which features are available for adding data to that channel. The channel types available for use are as follows.

46 Iocomp Components – Plot Pack Manual Chapter 6 - Channels

Refer to the chapter entitled “Adding Data” for more detailed information on using the different add data methods described below.

iPlot Component Channel: iPlotChannel: This is the channel type used by the iPlot component. Implements Date Time adding methods and method for adding X Null and X Empty data points. For Date Time adding methods, it is assumed that the X-Axis is the Time Axis. You can rotate the axes if you wish the Time Axis (the X-Axis) to be vertical instead of horizontal.

AddXY : adds data points in X and Y data point pairs.

Index = iPlot1.Channel(ChannelNumber).AddXY(XValue, YValue) Index = iPlot1.Channel(0).AddXY(10.34, 25.43)

AddXYArrays : adds data points from two variant arrays, each containing x and y values. The number of elements in each array must be identical (i.e. if XArray contains 100 elements, YArray must contain 100 elements), otherwise an exception will be generated.

Index = iPlot1.Channel(ChannelNumber).AddXYArrays(XArray, YArray)

This procedure is able to handle variant arrays that start at element 0 or any value that you require. If you array starts at element XArray(10), then that value will be used to add the first data point.

It is recommended that you loop through your array and use the AddXY method to add data to the chart as that is much faster than using the AddXYArrays procedure due to the use of Variants. This procedure has been added as a convenient way of passing variant arrays to the channel to add data, but is slower than simply looping through the array in your program. If your data is already in Variant array format (i.e. not a double array), then there is no performance penalty by using the AddXYArrays procedure.

AddYArray : Adds multiple y values with a specified X-Axis spacing interval. For example, if your variant array (Y values) contains 100 elements and your XInterval is 1, then the plot component will plot all of your Y values with an increasing X value of 1. First data point is (1, YArray(0)), second data point is (2, YArray (1)), third data point is (3, YArray (2)), fourth data point is (4, YArray (3)), etc.

Index = iPlot1.Channel(ChannelNumber).AddYArray(XInterval, YArray)

This procedure is able to handle variant arrays that start at element 0 or any value that you require. If you array starts at element XData(10), then that value will be used to add the first data point.

AddYElapsedSeconds : adds a Y data point at an X coordinate specified by the number of elapsed seconds since the ResetElapsedStartTime method was called.

Index = iPlot1.Channel(0).AddYElapsedSeconds(YValue) Index = iPlot1.Channel(0).AddYElapsedSeconds(25.43)

Iocomp Components – Plot Pack Manual 47 Chapter 6 - Channels

AddYElapsedTime : adds a Y data point at an X coordinate specified by the amount of time (in DateTimeFormat) since the ResetElapsedStartTime method was called.

Index = iPlot1.Channel(0).AddYElapsedTime(YValue) Index = iPlot1.Channel(0).AddYElapsedTime(25.43)

AddYNow : adds a Y data point at an X coordinate specified by the current system time (in DateTimeFormat).

Index = iPlot1.Channel(0).AddYNow(YValue) Index = iPlot1.Channel(0).AddYNow(25.43)

AddYElapsedTime and AddYNow: The time interval depends on whether your X-Axis is in Date/Time format or not. If LabelsFormatStyle of the X-Axis is iptfDateTime, then the interval must be specified in Date/Time format. Otherwise, the interval is expressed in seconds or the units that are used on your X-Axis.

AddXNull : adds a data point at a specified X data point. The Y value will be set to Null.

Index = iPlot1.Channel(0).AddXNull(XValue) Index = iPlot1.Channel(0).AddXNull(10.34)

AddXEmpty : adds an empty data point at a specified X coordinate with no Y coordinate. An empty data point is a data point with no X or Y Value, only an index placeholder for the data point. Since this data point doesn’t have an X or Y Value, no Data Marker is shown and the trace line will not be drawn to this data point. This is useful for adding data point “placeholders” so that you can set the X and Y value of the data point at a later time.

Index = iPlot1.Channel(0).AddXEmpty(XValue) Index = iPlot1.Channel(0).AddXEmpty (10.34)

Refer to the chapter entitled “Null Data and Empty Data Handling” for more information on Null and Empty Data Points.

The iPlot component does not support null X data points. Use the iXYPlot component if ! you need to create null X and Y data points.

iXYPlot Component Channel: iPlotXYChannel: This is the channel type used by the iXYPlot component. Supports adding data using the AddXY method. Also supported is the AddNull method for adding null data points

AddXY : adds data points in X and Y data point pairs.

iPlot1.Channel(0).AddXY(XValue, YValue) iPlot1.Channel(0).AddXY(10.34, 25.43)

48 Iocomp Components – Plot Pack Manual Chapter 6 - Channels

AddXYArrays : adds data points from two variant arrays, each containing X and Y values. The number of elements in each array must be identical (i.e. if XArray contains 100 elements, YArray must contain 100 elements), otherwise an exception will be generated.

iPlot1.Channel(0).AddXYArrays(XArray, YArray)

AddNull : sets a data point as a null data point (both X and Y coordinates).

Index = iPlot1.Channel(0).AddNull()

'or you can add a point and then set it to null later Index = iPlot1.Channel(0).AddXY(15.4,17.9) iPlot1.Channel(0).DataNull(Index) = TRUE

AddEmpty : sets a data point as an empty data point. An empty data point is a data point with no X or Y Value, only an index placeholder for the data point. Since this data point doesn’t have an X or Y Value, no Data Marker is shown and the trace line will not be drawn to this data point. This is useful for adding data point “placeholders” so that you can set the X and Y value of the data point at a later time.

Index = iPlot1.Channel(0).AddEmpty()

'You can later set the X and Y coordinates of this 'data point by using the DataX and DataY properties iPlot1.Channel(0).DataX(Index) = XValue iPlot1.Channel(0).DataY(Index) = YValue

Refer to the chapter entitled “Null Data and Empty Data Handling” for more information on Null and Empty Data Points.

Iocomp Components – Plot Pack Manual 49 Chapter 6 - Channels

Properties BarBrushColor BarBrushStyle BarBrushUseChannelColor BarEnabled BarPenColor BarPenStyle BarPenUseChannelColor BarPenWidth BarReference BarWidth Capacity Color Count DataEmpty DataMarkerShow DataMarkerStyle DataNull DataPointSize DataStyle DataX DataY DigitalEnabled DigitalReferenceHigh DigitalReferenceLow DigitalReferenceStyle DrawStartIndex DrawStopIndex ElapsedStartTime Enabled FastDrawEnabled FillColor FillEnabled FillReference FillStyle FillUseChannelColor InterpolationStyle LogBufferSize LogFileName LoggingActive MarkersAllowIndividual MarkersBrushColor MarkersBrushStyle MarkersBrushUseChannelColor MarkersPenColor MarkersPenStyle MarkersPenUseChannelColor MarkersPenWidth MarkersSize MarkersStyle MarkersTurnOffLimit MarkersVisible MaxDataPoints MemoryUsed Name OPCAutoConnect OPCComputerName OPCItemName OPCServerName OPCUpdateRate OPCXValueSource PopupEnabled RingBufferSize RunningYMax RunningYMean RunningYMin Tag TitleText TraceLineStyle TraceLineWidth TraceVisible VisibleInLegend Visible XAxisName XAxisTrackingEnabled YAxisName YAxisTrackingEnabled Refer to the Appendix for more detailed information about this plot object’s properties.

Methods AddXEmpty AddXNull AddXYArrays AddXY AddYArray AddYElapsedSeconds AddYElapsedTime AddYNow Clear DeletePoints GetXMax GetXMean GetXMin GetYInterpolated GetYMax GetYMean GetYMin LoadDataFromFile LoadPropertiesFromFile LogActivate LogDeactivate OPCActivate OPCDeactivate ResetElapsedStartTime SaveDataToFile SavePropertiesToFile Refer to the Appendix for more detailed information about this plot object’s properties.

Events OnClickDataPoint OnGotFocusChannel OnLostFocusChannel OnPopupMenuChannel Refer to the Appendix for more detailed information about this plot object’s events.

All events are on the main component interface and not on the sub-object interface. They ! are provided here for your convience.

50 Iocomp Components – Plot Pack Manual Chapter 7 - Legend

Chapter 7 - Legend

The Legend object provides display of channel names and their associated line and marker color symbols for easy reference by your application user.

FIGURE 7.1 Example showing a digital channel and points out the position of actual data points.

Legend Object

Predefined Columns By default, only the “Line” column is shown in the legend as well as the Channel Title. You can choose to show or hide the following columns in the chart as well as their associated titles…

Line : Displays the line style and line color of the channel. Marker : Displays the marker style and marker color of the channel. X-Axis Title : Displays the X-Axis title associated with this channel. Y-Axis Title : Displays the Y-Axis title associated with this channel.

Currently, the legend can only be a vertical Plot Object. Horizontal support will be added in ! a future release.

X-Value: Displays the last added data point’s X-Value for this channel. Y-Value: Displays the last added data point’s Y-Value for this channel. Y-Max: Displays the maximum Y-Value for this channel. Y-Min: Displays the minimum Y-Value for this channel. Y-Mean: Displays the mean Y-Value for this channel.

Iocomp Components – Plot Pack Manual 51 Chapter 7 - Legend

Only the Channel Title is shown in the “Title” Column. The Channel Title is set by using the ChannelTitle property of the channel. The Name property of each channel is the ! name that is used programmatically and is not the title seen by end user of the chart.

If you are using long Titles for your channels, you can utilize the ChannelNameMaxWidth property. This property specifies the maximum width, in characters, of Titles displayed in the legend. If the Title exceeds the number of characters specified, it will word-wrap to the next line.

FIGURE 7.2 Example showing the Legend object with the Line, Marker, X-Axis Title, and Y-Axis Title columns showing.

Turn On and Off Column Titles By default, the title of each column in the legend is not shown. You can choose to show the title of each column by setting the ColumnTitlesVisible = TRUE or by using the built-in property editor to make the Column Titles Visible.

52 Iocomp Components – Plot Pack Manual Chapter 7 - Legend

Properties BackGroundColor BackGroundTransparent ChannelNameMaxWidth ColumnSpacing ColumnTitlesFont ColumnTitlesVisible Enabled Font Height Horizontal MarginBottom MarginLeft MarginRight MarginTop Name PopupEnabled RowSpacing SelectedItemBackGroundColor SelectedItemFont ShowColumnLine ShowColumnMarker ShowColumnXAxisTitle ShowColumnXValue ShowColumnYAxisTitle ShowColumnYMax ShowColumnYMean ShowColumnYMin ShowColumnYValue StartPercent StopPercent Visible Width ZOrder Refer to the Appendix for more detailed information about this plot object’s properties.

Methods None. Open for future expansion.

Events OnGotFocusLegend OnLostFocusLegend OnPopupMenuLegend Refer to the Appendix for more detailed information about this plot object’s events.

In versions prior to Version 2.0.4 Service Pack 2, the X-Value and Y-Value columns were used to display the current position of the cursor. This has been changed so that cursor position data is shown in a hint window next to the cursor line(s). Refer to the chapter on Cursors for more information about displaying cursor data.

! All events are on the main component interface and not on the sub-object interface.

If you change previous data points, the YMax, YMin, and YMean values will no longer be valid. To refresh these values if you change previous data points, call GetYMax, GetYMin, and/or GetYMean to force a recalculation of these values after making your ! chages.

Iocomp Components – Plot Pack Manual 53 Chapter 8 - ToolBar

Chapter 8 - ToolBar

The Toolbar object provides access for your application user to many built-in features of the Plot Pack components such as Tracking Control, Zooming, Scrolling, Cursor, Clipboard, Print, Save, access to the Run-Time Property Editor, and many other functions which can be expanded.

The built-in toolbar makes it easy to use our component without needing a separate, external component or additional program code to implement a toolbar. Of course, if you need additional features that our toolbar doesn’t provide or if you need to include functions in a unified application toolbar, you can dispense with this toolbar and implement a toolbar externally. Refer to the chapter entitled “Implementing Toolbar Externally” for more detailed information.

Currently, the toolbar only supports being aligned to the top of the component. Moving and sizing the toolbar as well as support for multiple toolbars is left open for future expansion.

Configure Individual Buttons There are currently 10 buttons available for display and use in the toolbar. You can individually show or hide buttons by using the “Show” properties listed below. Additional buttons will be added and is open for future expansion.

FIGURE 8.1 Example showing the Legend object with the Line, Marker, X- Axis Title, and Y-Axis Title columns showing.

ToolBar Object

54 Iocomp Components – Plot Pack Manual Chapter 8 - ToolBar

Implemented Externally There are various methods and properties implemented for use in your programs code to control the toolbar outside of the Plot Component. Refer to the chapter on “Implementing Toolbar Externally” for more information.

Button Descriptions

Resume Button This button resumes all tracking on all axes. Also, all cursors are hidden and all axes are re- zoomed to their stored values. To ensure that new axis zoom settings are saved, right-click on the appropriate axis and select "Update Resume Values".

Pause Button This button pauses tracking on all axes.

Axes Scroll Mode Button There are two modes available when clicking the mouse on an axis and moving the mouse up/down or right/left. This button allows the axis to scroll.

Axes Zoom Mode Button There are two modes available when clicking the mouse on an axis and moving the mouse up/down or right/left. This button allows the axis to zoom.

Zoom In Button This button increases the zoom on all axes by a factor 2x.

Zoom Out Button This button decreases the zoom on all axes by a factor 2x.

Select Button Used for selecting items in the data view area. Generates events that can be used by the programmer to react to selection of items such as data points, annotations, areas of the data view, etc. Also used for moving annotations that have their UserCanMove property set to TRUE.

Zoom Box Button This button allows the user to draw a box on the DataView area and zoom all axes around the selected area. This tool has a dual purpose. It can also be used as a rectangular, region selection tool by utilizing the OnBeforeZoomBox event. In the event handler, cancel the zoom and then utilize the coordinate values passed to you to determine the selected, rectangular region bounds.

Cursor Button This button shows or hides all data cursors.

Iocomp Components – Plot Pack Manual 55 Chapter 8 - ToolBar

Edit Button This button brings up the run-time property editor for the component.

Copy Button This button copies an Enhanced Metafile Format version of the component to the clipboard.

Save Button This button brings up a save dialog to save out snapshots of the chart in several supported graphic formats.

Print Button This button brings up a print selection dialog to print out the current chart to a system or network printer. The chart as it is drawn when this button is pressed is used to generate the chart printout.

Properties CursorActive Enabled Height Horizontal Name PopupEnabled SelectActive ShowAxesModeButtons ShowCopyButton ShowCursorButton ShowEditButton ShowPauseButton ShowPrintButton ShowResumeButton ShowSaveButton ShowSelectButton ShowZoomBoxButton ShowZoomInOutButtons StartPercent StopPercent Visible Width ZoomBoxActive ZoomInOutFactor ZOrder Refer to the Appendix for more detailed information about this plot object’s properties.

Methods DoButtonClickCopy DoButtonClickCursor DoButtonClickEdit DoButtonClickPause DoButtonClickPrint DoButtonClickResume DoButtonClickSave DoButtonClickScrollAxesMode DoButtonClickSelect DoButtonClickZoomAxesMode DoButtonClickZoomBox DoButtonClickZoomIn DoButtonClickZoomOut TurnOffCursor Refer to the Appendix for more detailed information about this plot object’s properties. Also refer to the Implementing Toolbar Externally chapter for more information.

Events None. Open for future expansion.

56 Iocomp Components – Plot Pack Manual Chapter 9 - Annotations

Chapter 9 - Annotations

The Annotation Objects are the text and shapes that can be displayed in the DataView, overlaid over your channel data. Annotations can be positioned in relation to a particular channel or to the DataView area, depending on whether you want the annotations to scroll or track with the channel data or be fixed in place within the DataView.

Annotations can be in the form of text strings, lines, or rectangles. Additional annotation types will be added and is open for future expansion.

FIGURE 9.1 Example showing several annotation types available.

Text Annotation Object Graphical Annotation Objects

Iocomp Components – Plot Pack Manual 57 Chapter 9 - Annotations

Annotation Types Text: Font size, style, name, color properties, and text rotation can be set for each individual text annotation. Use the X and Y properties to set the center-point of the Text Object. The text will be centered both horizontally and vertically around this point.

FIGURE 9.2 Example of a Text Sample Annotation Annotation.

X, Y Center Point

Text Rectangle: Text annotations with a surrounding rectangle. Font size, style, name, color properties, and text rotation can be set for each individual Text Rectangle annotation. Use the X and Y properties to set the center-point of the Text Rectangle Object. Width, length, line color, fill style, and fill color properties can also be. The text will be centered both horizontally and vertically within the rectangle.

FIGURE 9.3 Example of a Text Rectangle Annotation. Sample Annotation

PenColor, BrushColor and PenStyle, and BrushStyle PenWidth X, Y Center Point

Line: Width, length, and line color properties can be set for each individual line annotation. Use the X and Y properties to set the beginning point of the line (X,Y) and the X2 and Y2 properties to set the end point of the line (X2, Y2).

FIGURE 9.4 Example of a Line PenColor, Annotation. X, Y Start Point PenStyle, and X2, Y2 End Point PenWidth

58 Iocomp Components – Plot Pack Manual Chapter 9 - Annotations

Rectangle: Rectangle annotations. Width, length, line color, fill style, and fill color properties can be set for each individual rectangle annotation. Use the X and Y properties to set the center- point of the Rectangle Object. The rectangle will be centered both horizontally and vertically around this point. Use the Width and Height properties to set the rectangle’s width and height. Use the PenColor, PenWidth, and PenStyle properties to set the border line properties. Use the BrushColor and BrushStyle properties to set the fill properties.

FIGURE 9.5 Example of a Rectangle Annotation. PenColor, PenStyle, and PenWidth BrushColor and BrushStyle

X, Y Center Point

You can also allow the user to resize and/or move annotations (except for line annotations) by utilizing the UserCanSize and UserCanMove properties of each individual annotation. Events such as OnAnnotationCoordinatesChangeFinished, OnAnnotationCoordinatesChange, and OnClickAnnotation can be used to perform actions when a user changes an annotation position or resizes the annotation.

LineX: X-Axis Line Annotation. Set the X coordinate to specify the X-Axis value that will be used to draw a line perpendicular to the X-Axis. The length of the line goes from positive infinity to negative infinity on the Y-Axis.

FIGURE 9.6 Example of a Line X Annotation.

PenColor, PenStyle, and PenWidth

X-Axis Value

Iocomp Components – Plot Pack Manual 59 Chapter 9 - Annotations

LineY: Y-Axis Line Annotation. Set the Y coordinate to specify the Y-Axis value that will be used to draw a line perpendicular to the Y-Axis. The length of the line goes from positive infinity to negative infinity on the X-Axis.

FIGURE 9.7 Example of a Line Y Annotation.

PenColor, PenStyle, and PenWidth Y-Axis Value

Bitmap Image: Bitmap Annotations. Use the X and Y properties to set the center-point of the Text Object. The image will be centered around this point. Images are obtained from the built- in image lists of the component. You can add images at design-time by using our built-in property editors, and loading in bitmap images of identical size. There are three image lists available, supporting an unlimited number of images…

FIGURE 9.8 Example of a Bitmap Image Annotation.

X, Y Center Point

60 Iocomp Components – Plot Pack Manual Chapter 9 - Annotations

Bitmap Image List The Plot component has several built-in image lists for use with the Plot Pack Annotation feature (other parts of the Plot Pack Components will utilize these image lists as well in future updates).

To add or remove bitmap images from the image lists, you must use the design-time property editor of the components to load these images into the component. This will allow the images to be streamed into the form and your compiled application.

These images were provided since not all development environments support image lists, and image list controls can vary from development environment to development environment as well as differing platforms (Windows vs. Linux).

The first image you add to a particular image list will dictate the size of the other images in that image list. If you add subsequent images that are larger than the first, they will be centered and cropped to fit.

Note: If you add subsequent images that are smaller than the first, their canvases will be expanded in size (not stretched), centered, and filled with the transparent background color of the image (the transparent color is always the pixel in the lower left-hand color of the image).

Reversing Axes has no effect on DataView aligned Annotations. The reference values specified are always left to right (0-100) and bottom to top in relation to the Data View.

FIGURE 9.9 Design-Time Property Editor Showing Built-In Image Lists

Iocomp Components – Plot Pack Manual 61 Chapter 9 - Annotations

Annotation Reference Relationships When setting the X, Y, X2, and Y2 coordinates of each annotation object, these coordinates can refer either to a specific channel or to the DataView itself.

DataView Reference To have the annotation be referenced to the DataView area, set the Reference property to iprtDataView. The coordinates will now refer to the DataView and will in effect be static in relation to the axes and channels in the chart. The range of values possible for the X and Y coordinates are from 0 – 100. A value of 0 would correspond to the left (X coordinate) or bottom (Y coordinate) of the DataView area. A value of 100 would correspond to the right (X coordinate) or top (Y coordinate) of the DataView area. A value of 50 would be halfway in-between.

Channel Reference To have the annotation be referenced to a particular channel, set the ChannelName Property to the name of the channel and set the Reference property to iprtChannel. The coordinates specified will now be in reference to the X and Y-Axes associated with that channel. In effect, the annotation will move with the channel as the channel and associated axes are scrolled.

FIGURE 9.10 Annotation References Reference = iprtDataView Reference = iprtChannel Annotation references Data View Annotation references Channel’s Axes

Reference = iprtXDataViewYChannel Reference = iprtXChannelYDataView • X-Coordinate references Data View • X-Coordinate references Channel's horizontal Axis • Y-Coordinate references Channel's horizontal (X-Axis unless axes have been flipped) Axis (X-Axis unless axes have been flipped) • Y-Coordinate references Data View

62 Iocomp Components – Plot Pack Manual Chapter 9 - Annotations

XDataViewYChannel Reference To have the X-Coordinate of the annotation be referenced to the DataView area and the Y-Coordinate of the annotation be referenced to the vertical axis of a Channel (Y-Axis unless axes have been flipped), set the Reference property to iprtXDataViewYChannel. The X-coordinates will now refer to the DataView and will in effect be static in relation to the axes and channels in the chart. The Y-coordinates specified will now be in reference to the Y-Axes associated with that channel. The range of values possible for the X coordinates are from 0 – 100. A value of 0 would correspond to the left (X coordinate) of the DataView area. A value of 100 would correspond to the right (X coordinate) of the DataView area. A value of 50 would be halfway in-between.

XChannelYDataView Reference To have the X-Coordinate of the annotation be referenced to the vertical axis of a Channel (Y-Axis unless axes have been flipped) and the Y-Coordinate of the annotation be referenced to the DataView area, set the Reference property to iprtXChannelYDataView. The X-coordinates specified will now be in reference to the X- Axes associated with that channel. The Y-coordinates will now refer to the DataView and will in effect be static in relation to the axes and channels in the chart. The range of values possible for the Y coordinates are from 0 – 100. A value of 0 would correspond to the bottom (Y coordinate) of the DataView area. A value of 100 would correspond to the top (Y coordinate) of the DataView area. A value of 50 would be halfway in-between.

Moveable Annotations Annotations can be moveable by your application end user by setting the UserCanMove property of each annotation object.

Index = iPlot1.Annotation(0).UserCanMove = True

When this property is set to true, the application end-user at runtime will be able to grab a hold of and drag annotations within the DataView area.

Note: the line annotation style does not currently support this feature.

Resizable Annotations Certain annotations can also be resized by your application end user by setting the UserCanSize property of each annotation object.

Index = iPlot1.Annotation(0).UserCanSize = True

When this property is set to true, the application end-user at runtime will be able to grab a hold of anchors located around the annotation and resize the annotation within the DataView area.

How to Add Annotations To add an annotation to the chart, simply execute the following method…

Index = iPlot1.AddAnnotation

The return value is an unique index for use in manipulating the object. After adding the object, you can set the properties of the annotation, such as setting the object as a text annotation and its

Iocomp Components – Plot Pack Manual 63 Chapter 9 - Annotations

associated font properties or setting the object as a line annotation and its associated line properties.

[Note: Font properties in the example below will differ depending on your compiler]

Text Annotation Example iPlot1.Annotation(Index).Reference = iprtChannel iPlot1.Annotation(Index).ChannelName = "Channel 1" iPlot1.Annotation(Index).X = 18.33 'Center X Coordinate iPlot1.Annotation(Index).Y = 59.85 'Center Y Coordinate iPlot1.Annotation(Index).Style = ipasText 'Text Annotation iPlot1.Annotation(Index).FontColor = vbWhite 'White Font iPlot1.Annotation(Index).Text = "Sample Annotation" iPlot1.Annotation(Index).TextRotation = ira180 'Rotate up-side-down

Line Annotation Example iPlot1.Annotation(Index).Reference = iprtChannel iPlot1.Annotation(Index).ChannelName = iPlot1.Channel(0).Name iPlot1.Annotation(Index).X = 18.33 'Starting X Coordinate iPlot1.Annotation(Index).Y = 59.85 'Starting Y Coordinate iPlot1.Annotation(Index).X2 = 67.4 'Ending X Coordinate iPlot1.Annotation(Index).Y2 = 104.85 'Ending Y Coordinate iPlot1.Annotation(Index).Style = ipasLine 'Line Annotation iPlot1.Annotation(Index).PenColor = vbWhite 'White Line iPlot1.Annotation(Index).PenStyle = psSolid 'Solid Line iPlot1.Annotation(Index).PenWidth = 2

Rectangle Annotation Example iPlot1.Annotation(Index).Reference = iprtDataView iPlot1.Annotation(Index).X = 55.25 'Center X % Coordinate iPlot1.Annotation(Index).Y = 75.25 'Center Y % Coordinate iPlot1.Annotation(Index).Width = 20 'Width in % of DataView Width iPlot1.Annotation(Index).Height = 20 'Height in % of DataView Height iPlot1.Annotation(Index).Style = ipasRectangle 'Rectangle Annotation iPlot1.Annotation(Index).PenColor = vbWhite 'White Border iPlot1.Annotation(Index).PenStyle = psDash 'Dashed Line iPlot1.Annotation(Index).PenWidth = 1 iPlot1.Annotation(Index).BrushColor = vbYellow 'Yellow Fill iPlot1.Annotation(Index).BrushStyle = bsDiagCross

LineX Example iPlot1.Annotation(Index).Reference = iprtChannel iPlot1.Annotation(Index).ChannelName = iPlot1.Channel(0).Name iPlot1.Annotation(Index).X = 18.33 'X Coordinate iPlot1.Annotation(Index).Style = ipasLineX 'LineX Annotation iPlot1.Annotation(Index).PenColor = vbWhite 'White Line iPlot1.Annotation(Index).PenStyle = psSolid 'Solid Line iPlot1.Annotation(Index).PenWidth = 2

LineY Example iPlot1.Annotation(Index).Reference = iprtChannel iPlot1.Annotation(Index).ChannelName = iPlot1.Channel(0).Name iPlot1.Annotation(Index).Y = 59.85 'Y Coordinate iPlot1.Annotation(Index).Style = ipasLineY 'LineY Annotation iPlot1.Annotation(Index).PenColor = vbWhite 'White Line iPlot1.Annotation(Index).PenStyle = psSolid 'Solid Line

64 Iocomp Components – Plot Pack Manual Chapter 9 - Annotations

iPlot1.Annotation(Index).PenWidth = 2

How to Remove Annotations To remove an annotation, execute the DeleteAnnotation method, passing the unique index value of the annotation to delete. To delete all annotations, execute the RemoveAllAnnotations method. Note that these methods are on the main component interface.

Annotation Click Event This event, actually an event on the main component interface, is fired every time a user clicks on an annotation when the Select Button is engaged. The event passes back the Index of the Annotation that is clicked.

‘Visual Basic OnClickAnnotation(ByVal Index As Long)

//Visual C++ CProgramDlg::OnClickAnnotation(long Index)

//Delphi-Kylix-C++ Builder TForm1.iPlot1ClickAnnotation(Index: Integer)

Properties BrushColor BrushStyle ChannelName Enabled FontColor Font Height ImageIndex ImageListIndex Name PenColor PenStyle PenWidth PopupEnabled Reference Style TextHorzAlignment TextHorzMargin Text TextRotation TextVertAlignment TextVertMargin UserCanMove UserCanSize Visible Width X2 XY2Y Refer to the Appendix for more detailed information about this plot object’s properties.

Methods PositionXToPixels PositionYToPixels PixelsXToPositon PixelsYToPosition Refer to the Appendix for more detailed information about this plot object’s methods.

Events OnAnnotationCoordinatesChangeFinished OnAnnotationCoordinatesChange OnClickAnnotation OnGotFocusAnnotation OnLostFocusAnnotation OnPopupMenuAnnotation Refer to the Appendix for more detailed information about this plot object’s events.

! All events are on the main component interface and not on the sub-object interface.

Iocomp Components – Plot Pack Manual 65 Chapter 10 - Data Cursors

Chapter 10 - Data Cursors

The Cursor is a tool included with the Plot Pack components, which allows the user to display individual data points on the screen in the Plot Legend. This tool is available for use from the integrated toolbar, and can also be used by your program code through the built-in events and interfaces that support the cursor.

The cursor tool work differently depending on the type of component being used. All of the cursors display their data in a hint window next to the cursor. If you wish to display the cursor data in your own window or in an external control, refer to the available events at the end of this chapter.

The Plot pack components support an unlimited number of cursors through code and through the runtime property editor. One cursor is automatically added for easy use by the cursor toolbar button.

Cursor Types By default, the cursors are initially set as “Value X-Y” cursors, which in the iPlot component draws a line perpendicular to the X-Axis and displays the X and Y data point values for a particular channel. You can change the type of cursor either by right-clicking on the cursor at run-time or through code by accessing the Cursor Object. You can also change the labels in the popup menu for each cursor, customizing it for your particular application.

Value X-Y Cursor [ValueXY] This cursor style displays the current X and Y-Axis value for a data point in a particular channel. This example shows a data point on Channel #1 at X=40.0 and Y=2.0000.

FIGURE 10.1 Value X-Y Cursor Style

66 Iocomp Components – Plot Pack Manual Chapter 10 - Data Cursors

Value X Cursor [ValueX] This cursor style displays the current X-Axis value for a data point in a particular channel. This example shows a data point on Channel #1 at X=40.0.

FIGURE 10.2 Value X Cursor Style

Value Y Cursor [ValueY] This cursor style displays the current Y-Axis value for a data point in a particular channel. This example shows a data point on Channel #1 Y=2.0000.

FIGURE 10.3 Value Y Cursor Style

Iocomp Components – Plot Pack Manual 67 Chapter 10 - Data Cursors

Period Cursor [DeltaX] This cursor style displays the value of the distance between the two displayed cursors when measuring two data points along the X-Axis. This example shows a data point on Channel #1 at X=40.0 and Y=2.0000.

FIGURE 10.4 Period Cursor Style

Peak-Peak Cursor [DeltaY] This cursor style displays the value of the distance between the two displayed cursors when measuring two data points along the Y-Axis. This example shows a peak-to-peak distance value of 13.559.

FIGURE 10.5 Peak-Peak Cursor Style

68 Iocomp Components – Plot Pack Manual Chapter 10 - Data Cursors

Frequency Cursor [InverseDeltaX] This cursor style displays the current X and Y-Axis value for a data point in a particular channel. This example shows a data point on Channel #1 at X=40.0 and Y=2.0000.

FIGURE 10.6 Frequency Cursor Style

Adding and Removing Cursors To add a data cursor to the chart, simply execute the following method…

index = iPlot1.AddDataCursor

To delete a data cursor from the chart, simply execute the following method…

iPlot1.DeleteDataCursor(index)

To remove all data cursors from the chart, simply execute the following method…

iPlot1.RemoveAllDataCursors

The return value is an unique index for use in manipulating the object. After adding the object, you can set the properties of the data cursor, such changing the cursor style, the hint window font, hint orientation, etc.

[Note: Font properties in the example below will differ depending on your compiler]

If you are using Interpolation to draw the trace line, please note that the Data Cursors do not yet support the display of X or Y coordinate data for Interpolated trace lines. The X ! and Y coordinate data will reflect Straight Line Traces only.

Iocomp Components – Plot Pack Manual 69 Chapter 10 - Data Cursors

Data Cursor Example iPlot1.DataCursor(index).Style = ipcsValueXY iPlot1.DataCursor(index).MenuItemCaptionValueXY = "XY Coordinates" iPlot1.DataCursor(index).MenuItemVisibleValueX = False iPlot1.DataCursor(index).MenuItemVisibleValueY = False iPlot1.DataCursor(index).ChannelName = "Channel 1" iPlot1.DataCursor(index).FontColor = vbCyan

CursorXValue = iPlot1.DataCursor(index).ValueX CursorYValue = iPlot1.DataCursor(index).ValueY

Accessing Individual Cursor Properties There are many properties that can be used to customize the look and feel as well as the operation of the cursor in your application.

Controlling User Popup Menu By default, the popup menu allows users to change the style of the cursor. You can control the user selections that are available by using the “MenuItemCaption” and “MenuItemVisible” properties of the cursor object. The “MenuItemCaption” properties allow you to customize the label used to describe the type of cursor style available to the user. The “MenuItemVisible” properties allow you to customize whether a particular cursor style is available to the user.

Controlling Hints You can control the behavior of the cursor by using the available hint properties of the cursor object. The HintHideOnRelease property is useful if you only want the hint window to be visible when the user has clicked, and holds down the mouse button on a particular cursor. You can also choose to hide the hint permanently using the HintShow property so that you can show cursor data outside the component. Use the OnCursorChange event on the main plot interface to be notified that the cursor has changed position.

Controlling Cursor Pointers You can programmatically change the cursor positions by using the Pointer1Position and Pointer2Position properties. The Pointer2Position property is only valid for those cursors that use two pointers. iPlot Component Specific Notes If the cursor is in-between data points in a particular channel, then the cursor will display linear interpolated (y = mx + b) values. Also, the value displayed for each channel depends on which X and Y-Axes that channel is associated with.

70 Iocomp Components – Plot Pack Manual Chapter 10 - Data Cursors

FIGURE 10.7 iXYPlot Cursor

iXYPlot Component Specific Notes The iXYPlot Component’s cursor, if in ipcsValueXY mode, will display a crosshair cursor instead of a single line. This is due to the fact that there can be many different y solutions from any particular x value.

Cursor Events If you need to know when the user is moving the cursor tool on the DataView area, you can use the OnCursorChange event to detect this. You can then query the DataCursor object for the current Pointer1Position and Pointer2Position properties (depending on the Cursor Style) to determine the X and Y values for that channel under the cursor or to determine the calculated values from specialized cursor styles.

OnCursorChange(CursorIndex as Integer) iComponent.DataCursor(CursorIndex).Pointer1Position iComponent.DataCursor(CursorIndex).Pointer2Position

Properties ChannelName Color Enabled FontColor Font HintHideOnRelease HintOrientationSide HintPosition HintShow MenuItemCaptionDeltaX MenuItemCaptionDeltaY MenuItemCaptionInverseDeltaX MenuItemCaptionValueX MenuItemCaptionValueXY MenuItemCaptionValueY MenuItemVisibleDeltaX MenuItemVisibleDeltaY MenuItemVisibleInverseDeltaX MenuItemVisibleValueX MenuItemVisibleValueXY MenuItemVisibleValueY Name Pointer1Position Pointer2Position PopupEnabled Status Style UseChannelColor ValueX ValueY Visible Refer to the Appendix for more detailed information about this plot object’s properties.

Iocomp Components – Plot Pack Manual 71 Chapter 10 - Data Cursors

Methods None. Open for future expansion.

Events OnDataCursorChange OnGotFocusDataCursor OnLostFocusDataCursor OnPopupMenuDataCursor Refer to the Appendix for more detailed information about this plot object’s events.

! All events are on the main component interface and not on the sub-object interface.

72 Iocomp Components – Plot Pack Manual Chapter 11 - Limits

Chapter 11 - Limits

Limits (a.k.a. Process Windows) are objects that you can define and place on the chart. This is useful for showing a set of limits or process windows where data should be contained.

There are six types of Limits and Process Windows (referred to as Band Limits) available in the chart. Each limit is associated with an X-Axis and Y-Axis. Band Limits can be setup to be drawn as a filled band or two lines. You can create an unlimited number of limits and limit types per chart.

LineX This type of limit is a vertical line positioned at a specific X-Axis value, perpendicular to the X- Axis. You can modify the line style, color, and width. Do not use the line width to simulate a band limit as the line width is in pixels (not accurate for limit use), and the band limits use the actual axis values.

FIGURE 11.1 LineX Limit Style

LineX Limit

Iocomp Components – Plot Pack Manual 73 Chapter 11 - Limits

LineY This type of limit is a vertical line positioned at a specific Y-Axis value, perpendicular to the Y- Axis. You can modify the line style, color, and width. Do not use the line width to simulate a band limit as the line width is in pixels (not accurate for limit use), and the band limits use the actual axis values.

FIGURE 11.2 LineY Limit Style

LineY Limit

BandX This type of limit is a set of two lines or a filled-band positioned at two specific X-Axis values, perpendicular to the X-Axis. You can modify the starting X Value and ending X Value to create the band. You can also modify fill properties such as fill style and fill color. If you specify a fill style of clear, then the band will be comprised of two parallel lines.

FIGURE 11.3 BandX Limit Style

74 Iocomp Components – Plot Pack Manual Chapter 11 - Limits

BandY This type of limit is a set of two lines or a filled-band positioned at two specific Y-Axis values, perpendicular to the Y-Axis. You can modify the starting Y Value and ending Y Value to create the band. You can also modify fill properties such as fill style and fill color. If you specify a fill style of clear, then the band will be comprised of two parallel lines.

FIGURE 11.4 BandY Limit Style

PolyBandX This type of limit is a dynamic set of connected points (two X Values, and one Y Value), resulting in two lines or a filled-band perpendicular to the X-Axis. Use AddBandElement to add individual band elements to make up the entire band. Each band element will be connected to the previous and next band element to make up the band.

FIGURE 11.5 PolyBandX Limit Style

Iocomp Components – Plot Pack Manual 75 Chapter 11 - Limits

PolyBandY This type of limit is a dynamic set of connected points (two Y Values, and one X Value), resulting in two lines or a filled-band perpendicular to the Y-Axis. Use AddBandElement to add individual band elements to make up the entire band. Each band element will be connected to the previous and next band element to make up the band.

FIGURE 11.6 PolyBandY Limit Style

Adding and Removing Limits To add a data limit to the chart, simply execute the following method…

index = iPlot1.AddLimit

The return value is an unique index for use in manipulating the object. After adding the object, you can set the properties of the limit, such as changing the limit style, the limit fill (if applicable), and the limit color.

To remove a limit from the chart, simply execute the following method…

iPlot1.DeleteLimit(Index)

To remove all limits, simply execute the following method…

iPlot1.RemoveAllLimits

Single-Line Limit Examples iPlot1.Limit(index).Style = iplsLineY iPlot1.Limit(index).Color = vbRed iPlot1.Limit(index).LineStyle = psSolid iPlot1.Limit(index).Line1Position = 25 'Position on Y-Axis

iPlot1.Limit(index).Style = iplsLineX iPlot1.Limit(index).Color = vbRed iPlot1.Limit(index).LineStyle = psSolid iPlot1.Limit(index).Line1Position = 25 'Position on X-Axis

76 Iocomp Components – Plot Pack Manual Chapter 11 - Limits

Band Limit Examples iPlot1.Limit(index).Style = iplsBandY iPlot1.Limit(index).Color = vbRed iPlot1.Limit(index).FillStyle = bsDiagCross iPlot1.Limit(index).Line1Position = 25 'Position on Y-Axis iPlot1.Limit(index).Line2Position = 55 'Position on Y-Axis

iPlot1.Limit(index).Style = iplsBandX iPlot1.Limit(index).Color = vbRed iPlot1.Limit(index).FillStyle = bsDiagCross iPlot1.Limit(index).Line1Position = 25 'Position on X-Axis iPlot1.Limit(index).Line2Position = 55 'Position on X-Axis

Poly Band Limit Examples iPlot1.Limit(index).Style = iplsPolyBandY iPlot1.Limit(index).Color = vbRed iPlot1.Limit(index).FillStyle = bsDiagCross iPlot1.Limit(index).AddBandElement(25, 75, 45) '25: Position on X-Axis '75: Upper limit Y-Axis '45: Lower limit Y-Axis

iPlot1.Limit(index).AddBandElement(30, 85, 50) '30: Position on X-Axis '85: Upper limit Y-Axis '50: Lower limit Y-Axis

iPlot1.Limit(index).AddBandElement(35, 90, 50) '35: Position on X-Axis '90: Upper limit Y-Axis '50: Lower limit Y-Axis

iPlot1.Limit(index).AddBandElement(40, 80, 45) '40: Position on X-Axis '80: Upper limit Y-Axis '45: Lower limit Y-Axis

iPlot1.Limit(index).AddBandElement(45, 70, 40) '45: Position on X-Axis '70: Upper limit Y-Axis '40: Lower limit Y-Axis

iPlot1.Limit(index).Style = iplsPolyBandX iPlot1.Limit(index).Color = vbRed iPlot1.Limit(index).FillStyle = bsDiagCross iPlot1.Limit(index).AddBandElement(25, 75, 45) '25: Position on Y-Axis '75: Upper limit X-Axis '45: Lower limit X-Axis

iPlot1.Limit(index).AddBandElement(30, 85, 50) '30: Position on Y-Axis '85: Upper limit X-Axis '50: Lower limit X-Axis

iPlot1.Limit(index).AddBandElement(35, 90, 50) '35: Position on Y-Axis '90: Upper limit X-Axis '50: Lower limit X-Axis

iPlot1.Limit(index).AddBandElement(40, 80, 45) '40: Position on Y-Axis '80: Upper limit X-Axis '45: Lower limit X-Axis

iPlot1.Limit(index).AddBandElement(45, 70, 40) '45: Position on Y-Axis '70: Upper limit X-Axis '40: Lower limit X-Axis

Iocomp Components – Plot Pack Manual 77 Chapter 11 - Limits

To remove all band elements, use the ClearAllElements method…

iPlot1.Limit(index).ClearAllElements 'Remove All Band Elements

Properties Color Enabled FillStyle Line1Position Line2Position LineStyle LineWidth Name PopupEnabled Style UserCanMove Visible XAxisName YAxisName Refer to the Appendix for more detailed information about this plot object’s properties.

Methods AddBandElement ClearAllElements Refer to the Appendix for more detailed information about this plot object’s methods.

Events OnLimitLine1PositionChange OnLimitLine2PositionChange OnPopupMenuLimit Refer to the Appendix for more detailed information about this plot object’s events.

! All events are on the main component interface and not on the sub-object interface.

78 Iocomp Components – Plot Pack Manual Chapter 12 - Labels

Chapter 12 - Labels

The Label Objects hold text that can be used as a horizontal chart title, common stacked-axes vertical title, footer, etc. By default, one label object is added to the chart to hold the chart title. You can add any number of label objects to the Plot component and change their position and properties using our built-in property editor and visual layout manager.

Remember that it is easier to add labels and setup their properties using our built-in property editor. The examples here illustrate manipulating the object through code.

FIGURE 12.1 Example of Labels

Label Labels

For backward compatibility with older versions of our Plot Components, the first label cannot be removed. This is due to the fact that the first label is mapped to the depreciated title properties of the component. All Title properties such as TitleText, ! TitleFont, and TitleMargin are mapped to the first label object.

How to Add Labels To add a Label to the chart, simply execute the following method…

index = iPlot1.AddLabel

The return value is a unique index for use in manipulating the object. After adding the object, you can set the properties of the label, such as setting the object associated font properties or setting the caption.

Iocomp Components – Plot Pack Manual 79 Chapter 12 - Labels

[Note: Font properties in the example below will differ depending on your compiler]

Horizontal Label Example iPlot1.Labels(Index).Alignment = iahCenter iPlot1.Labels(Index).Caption = "Sample Chart X vs. Y" iPlot1.Labels(Index).Font = "Times New Roman" iPlot1.Labels(Index).Horizontal = True iPlot1.Labels(Index).MarginBottom = 0.25 iPlot1.Labels(Index).MarginLeft = 0 iPlot1.Labels(Index).MarginRight = 0 iPlot1.Labels(Index).MarginTop = 0.25

Vertical Label Example iPlot1.Labels(Index).Alignment = iahCenter iPlot1.Labels(Index).Caption = "Stacked Y-Axes" iPlot1.Labels(Index).Font = "Times New Roman" iPlot1.Labels(Index).Horizontal = False iPlot1.Labels(Index).MarginBottom = 0.25 iPlot1.Labels(Index).MarginLeft = 0 iPlot1.Labels(Index).MarginRight = 0 iPlot1.Labels(Index).MarginTop = 0.25

How to Remove Labels To remove a label, execute the DeleteLabel method, passing the unique index value of the label to delete. To delete all labels, execute the RemoveAllLabels method. Note that these methods are on the main component interface.

Properties Alignment Caption Enabled FontColor Font Height Horizontal MarginBottom MarginLeft MarginRight MarginTop Name PopupEnabled StartPercent StopPercent Visible Width ZOrder Refer to the Appendix for more detailed information about this plot object’s properties.

Methods None. Open for future expansion.

Events None. Open for future expansion.

80 Iocomp Components – Plot Pack Manual Chapter 13 - Visual Layout Manager

Chapter 13 - Visual Layout Manager

The Visual Layout Manger included in each Plot Pack component enables you to easily layout your chart plot objects with very little effort. The Layout Manager is available at design-time through our custom property editors or available to your application users at run-time with our run-time property editor.

The Layout Manger makes it possible to visually layout your chart without writing a single line of code and without using complicated properties. You can of course use your own programming code to make changes to the chart layout at runtime, but the Layout Manger makes it simple and easy to do visually.

FIGURE 13.1 Visual Layout Manager

To access the Visual Layout Manger, open up the property editor for the Plot Component and click on the “Layout” tab.

The Plot control on your form is represented by the blue rectangle with icons for all of the current layout objects contained within the control such as the X-Axis, Y-Axis, Data View, Legend, and Toolbar Layout Objects. The Data View Object is fixed in position and in size (it resizes to fill all available space) and all other objects move in relation to the Data View.

Iocomp Components – Plot Pack Manual 81 Chapter 13 - Visual Layout Manager

Tutorial How to Move Objects Click and hold down the left mouse button on the Y-Axis. Notice that the Y-Axis object turns from a gray background to a yellow background on your screen. FIGURE 13.2 Moving Y-Axis Object

Drag and drop the “Y-Axis 1” object in-between the Data View and “Legend 1”. Notice that a rectangle will move along with your cursor. This indicates that you are moving the object over valid positions that are available. FIGURE 13.3 Moving Y-Axis Object

82 Iocomp Components – Plot Pack Manual Chapter 13 - Visual Layout Manager

Release the mouse button to complete the move of the Y-Axis object. Notice that the Y- Axis object has moved to the position specified and all of the other objects have been repositioned to maximize the size of the Data View area. FIGURE 13.4 Y-Axis Object Moved in-between DataView and Legend

Resizing Plot Objects To resize a Plot Object, such as an axis, hold your mouse cursor over one of the ends of the object to be resized. Notice that the mouse cursor changes to a double arrow pointer, indicating that you are about to resize the Plot Object.

Hold down the left mouse button. Notice that the object is highlighted in yellow to indicate that you are resizing that particular object on your screen. FIGURE 13.5 Resizing Height of Y-Axis #2

Iocomp Components – Plot Pack Manual 83 Chapter 13 - Visual Layout Manager

Drag your mouse to resize the object. Notice that the object dynamically changes size as you resize it. Release the mouse button when finished.

FIGURE 13.6 Resizing Height of Y-Axis #2

Note: The only objects that can be resized at this time are the X and Y-Axis objects.

How to Stack Axes The Visual Layout Manger make it easy to stack multiple axes on top of one another.

To stack axes, first make sure that the axes to stack are sized so that they don’t overlap. If the axes overlap, then the stacking process will not work.

FIGURE 13.7 Stacking Y-Axis #1 and Y-Axis #2

84 Iocomp Components – Plot Pack Manual Chapter 13 - Visual Layout Manager

Drag and drop one of the axis objects on top of another axis that you wish to stack with.

FIGURE 13.8 Stacking Y-Axis #1 and Y-Axis #2

Release the mouse button and the two axes will stack, with all other plot objects readjusting.

FIGURE 13.9 Y-Axis #1 and Y-Axis #2 Stacked

Iocomp Components – Plot Pack Manual 85 Chapter 13 - Visual Layout Manager

Rotating X and Y-Axes To swap the positions of the X and Y-Axes, right-click on the Data View object and select “X-Y-Axes Reverse” . This will reverse the positions of all X and Y-Axes objects.

FIGURE 13.10 Y-Axis #1 and Y-Axis #2 Stacked

Reversing or Rotating Axes has no effect on DataView aligned Annotations. The reference values specified are always left to right (0-100) and bottom to top in relation to the Data View.

FIGURE 13.11 Rotated X and Y- Axes

86 Iocomp Components – Plot Pack Manual Chapter 14 - Adding Data

Chapter 14 - Adding Data

Adding Data to the Plot Pack components is a very easy and straightforward process. Since the channels in the chart are not required to be synchronous, you can simply add your data points in X/Y coordinate pairs as required.

There are currently four methods for adding data to the Plot Components.

If you will be adding data from unsynchronized events (such as from data acquisition hardware) and run into a problem where some data will cause other data to scroll off the screen, take a look at the multiple X and Y-Axis support. You can have each channel assigned to its own axes, independent of other channels. You can then add data in a synchronous or asynchronous manner as needed.

AddXY This method allows you to add data to the plot component in x and y data value pairs. This is the simplest method to use when adding data to the Plot Components. This method is compatible with both the iPlot and iXYPlot components.

Complete AddXY Example The following example assumes that you have placed a single iPlot component on your form along with a standard push button named “PlotButton”. When you initially create the plot object, it automatically adds one X-Axis, one Y-Axis, and one Channel for you by default.

Each example will plot 100 random Y data points with an increasing X value.

Visual Basic Private Sub PlotButton_Click() Dim x As Long Dim XData As Double Dim YData As Double

Forx=1To100 'Increment X Data XData = XData + 1

'Generate Random Y Data YData = Rnd(1) * 100

'Plot XY Data Pair iPlotX1.Channel(0).AddXY XData, YData Next x End Sub

Iocomp Components – Plot Pack Manual 87 Chapter 14 - Adding Data

Visual C++ [Disp Interface] //Place at top of cpp file #include "iplotx.h" #include "iplotaxisx.h" #include "iplotlegendx.h" #include "iplotchannelx.h" #include "iplottoolbarx.h" #include "iplotdataviewx.h" #include "iplotannotationx.h" #include "iplotlabelsx.h"

void CFormDlg::OnPlotButton() { double XData; double YData;

XData = 0; YData = 0;

for(int i=0; i<100; i++) { //Increment X Data XData = XData + 1;

//Generate Random Y Data YData = (rand()/(double)RAND_MAX)*100;

//Plot XY Data Pair m_iPlotX.GetChannel(0).AddXY(XData, YData); }; }

Visual C++ [High-Speed iDispatch Interface] //Place at top of cpp file #import "iPlotLibrary.tlb" named_guids #include "atlbase.h" extern CComModule _Module; using namespace iPlotLibrary;

void CFormDlg::OnPlotButton() { double XData; double YData; CWnd* m_Wnd; IUnknown* m_iUnknown; CComPtr iPlotX1;

//Get interface to Plot Component //Assuming that name of component on form is IDC_IPLOTX1 in //this example m_Wnd = GetDlgItem(IDC_IPLOTX1); m_iUnknown = m_Wnd->GetControlUnknown(); m_iUnknown->QueryInterface(__uuidof(iPlotLibrary::IiPlotX), \ (LPVOID*)&iPlotX1);

XData = 0; YData = 0;

88 Iocomp Components – Plot Pack Manual Chapter 14 - Adding Data

for(int i=0; i<1000000; i++) { //Increment X Data XData = XData + 1;

//Generate Random Y Data YData = (rand()/(double)RAND_MAX)*100;

//Plot XY Data Pair iPlotX1->Channel[0]->AddXY(XData, YData); }; }

C++ Builder #include //Place at top of cpp file

void __fastcall TForm1::PlotButtonClick(TObject *Sender) { double XData; double YData;

XData = 0; YData = 0;

for(int i=0; i<100; i++) { //Increment X Data XData = XData + 1;

//Generate Random Y Data YData = (random(100));

//Plot XY Data Pair iPlot1->Channel[0]->AddXY(XData, YData); }; }

Delphi/Kylix procedure TForm1.PlotButtonClick(Sender: TObject); var x : Integer; XData : Double; YData : Double; begin forx:=1To100do begin //Increment X Counter XData := XData + 1;

//Generate Random Data YData := Random(100);

//Plot XY Data Pair iPlot1.Channel[0].AddXY(XData, YData); end; end;

Iocomp Components – Plot Pack Manual 89 Chapter 14 - Adding Data

Internet Explorer [Client-Side, VBScript] Internet Explorer Plot Pack Example

FIGURE 14.1 Sample Output from Example

90 Iocomp Components – Plot Pack Manual Chapter 14 - Adding Data

Special ActiveX Example: When iterating through a large loop and access sub objects of the ActiveX plot component, it is more efficient to create a temporary variable to keep track of the sub object in memory instead of having to access it during each iteration of the loop.

In the example above, we go through a loop 100 times. We access the channel sub object 100 times for each AddXY method. There is a very small performance penalty when accessing the channel, which is magnified when looping, and can be noticeable with very large loops. To rectify this, we can sacrifice a small amount of memory to greatly speed up large loops. We will set a local variable to reference the channel sub-object only once, and then reuse the local variable in the loop.

In the following example, we will create a temporary variable to hold the channel sub object and will loop through 1,000,000 data points. You can flip between the method used in the example above and the example shown below to see the difference in speed. (Approximately 2x-4x faster using the local variable method shown below depending on your compiler).

Visual Basic Private Sub PlotButton_Click() Dim x As Long Dim XData As Double Dim YData As Double Dim TempChannel as iPlotChannelX

Set TempChannel = iPlotX1.Channel(0)

Forx=1To1000000 'Increment X Data XData = XData + 1 'Generate Random Y Data YData = Rnd(1) * 100 'Plot XY Data Pair TempChannel.AddXY XData, YData Next x End Sub

Iocomp Components – Plot Pack Manual 91 Chapter 14 - Adding Data

Visual C++ [Disp Interface] //Place at top of cpp file #include "iplotx.h" #include "iplotchannelx.h"

void CFormDlg::OnPlotButton() { double XData; double YData; CiPlotChannelX TempChannel;

XData = 0; YData = 0;

TempChannel = m_iPlotX1.GetChannel(0);

for(int i=0; i<1000000; i++) { //Increment X Data XData = XData + 1; //Generate Random Y Data YData = (rand()/(double)RAND_MAX)*100; //Plot XY Data Pair TempChannel.AddXY(XData, YData); }; }

Visual C++ [High-Speed iDispatch Interface] //Place at top of cpp file #import "iPlotLibrary.tlb" named_guids #include "atlbase.h" extern CComModule _Module; using namespace iPlotLibrary;

void CFormDlg::OnPlotButton() { double XData; double YData; CWnd* m_Wnd; IUnknown* m_iUnknown; CComPtr iPlotX1; CComPtr tempChannel;

tempChannel = iPlotX1->Channel[0];

XData = 0; YData = 0;

92 Iocomp Components – Plot Pack Manual Chapter 14 - Adding Data

for(int i=0; i<1000000; i++) { //Increment X Data XData = XData + 1; //Generate Random Y Data YData = (rand()/(double)RAND_MAX)*100; //Plot XY Data Pair tempChannel->AddXY(XData, YData); }; }

Internet Explorer [Client-Side, VBScript] Internet Explorer Plot Pack Example

Other Data Adding Methods The iPlot component has several other methods for adding data that are specific only to the iPlot component. These methods make it very easy to add data in real-time using the component’s built-in timer or the computer’s internal system clock, or by allowing you to pass various variant arrays directly to the channel object for easy addition.

Iocomp Components – Plot Pack Manual 93 Chapter 14 - Adding Data

AddYElapsedSeconds This method adds Y data that you specify, and Y data from an internal “seconds” counter. This is useful if you are acquiring data in real-time and wish to use the built-in seconds timer and you do not have access to independent time data from your data source.

iComponent.Channel(0).AddYElapsedSeconds(YData)

The time value added for the x-axis is calculated as the number of seconds that have elapsed since the date/time value of the ElapsedStartTime property. To set the ElapsedStartTime property to the current system time (i.e. Reset the Elapsed Time used by the AddYElapsedSeconds and AddYElapsedTime methods), execute the ! ResetElapsedStartTime method to set the ElapsedStartTime property to the current system time.

AddYElapsedTime This method adds Y data that you specify and Y data from an internal time counter. This is useful if you are acquiring data in real-time and wish to use the built-in timer and you do not have access to independent time data from your data source.

iComponent.Channel(0).AddYElapsedTime(YData)

DateTime Note: the X value that is used is in Date/Time format [i.e. 1 Day = 1, 1 hour = 1/24, 1 minute = 1/(24*60)]. Refer to the section on Date/Time formats for more information on using Date/Time values.

AddYNow This method adds Y data that you specify, and Y data from your computer’s internal system clock (Operating System’s Clock). This is useful if you are acquiring data in real- time and wish to use current system time and you do not have access to independent time data from your data source.

iComponent.Channel(0).AddYElapsedTime(YData)

DateTime Note: the X value that is used is in Date/Time format [i.e. 1 Day = 1, 1 hour = 1/24, 1minute = 1/(24*60)]. Refer to the section on Date/Time formats for more information on using Date/Time values.

If you have a service or program that automatically runs on your computer to synchronize your time with the NIST time computers via the internet, with your corporate network servers, or any other program that may modify your system clock, you may run into problems using this method. This is because the chart (and your actual data) expects time to increment properly. It is recommended that you do not use this method with such utilities, as there can be unpredictable results.

AddYArray This method adds data points from a single variant array, containing just y values. You will then specify a fixed x-interval between data points.

iComponent.Channel(0).AddXYArrays(XInterval, YDataArray)

94 Iocomp Components – Plot Pack Manual Chapter 14 - Adding Data

AddXYArray This method adds data points from a single variant array, containing both x and y values. The array must be two-dimensional with the first dimension containing X-coordinate data and the second dimension containing Y-coordinate data. Both dimensions must have the same number of elements (i.e. if the first dimension contains 100 elements, the second dimension must contain 100 elements), otherwise an exception will be generated.

iComponent.Channel(0).AddXYArrays(DataArray)

AddXYArrays This method adds data points from two variant arrays, each containing x and y values. The number of elements in each array must be identical (i.e. if XArray contains 100 elements, YArray must contain 100 elements), otherwise an exception will be generated)

iComponent.Channel(0).AddXYArrays(XArray, YArray)

AddEmpty This method sets a data point as an empty data point. An empty data point is a data point with no X or Y Value, only an index placeholder for the data point. Since this data point doesn’t have an X or Y Value, no Data Marker is shown and the trace line will not be drawn to this data point. This is useful for adding data point “placeholders” so that you can set the X and Y value of the data point at a later time.

Index = iPlot1.Channel(0).AddEmpty()

'You can later set the X and Y coordinates of this 'data point by using the DataX and DataY properties iPlot1.Channel(0).DataX(Index) = XValue iPlot1.Channel(0).DataY(Index) = YValue

iPlot1.Channel(0).DataX(Index) = 10.5 iPlot1.Channel(0).DataY(Index) = 57.4

See Chapter “Null Data and Empty Data Handling” for more information.

AddXNull [iPlotX component only] This method adds a data point at a specified X data point. The Y value will be set to Null.

Iocomp Components – Plot Pack Manual 95 Chapter 14 - Adding Data

iComponent.Channel(0).AddXNull(XData) iComponent.Channel(0).AddXNull(10.5)

See Chapter “Null Data and Empty Data Handling” for more information.

AddNull [iXYPlotX component only] This method adds a data point as a null data point (both X and Y coordinates). You must first add a data point using AddXY using dummy data, obtain the index of that data point, and then pass that index to set the data point to null.

Index = iPlot1.Channel(0).AddNull()

See Chapter “Null Data and Empty Data Handling” for more information.

Modifying/Reading Data If you need to modify or read a data point after adding it to a channel, you can use the following property and/or methods to change the X or Y value of a data point. You will need to know the index of the data point to make this modification(the index was passed back by the AddXY and other add data functions when you were adding data points)…

Visual Basic 'Add a data point and get the data point's Index Index = iComponent.Channel(0).AddXY(10.5, 20.5) 'Change the data point's X and Y Value iComponent.Channel(0).DataX(Index) = 11 iComponent.Channel(0).DataY(Index) = 21 'Read the data point's X and Y Value DataPointXValue = iComponent.Channel(0).DataX(Index) DataPointYValue = iComponent.Channel(0).DataY(Index)

Visual C++ //Add a data point and get the data point's Index Index = m_iComponent.GetChannel(0).AddXY(10.5, 20.5); //Change the data point's X and Y Value m_iComponent.GetChannel(0).SetDataX(Index, 11); m_iComponent.GetChannel(0).SetDataY(Index, 21); //Read the data point's X and Y Value DataPointXValue = m_iComponent.GetChannel(0).GetDataX(Index); DataPointYValue = m_iComponent.GetChannel(0).GetDataY(Index);

Borland Delphi //Add a data point and get the data point's Index Index := iComponent.Channel[0].AddXY(10.5, 20.5); //Change the data point's X and Y Value iComponent.Channel[0].DataX[Index] := 11; iComponent.Channel[0].DataY[Index] := 21; //Read the data point's X and Y Value DataPointXValue := iComponent.Channel[0].DataX[Index]; DataPointYValue := iComponent.Channel[0].DataY[Index];

96 Iocomp Components – Plot Pack Manual Chapter 14 - Adding Data

Borland C++ Builder //Add a data point and get the data point's Index Index = iComponent->Channel[0]->AddXY(10.5, 20.5); //Change the data point's X and Y Value iComponent->Channel[0]->DataX[Index] = 11; iComponent->Channel[0]->DataY[Index] = 21; //Read the data point's X and Y Value DataPointXValue = iComponent->Channel[0]->DataX[Index]; DataPointYValue = iComponent->Channel[0]->DataY[Index];

If you are using the iPlot component, you can also use a special method on the channel called GetYInterpolated. If you know a X value, then you can query the component for the corresponding Y value of a data point at the X value. Since double values are not precise, the Y value returned will be interpolated using the trace line drawn between a data point before and after the given X value.

YValue = iComponent.Channel(Index).GetYInterpolated(XValue)

Note: this method does not exist on the iXYPlot component since there can be many numerous solutions to any given X value.

Running Y-Value Min, Max, and Mean The Channel objects have three specialized properties that provide the following information about the channel without requiring extensive calculations by the component…

• RunningYMax • RunningYMin • RunningYMean

These values represent the Maximum Y, Minimum Y, and Mean Y values in the specified channel. Since these values are calculated as you add data, accessing these values is very quick since calculation of the max, min, and mean do not have to be done on every query.

'Use these values to get the running mean of the corresponding values 'This method is quick because it is calculated during every addition 'of a data point instead of every time the value is checked YMaxValue = iComponent.Channel(Index).RunningYMax YMinValue = iComponent.Channel(Index).RunningYMin YMeanValue = iComponent.Channel(Index).RunningYMean

The drawback to using these values is that if you change previous data points, these values will no longer be valid. To refresh these values if you change previous data points, call GetYMax, GetYMin, and/or GetYMean to force a recalculation of these values. You can use the GetYMax, GetYMin, and GetYMean values if you wish to have these values recalculated every time, but you will see a performance decrease due to the overhead.

'Use these values to force a recalculation for every call YMaxValue = iComponent.Channel(Index).GetYMax YMinValue = iComponent.Channel(Index).GetYMin YMeanValue = iComponent.Channel(Index).GetYMean

Iocomp Components – Plot Pack Manual 97 Chapter 14 - Adding Data

If you are utilizing Empty or Null data points, the RunningYMean value will not be ! correct, as it does not exclude these values from the Mean calculation.

Empty and Null Data Points In some situations, you may want to add a data point but not specify its X and/or Y Value. When a data point is missing it’s X and/or Y value, the data point is ignored by the Plot component when drawing the trace line. This results in a trace line between two valid data points and ignoring the empty data point.

In contrast, null data points create a “break” in the trace line.

To add an empty data point, use the AddXEmpty if you are using the iPlot component to add an empty data point with an X value and an empty Y value. Use the AddEmpty method if you are using the iXYPlot component to add an empty data point with no X or Y value. You can then use the DataX and/or DataY properties to specify the data point X and/or Y values at a later time.

'Add an empty data point to the iPlot component Index = iComponent.Channel.AddXEmpty(10.5) 'Specify the X coordinate

'Add an empty data point to the iXYPlot component Index = iComponent.Channel.AddEmpty()

See Chapter “Null Data and Empty Data Handling” for more information.

98 Iocomp Components – Plot Pack Manual Chapter 15 - Cartesian Axes

Chapter 15 - Cartesian Axes

Cartesian Axes are axes that are contained within the Data View Plot Are. You can configure an axis to be Cartesian by setting the CartesianStyle property of the Axis to either Cartesian Master or Cartesian Child.

Master Cartesian Axes Each Cartesian Axis is displayed within the Bounds of the DataView area (area where Channels and Grid Lines are drawn). Overlapping Cartesian Axes automatically have their tick labels hidden if they overlap another axis. The above chart was modified as follows…

‘X and Y-Axes configured to be Master Cartesian Axis iComponent1.XAxis(0).CartesianStyle = ipcsMaster iComponent1.YAxis(0).CartesianStyle = ipcsMaster ‘X & Y-Axes Min property set to one half of Span so that 0 origin ‘is in the center of the DataView iComponent1.XAxis(0).Min = -iComponent1.XAxis(0).Span / 2 iComponent1.YAxis(0).Min = -iComponent1.YAxis(0).Span / 2

FIGURE 15.1 Master Cartesian Axes

Master Cartesian Axes

Iocomp Components – Plot Pack Manual 99 Chapter 15 - Cartesian Axes

Child Cartesian Axes This type of Axis is subordinate to the position of a Master Cartesian Axis. All Master Cartesian Axes are positioned in the center of the DataView (Vertically Centered if an X-Axis, Horizontally Centered if a Y-Axis. Reverse this if you have chosen the XYAxisReverse Option)

Each Child Cartesian Axis is positioned relative to a position on the configured Master Cartesian Axis by using the CartesianChildRefAxisName and CartesianChildRefValue. Whenever the Master Cartesian Axis is scrolled, the Children Cartesian Axis configured for that Master Cartesian Axis will also scroll since they are “tied” to a fixed position on the Master Cartesian Axis.

FIGURE 15.2 Example of Two Master Cartesian Axes and one Child Y-Axis tied to Position 25 on the X-Axis

Master Cartesian Axes

Child Cartesian Axes

For example, to configure a Child Cartesian Y-Axis and have it tied to the Master Cartesian Y- Axis, do the following…

‘X-Axis and First Y-Axis configured to be Master Cartesian Axis iComponent1.XAxis(0).CartesianStyle = ipcsMaster iComponent1.YAxis(0).CartesianStyle = ipcsMaster ‘Second Y-Axis configured to be Child Cartesian Axis of X-Axis iComponent1.YAxis(1).CartesianStyle = ipcsChild iComponent1.YAxis(1).CartesianChildRefAxisName = iComponent1.XAxis(0).Name

100 Iocomp Components – Plot Pack Manual Chapter 15 - Cartesian Axes

‘Fix Second Y-Axis to a position on the X-Axis iComponent1.YAxis(1).CartesianChildRefValue = 25 ‘Color Child Axis differently from other Axes iComponent1.YAxis(1).LabelsFontColor = &HA0A0A0 iComponent1.YAxis(1).ScaleLinesColor = &HA0A0A0 ‘X & Y-Axes Min property set to one half of Span so that 0 origin ‘is in the center of the DataView iComponent1.XAxis(0).Min = -iComponent1.XAxis(0).Span / 2 iComponent1.YAxis(0).Min = -iComponent1.YAxis(0).Span / 2

Iocomp Components – Plot Pack Manual 101 Chapter 16 - Translation

Chapter 16 - Translation

Translation in the Plot Pack is handled by providing a list of English strings and their translations to the Plot Pack either through our design-time property editor or dynamically at runtime through code.

FIGURE 16.1 German Translation of Run-Time Property Editor

Whenever a string is drawn on either the component, tool-tips within the component, right-click context- sensitive menus, or in the run-time property editor, the list of translation strings will be reviewed and any appropriate translations will be substituted, as seen above.

Translations can also be used to change fixed strings within the component to whatever you deem necessary for your application.

Translations are performed on entire strings, not sub-strings. This means that we only look at the entire string being drawn on the screen, not the individual words that make up the string. For example, if you provide a translation of the string ‘Y-Axis” to be “Y-Achse”, the string “Y-Axis 1” will not be translated since the two strings, “Y-Axis” and “Y-Axis 1” are not exactly the same.

Also, understand that Plot Objects automatically have names and titles assigned to themselves (such as each channel is named “Channel 1”, “Channel 2”, “Channel 3”, etc.). Translations should not be used to translate these strings as these strings can be manipulated through the channel object properties such as…

iComponent1.Channel(0).Title = “Signale 1”

Translations should only be used for fixed strings in the component and the run-time property editor where you do not have the ability to change them through properties already in the control.

Several “templates” with lists of English-Strings within a particular version or release of our component are provided on our website at http://www.iocomp.com. You can also find sample translations provided by other customers like yourself available for download.

102 Iocomp Components – Plot Pack Manual Chapter 16 - Translation

FIGURE 16.2 Design-Time Property Editor Showing Loaded Translation Strings

Remember that translations are not case sensitive. Also remember that translations are performed on complete strings and not sub-strings.

Iocomp Components – Plot Pack Manual 103 Chapter 17 - Null Data Handling

Chapter 17 - Null Data Handling

By default, the Plot Pack components are setup to draw a trace line between every point on the chart in the order that they are added to the channel. The Null Data handling features allows you to specify certain Y data values as null data points, preventing the chart from connecting these data points to actual data points.

This feature is typically used in data acquisition hardware applications where you lose connection with the hardware, but want to show on the chart that no data was collected at a particular X (usually Time Axis value) and you have an undefined Y value (a.k.a. Null Data Point).

For example, notice the break in the trend line between the 4th and 6th data points. The 5th data point was plotted with a null Y value, so it does not show up in the chart and no line is drawn through that data point.

6th Point FIGURE 17.1 Example Diagram of a Null Data Point

4th Point

Y-Axis Null Y Data Point Added at This X Value (5th point)

X-Axis

Adding a Null Y Data Point at a Specific X Data Point (iPlot Only) The AddXNull() method is used to add a specified X data point with the corresponding Y data point being null (i.e. undefined). Simply pass the X value (e.g. 2.56)

iComponent.Channel(0).AddXNull(2.56)

Adding a Null X & Y Data (iXYPlot Only) The AddNull() method is used to add a data point with both an X and Y null value.

iComponent.Channel(0).AddNull()

Setting a Null Y Data Point at a Specific X Data Point The DataNull() method is used to change a Y data point to a null value for an X/Y data point pair that has already been plotted on the chart. Simply pass the X value (e.g. 2.56)

iComponent.Channel(0).DataNull(2.56)

104 Iocomp Components – Plot Pack Manual Chapter 17 - Null Data Handling

Full Source Example The following examples assume you have placed an iPlot Component on your form and have placed a simple pushbutton named “PlotButton” on your form. The example will plot 50 random data points with some random Null Data points for illustrative purposes.

FIGURE 17.2 Sample Output from Example

Example: Visual Basic Private Sub PlotButton_Click() Dim x As Long Dim XData As Long Dim YData As Long

Forx=1To50 XData = XData + 2 YData = Rnd(1) * 100 '85% of the time plot the X and Y Data Value '15% of the time plot the X Value and Y as null If Rnd(1) < 0.85 Then 'Plot X and Y Data Pair iPlotX1.Channel(0).AddXY XData, YData Else 'Plot X Data and Y Null Data iPlotX1.Channel(0).AddXNull XData End If Next x End Sub

Iocomp Components – Plot Pack Manual 105 Chapter 17 - Null Data Handling

Example: Visual C++ [Disp Interface] void CFormDlg::OnPlotButton() { double XData; double YData;

XData = 0; YData = 0;

for(int i=0; i<50; i++) { XData = XData + 2; YData = (rand()/(double)RAND_MAX)*100;

//85% of the time plot the X and Y Data Value //15% of the time plot the X Value and Y as Null if ((rand()/(double)RAND_MAX) < 0.85) { //Plot X and Y Data Pair m_iPlotX1.GetChannel(0).AddXY(XData, YData); } else { //Plot X Data and Y Null Data m_iPlotX1.GetChannel(0).AddXNull(XData); } }; }

Example: Visual C++ [High-Speed iDispatch Interface] //Place at top of cpp file #import "iPlotLibrary.tlb" named_guids #include "atlbase.h" extern CComModule _Module; using namespace iPlotLibrary;

void CFormDlg::OnPlotButton() { double XData; double YData; CWnd* m_Wnd; IUnknown* m_iUnknown; CComPtr iPlotX1;

XData = 0; YData = 0;

106 Iocomp Components – Plot Pack Manual Chapter 17 - Null Data Handling

for(int i=0; i<50; i++) { XData = XData + 2; YData = (rand()/(double)RAND_MAX)*100;

//85% of the time plot the X and Y Data Value //15% of the time plot the X Value and Y as Null if ((rand()/(double)RAND_MAX) < 0.85) { //Plot X and Y Data Pair iPlotX1->Channel[0]->AddXY(XData, YData); } else { //Plot X Data and Y Null Data iPlotX1->Channel[0]->AddXNull(XData); } };

}

Example: Delphi/Kylix procedure TForm1.PlotButtonClick(Sender: TObject); var x : Integer; XData : Double; YData : Double; begin forx:=1To50do begin XData := XData + 2; YData := Random(100);

//85% of the time plot the X and Y Data Value //15% of the time plot the X Value and Y as Null If Random(11) < 8.5 then //Plot XY Data Pair iPlot1.Channel[0].AddXY(XData, YData) else //Plot X Data and Y Null Data iPlot1.Channel[0].AddXNull(XData); end; end; end;

Iocomp Components – Plot Pack Manual 107 Chapter 17 - Null Data Handling

Example: C++ Builder #include //Place at top of cpp file

void __fastcall TForm1::PlotButtonClick(TObject *Sender) { double XData; double YData;

XData = 0; YData = 0;

for(int i=0; i<50; i++) { XData = XData + 2; YData = (random(100));

//85% of the time plot the X and Y Data Value //15% of the time plot the X Value and Y as Null if (random(11) < 8.5) { //Plot X and Y Data Pair iPlot1->Channel[0]->AddXY(XData, YData); } else { //Plot X Data and Y Null Data iPlot1->Channel[0]->AddXNULL(XData); } }; }

Example: VB.Net Private Sub PlotButton_Click() Dim x As Long Dim XData As Long Dim YData As Long

Forx=1To50 XData = XData + 2 YData = Rnd(1) * 100

'85% of the time plot the X and Y Data Value '15% of the time plot the X Value and Y as null If Rnd(1) < 0.85 Then 'Plot X and Y Data Pair iPlotX1.Channel(0).AddXY XData, YData Else 'Plot X Data and Y Null Data iPlotX1.Channel(0).AddXNull XData End If Next x End Sub

108 Iocomp Components – Plot Pack Manual Chapter 17 - Null Data Handling

Example: C#.NET Private Sub PlotButton_Click() Dim x As Long Dim XData As Long Dim YData As Long

Forx=1To50 XData = XData + 2 YData = Rnd(1) * 100

Example: Internet Explorer [Client-Side, VBScript] Internet Explorer Plot Pack Example

Iocomp Components – Plot Pack Manual 109 Chapter 18 - User Interface Control

Chapter 18 - User Interface Control

This chapter will cover using the User Interface controls that included with the Plot Pack. These control objects are available to your end user at runtime while using your compiled application.

The main user interfaces in the Plot Pack components that are available at runtime for the application user are:

The Built-in Toolbar The toolbar provides quick and easy to use control over the function of the chart by your end user at runtime in your application. All functions are implemented inside of the chart without the need to implement these in your own application code.

Button Meaning Resume Button: Resumes tracking on ALL axes Pause Button: Pauses tracking for ALL axes Axes Mode Buttons: Changes the mode that the axes are in when using the mouse. The first icon puts the axes in scroll mode. The second icon puts the

axes in zoom mode. Zoom In/Out Buttons: Zooms ALL axes in our out according to the ZoomInOutFactor property.. Select Button: Used for selecting items in the data view area. Generates events that can be used by the programmer to react to selection of items such as data points, annotations, areas of the data view, etc. Zoom Box Button: Allows the user to draw a "Zoom Box" on the DataView area to zoom ALL axes. Cursor Button: Show or hide all data cursors. Values for each channel are displayed in a hint window next to the cursor(s). Edit Button: Brings up the Run-Time property editor for the user to change most control properties. Copy Button: Copies the current component image to the clipboard. Save Button: Brings up a dialog to allow the user to save chart data to currently supported file types. Print Button: Allows user to print image of chart to printer. Table 18.1

Scrollable and Zoomable Axes All X and Y-Axes can be scrolled or zoomed by the user at runtime, even while data is being plotted to the chart.

By default, the chart is set into “Scroll Mode” . This means that when a user clicks on an axis, holds down the mouse button, and drags the cursor, that axis will scroll up or down depending on the user’s direction of movement.

110 Iocomp Components – Plot Pack Manual Chapter 18 - User Interface Control

When the user selects “Zoom Mode” from the toolbar, clicking and dragging the axis will cause the axis scale to zoom in our out, depending on the user’s direction of movement (Up Zooms In, Down Zooms Out, Left Zooms Out, Right Zooms In).

Whenever an axis is scrolled or zoomed, tracking on that axis will pause until restarted. You can

pause or resume tracking on all axes by using the Resume and Pause Buttons, or by right-clicking on an individual axis and toggling “Tracking Enabled”.

Zooming Tools There are three tools available to the user to zoom all axes at the same time…

Zoom In Button: this tool will zoom all axes according to the ZoomInOutFactor property. Zoom Out Button: this tool will de-zoom all axes according to the ZoomInOutFactor property. Zoom Box Button: this tool will allow a user to click and drag out a box on the DataView area. All axes will be zoomed to display this selected area. Table 18.2

To reset the zoom, click on the Resume Button . To accept the modified zoom of the axis, right-click on the axis and select “Use New Values”.

Select Tool The select tool is used by the application end-user to select items in the data view area at runtime, such as annotations, data points, etc.

Cursor Tool The cursor tool hides or shows all available cursors. See the chapter on the Cursor for more detailed information.

Context Sensitive Right-Click Menus (Popup Menus) Each object in the Plot Component has it’s own context sensitive right-click menu. The available options depend on the object being selected.

Axis Object You can resume or pause tracking on an individual axis by right-clicking on the axis and selecting “Tracking Enabled”

If the user has zoomed or scrolled the axis, the option “Use New Values” will be available. This will change the properties of the axis to use the new Min and Span values that correspond to the scrolled or zoomed axis.

The edit menu item will allow the user to bring up the runtime property editor for this object.

Iocomp Components – Plot Pack Manual 111 Chapter 18 - User Interface Control

DataView Object Right-Clicking on the DataView will allow the user to bring up the runtime property editor for this object.

Toolbar Object Right-Clicking on the Toolbar will allow the user to bring up the runtime property editor for this object.

Legend Object Right-Clicking on the Legend will allow the user to bring up the runtime property editor for the selected channel.

DataCursor Object Right-Clicking on a Data Cursor will allow the user modify the properties and functionality of the selected Data Cursor object.

Runtime Property Editor The runtime property editor allows your application user to have complete control over the plot component control at runtime. Some features are disabled in the runtime property editor, such as adding and deleting axes or channels, since these functions are to be handled by the application’s code and may lead to problems and program errors at runtime.

You can disable the Popup Menus on each individual object by using the Enabled and PopupEnabled properties of each plot object. For example, to keep the application user from scrolling the X-Axis, you can set the Enabled property of the X-Axis to FALSE (iComponent.XAxis(0).Enabled = FALSE). This will prevent the user from interacting with the X-Axis with either the mouse or keyboard input devices.

The Runtime Property allows the user to make changes to almost all aspects of the control during execution such as modifying axes properties, changing channel properties, using the Visual Layout Manager, etc.

There are two ways that your application user can directly access the Runtime Property Editor at runtime…

Right-Click on Plot Object When a user right-clicks on a Plot Object and selects “Edit…”, the runtime property editor will be displayed along with the particular Plot Object that was selected (Such as The X-Axis or the particular channel selected in the Legend).

You can prevent the user from being able to bring up the runtime property editor through right-clicks by setting the UserCanEditObjects property to FALSE.

112 Iocomp Components – Plot Pack Manual Chapter 18 - User Interface Control

Toolbar Runtime Property Editor Button

The Toolbar Runtime Property Editor Button brings up the runtime property editor for the entire plot component control.

iComponent1.Toolbar(0).ShowEditButton = FALSE

You can prevent the user from being able to bring up the runtime property editor from the toolbar by setting the ShowEditButton property to FALSE

You will notice that the Runtime Property Editor is missing the OK, Apply, and Cancel button. When changes are made by your application’s end-user, the changes are immediately reflected in the Plot Component.

FIGURE 18.1 Run-Time Property Editor Showing Channel Tab missing buttons.

Preventing or Disabling UI Interaction You can disable or enable the following on the component as a whole or on a specific plot object as needed.

Disabling All UI Interaction on a Plot Object Set the Enabled property on each Plot Object, such as the Axis, to prevent scrolling, the legend to prevent selection, etc. All plot objects support the Enabled property, but some objects don’t accept user interaction at this time (such as limits) so this property is ignored.

iComponent.XAxis(0).Enabled = False iComponent.YAxis(0).Enabled = False iComponent.Legend(0).Enabled = False

Iocomp Components – Plot Pack Manual 113 Chapter 18 - User Interface Control

Disabling Popup Menu on a Plot Object or On Entire Component Set the PopupEnabled property on each Plot Object, such as the Axis, to prevent the user from bringing up the Popup Menu. All plot objects support the PopupEnabled property, but some objects don’t accept user interaction at this time (such as limits) so this property is ignored. The main plot interface supports the UserCanEditObjects which disables all run-time property access by the application user, but does not disable all popup menus.

iComponent.UserCanEditObjects = False iComponent.XAxis(0).Enabled = False iComponent.YAxis(0).Enabled = False iComponent.Legend(0).Enabled = False

By default, the ADD and REMOVE buttons on the Channels tab are hidden. This is to prevent your end user from unexpectedly removing channels which could result in exceptions being generated in your code. You can force these buttons to be visible and allow your user to add and remove channels by setting the UserCanAddRemoveChannels property to TRUE. This property is located on the main component interface.

Special User Events Several events are available for use when interacting with your end users, and to either override their actions or cancel their actions.

OnBeforeLoadProperties OnAfterLoadProperties These events can be used to perform actions either before or after a user (or your own code) instructs the component to load properties from a saved file. You

OnBeforeZoomBox This event can be used to perform actions before a zoom box zooms the axes. You will have the opportunity to cancel the zoom if necessary.

OnAnnotationCoordinatesChange This event can be used to perform actions every time a moveable annotation changes position within the chart.

OnClickAnnotation OnClickDataPoint This event can be used to perform actions every time a clickable Annotation or Data Point has been clicked by your end user. The index of the clicked annotation or data point is provided.

OnAnnotationCoordinatesChangeFinished This event can be used to perform actions when a user has finished moving a moveable annotation, and has released the mouse button.

114 Iocomp Components – Plot Pack Manual Chapter 18 - User Interface Control

OnBeforePrint OnAfterPrint These events can be used to perform actions either before or after the chart is printed using our built-in printing facilities. This event is useful for those times you want to change properties of the chart before its image is sent to the printer, such as changing chart colors for black and white printers, etc.

OnXAxisMinChange OnYAxisMinChange These events can be used to perform actions whenever an axis min changes due to the user scrolling the axes manually or whenever the built-in tracking system scrolls the chart. The index of the axis changed is provided.

OnXAxisSpanChange OnYAxisSpanChange These events can be used to perform actions whenever an axis span changes due to the user zooming the axes manually or whenever the built-in tracking system scales the chart. The index of the axis changed is provided.

OnGotFocusAnnotation OnGotFocusChannel OnGotFocusDataCursor OnGotFocusDataView OnGotFocusLegend OnGotFocusXAxis OnGotFocusYAxis OnLostFocusAnnotation OnLostFocusChannel OnLostFocusDataCursor OnLostFocusDataView OnLostFocusLegend OnLostFocusXAxis OnLostFocusYAxis These events can be used to perform actions whenever a user sets focus on one of the Plot component’s plot objects. The index of the focused object is provided.

OnPopupMenuChannel OnPopupMenuXAxis OnPopupMenuYAxis OnPopupMenuToolBar OnPopupMenuLegend OnPopupMenuLimit OnPopupMenuAnnotation These events can be used to perform actions whenever a user brings-up one of our right-click, context-sensitive popup menus. . You will have the opportunity to cancel the popup menu if desired. The event passes the current screen X and Y pixel coordinates so that you can replace our popup menu with your own popup.

Iocomp Components – Plot Pack Manual 115 Chapter 19 - Tracking

Chapter 19 - Tracking

Tracking is a general term for the Auto-Scale and Auto-Scrolling features of the Plot Pack. These features pertain to how the axes react to the addition of new data to the chart with respect to the sizing of the span of the axes and the position of the axes with respect to this new data. Tracking Data is information from the channel, regarding newly added data points, that is passed to the axes so that they can adjust according to your needs.

The Plot Pack Channel and Axes objects support a feature called Tracking. Whenever a channel draws data to the DataView window, it sends Tracking Data to its associated X and Y-Axes. This tracking data tells the axis where new data is being plotted so that the axis can scroll or adjust it various sizing properties (Min, Max, and Span) to keep the newly added data in view.

FIGURE 19.1 Channel Diagram of Transmission of Tracking Data from Channel to Axes whever data is added. Tracking Data Tracking Data

X-Axis Y-Axis

By default, the Plot Components Axes and Channel Tracking Settings are setup as follows…

X-Axis is setup for Smooth Scrolling. Whenever new data is added to the chart (assume data is added from left to right), the X-Axis will smoothly scroll to keep the most recent data in view.

iComponent.Xaxis(0).TrackingStyle = iptsScrollSmooth

Y-Axis is setup for Scale Min Max Adjust. The axis will scale the Min and Span properties to keep the new tracking data in view.

iComponent.YAxis(0).TrackingStyle = iptsScaleMinMax

All Channels are set to have their tracking data sent to their associated axes

iComponent.Channel(0).TrackingStyle = iptsScrollSmooth

All Axes have their Tracking enabled so that they will adjust to new tracking data from the channels.

iComponent.Xaxis(0).TrackingEnabled = TRUE iComponent.YAxis(0).TrackingEnabled = TRUE

You can independently setup your own scaling and tracking options for each axis and channel if you wish if the default settings do not fit your needs. The next few sections will discuss the different AutoScale and Tracking options that are available…

116 Iocomp Components – Plot Pack Manual Chapter 19 - Tracking

1-2-5 Rule: This is a feature of the AutoScale capability built into the axes of all Plot Pack components. The rule has been designed to provide major tick labels that are “human readable”. In studies, most people like to see numbers increment by numbers that are multiples of 1, 2, or 5. For example, on a scale that is between 0 and 100, people like to see a scale that increments like 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, and 100. If there is not enough room on the chart, then the next best “Human Readable” format is 0, 20, 40, 60, 80, 100. A scale of 0, 17, 33, 50, 67, 83, and 100 would not fit into the 1-2-5 rule, and wouldn’t look good to a human anyway. The 1-2-5 Rule will ensure that the scales always look professional. Refer to the AutoLabel and AutoScale Chapter for more information on the 1-2-5 Rule.

Tracking Styles There are five different styles that can be set on each axis that control how the axes are Auto- Scaled when new tracking data is received from each channel. All axes support the 1-2-5 rule which provides “human readable” scales. See the chapter on AutoScale and AutoLabel for more information on the automatic scaling and label features of the Plot Pack.

Scale Min Max [Y-Axis Default] This tracking mode will adjust the min and span properties on the axis to ensure that new data being added to the channel is kept in the visible DataView area. This is generally used with the Y-Axis for Strip Chart applications.

iComponent.XAxis(0).TrackingStyle = iptsScaleMinMax iComponent.YAxis(0).TrackingStyle = iptsScaleMinMax

Scale Max This tracking mode will adjust only the max properties on the axis to ensure that new data being added to the channel is kept in the visible DataView area. If tracking data indicates that the data is below the min property of the axis, then the min value will not be changed.

iComponent.XAxis(0).TrackingStyle = iptsScaleMax iComponent.YAxis(0).TrackingStyle = iptsScaleMax

Scale Min This tracking mode will adjust only the min properties on the axis to ensure that new data being added to the channel is kept in the visible DataView area. If tracking data indicates that the data is above the max property of the axis, then the max value will not be changed.

iComponent.Xaxis(0).TrackingStyle = iptsScaleMin iComponent.Yaxis(0).TrackingStyle = iptsScaleMin

Iocomp Components – Plot Pack Manual 117 Chapter 19 - Tracking

Scroll Smooth [X-Axis Default] If the data is off axis, then this tracking mode will adjust the axis to show the new tracking data at the end of the scale. This style is generally used with the X-Axis for Strip Chart applications. Smooth Scroll works in one direction only. You can add data in ever increasing or ever increasing x-values, but you cannot change direction.

iComponent.Xaxis(0).TrackingStyle = iptsScrollSmooth iComponent.Yaxis(0).TrackingStyle = iptsScrollSmooth

Scroll Page If the data is off axis, then this tracking mode will adjust the axis in discrete blocks (will show next major tick) to show the new tracking data at the end of the scale. This style is generally used with the X-Axis for Strip Chart applications.

iComponent.Xaxis(0).TrackingStyle = iptsScrollPage iComponent.Yaxis(0).TrackingStyle = iptsScrollPage

Expand Collapse This tracking mode will adjust the min and span properties on the axis to ensure that all data being added to the channel is kept in the visible DataView area. It will also ensure that the all visible data is expanded to the maximum viewing size within the data view by sizing the span up and down and the data changes in the viewable area.

Warning!: This style is not recommended for all situations because the routines used to achieve this effect can place a large load on the computer’s processor under certain situations.

iComponent.Xaxis(0).TrackingStyle = iptsExpandCollapse iComponent.Yaxis(0).TrackingStyle = iptsExpandCollapse

118 Iocomp Components – Plot Pack Manual Chapter 19 - Tracking

Tracking Align First Styles There are four styles that can be used to instruct the axes on how to align themselves when the first data point is plotted to the chart. You can have the data begin plotting on one extreme side of the chart or another depending on this setting.

Min This style adjusts the axis to show the first data point on the beginning of the scale. iComponent.Xaxis(0).TrackingAlignFirstStyle = ipafsMin iComponent.Yaxis(0).TrackingAlignFirstStyle = ipafsMin FIGURE 19.2 Example of the Min Tracking Align First Style.

Max This style adjusts the axis to show the first data point on the end of the scale. iComponent.Xaxis(0).TrackingAlignFirstStyle = ipafsMax iComponent.Yaxis(0).TrackingAlignFirstStyle = ipafsMax

FIGURE 19.3 Example of the Max Tracking Align First Style.

Iocomp Components – Plot Pack Manual 119 Chapter 19 - Tracking

Auto This style leaves the axis unchanged if the first data point is already in view. If the first data point is out of view, then the axis is adjusted to show the first data point on the beginning of the scale. iComponent.Xaxis(0).TrackingAlignFirstStyle = ipafsAuto iComponent.Yaxis(0).TrackingAlignFirstStyle = ipafsAuto

None [All Axis Default] The axes are not adjusted on the first data point. This is the default for all axes and is the most commonly used Align First Style. iComponent.Xaxis(0).TrackingAlignFirstStyle = ipafsNone iComponent.Yaxis(0).TrackingAlignFirstStyle = ipafsNone

Tracking Scroll Compress Max This feature specifies the maximum span value that is used to compress the axis when it receives tracking data. When the TrackingEnabled property is set to TRUE, the Span property will be increased (Compressed) to include the new Tracking Data if the current Span property is less than the TrackingSrollCompressMax property value.

FIGURE 19.4 Example of Chart for Tracking Scroll Compress Max Discussion

Notice that the data in the plot has been plotted up to an X-Axis value of 100. If the TrackingScrollCompressMax property is set to 500, then X-Axis span will begin to increase as new data is being added. When the Span property reaches the same value as the TrackingScrollCompressMax property, a value of 500, then the TrackingStyle will take over from that point on. In a default chart, the X-Axis would begin to Smooth Scroll after the Span property had reached a value of 500.

iComponent.Xaxis(0).TrackingScrollCompressMax = 500

120 Iocomp Components – Plot Pack Manual Chapter 19 - Tracking

Enabling and Disabling Tracking You can enable or disable the transfer of tracking data from the Channel to the Axes by setting independent properties on either the channel or axes. This gives you complete control over how tracking is implemented.

Channel Tracking Properties You can disable the transmission of tracking data that comes from a channel to a particular axis by setting that channel’s XAxisTrackingEnabled or YAxisTrackingEnabled properties. This allows you to only send tracking data to one, both, or none of the associated axes for this channel. The default value is TRUE.

iComponent.Channel(0).XAxisTrackingEnabled = TRUE iComponent.Channel(0).YAxisTrackingEnabled = TRUE

Axis Tracking Properties You can disable the reception of tracking data for a particular axis by setting the TrackingEnabled property for the axis. The default value is TRUE.

iComponent.XAxis(0).TrackingEnabled = TRUE iComponent.YAxis(0).TrackingEnabled = TRUE

User Interaction The end user of your application can also enable or disable tracking for all channels by using the Pause and Resume buttons on the built-in toolbar. Refer to the chapter on the toolbar for more information.

Manual Tracking If you need to manually send tracking information to the axes, use the following procedure, passing the new data…

iComponent.XAxis(Index).NewTrackingData(XData) iComponent.YAxis(Index).NewTrackingData(YData)

iComponent.XAxis(Index).NewTrackingData(10.5) iComponent.YAxis(Index).NewTrackingData(27.2)

If all you are interested in doing is preventing the axes from scrolling all together, then you should turn off the Tracking on all axes. Set the TrackingEnabled property to False for all axes. The effect will be that all of the axes will not respond to tracking data, and will not scroll. If you want to prevent user’s from scrolling the axes, set the Enabled property of the axis to False to prevent user interaction with the axis.

Iocomp Components – Plot Pack Manual 121 Chapter 20 - Interpolation

Chapter 20 - Interpolation

This feature, sometimes referred to as Curve -Fitting though that is not always the case, is supported by our iPlot component. Interpolation is the process by which a line or series is drawn according to an estimation function or set of functions based on existing known data point values.

There are several types of Interpolation available for the channel object. All of the current Interpolation styles draw curves that intersect existing data points.

None This is not really an Interpolation Style of the component, but is used when you do not want a trace line drawn between data points. You simply want to show the known data points on the graph without a line interconnecting the data points. To draw no line, set the TraceVisible property to FALSE. Don’t forget, that if you turn off the trace and don’t turn on the Data Markers (or you do not enable the other channel features such as bars, fill, etc), then nothing will be drawn to the screen!

iPlot1.Channel(0).TraceVisible = False

FIGURE 20.1 Channel with No Trace Visible.

122 Iocomp Components – Plot Pack Manual Chapter 20 - Interpolation

Straight Line This type of interpolation simply draws a straight line between each data point. This can result in “jagged-looking” curves. This interpolation style takes the least amount of CPU time.

iPlot1.Channel(0).InterpolationStyle = ipistStraightLine

FIGURE 20.2 Channel with Straight Line Trace.

Cubic Spline This type of interpolation draws a curve based on Cubic Spline curve fitting interpolation equations. This interpolation style will take additional CPU time as the data set gets larger.

iPlot1.Channel(0).InterpolationStyle = ipistCubicSpline

FIGURE 20.3 Channel with Cubic Spline Interpolated Trace

Iocomp Components – Plot Pack Manual 123 Chapter 20 - Interpolation

Polynomial This type of interpolation draws a curve based on Polynomial Interpolation curve fitting equations and is only good for small data sets (~100 data points). This interpolation style will take additional CPU time as the data set gets larger. Polynomial degree is fixed at [n – 1] with n =number of data points.

iPlot1.Channel(0).InterpolationStyle = ipistPolynomial

FIGURE 20.4 Channel with Polynomial Interpolated Trace

Rational This type of interpolation draws a curve based on Rational Interpolation curve fitting equations. This is an alternative to the Polynomial Interpolation with functions that have poles. This interpolation is good for small to medium-sized data sets. This interpolation style will take additional CPU time as the data set gets larger.

iPlot1.Channel(0).InterpolationStyle = ipistRational

FIGURE 20.5 Channel with Rational Interpolation Trace

124 Iocomp Components – Plot Pack Manual Chapter 20 - Interpolation

Differential This type of interpolation draws a curve based on Differential Interpolation. This style draws horizontal and vertical lines between data points. A line is drawn horizontal between one point’s X and Y-Value to the next data point’s X-Value. A vertical line is then drawn perpendicular from the end point up or down to the Y-Value of the second data point. This interpolation style will take slightly more additional CPU time than the straight line interpolation as it requires that twice the number of line segments be drawn on screen.

iPlot1.Channel(0).InterpolationStyle = ipistDifferential

FIGURE 20.6 Channel with Rational Interpolation Trace

Sometimes when using the curve fitting styles, an exception may be generated by the curve-fitting function due to the data being outside of the bounds of the function. If the data in your channel causes the function to go outside its bounds (e.g. causes the function to divide by zero or generate a larger number than can be handled by a double value), then an exception will be generated within the component causing the painting routine to fail. This will result in partially drawn curves and/or data points.

Iocomp Components – Plot Pack Manual 125 Chapter 21 - Loading and Saving Data

Chapter 21 - Loading and Saving Data

The Plot Pack components support several different methods for storing and retrieving data and control image snapshots both to and from the local file system or to and from a network server. Additionally, several data text, data log, and binary image file formats are also supported. The component interfaces have been left open for future expansion and support of additional file types and formats.

Data Formats The plot pack components natively support several text formats for saving and loading channel data. The saved data can be used in other applications (such as Microsoft Excel) or can be used to reload channel data into another instance of the control at a later date or program execution. Saving and loading of channel properties, such as channel trace width, line color, and other control properties is also supported.

There are two interfaces that are supported for loading and saving data. One is specific to a particular channel and the other is for all channels. To save and load data for a specific channel, use the methods below from a specific channel interface (e.g. iPlot1.Channel(0).SaveDataToFile). To save and load data for all channels in the chart, use the methods below from the main plot component interface (e.g. iPlot1.SaveToDataFile).

The supported data formats are as follows…

• Text (Tab Delimited) File

SaveDataToFile This method will save out the data for the specified channel or all channels to a tab delimited text file specified by Filename.

iPlot1.Channel(0).SaveDataToFile(Filename)

Sample File Output:

00 11 22 00 11 22 99

126 Iocomp Components – Plot Pack Manual Chapter 21 - Loading and Saving Data

iPlot1.SaveDataToFile(Filename)

Sample File Output:

Channel 1(X) Channel 1(Y) Channel 2(X) Channel 2(Y) 1 5 0 Null 2 10.458 1 30.627 3 12.444 2 43.433 4 6.411 3 38.513 6 11.558 4 46.817 7 11.132 5 48.345 8 9.933 6 43.953 9 7.983 7 33.252 11 24.529 8 46.513 12 5.405 9 47.486 13 5.433 10 Null 14 18.013 11 39.85

LoadDataFromFile This method will load in the data for the specified channel from a tab delimited text file specified by Filename. The first column must be the X channel data and the second column must be the Y channel data.

For loading data from the main plot interface, the first column is for the first channel’s X data, the second column is for the first channel’s Y data, the third column is for the second channel’s X data, the fourth column is for the second channel’s Y data, and so on. The first row is ignored when loading data from the main plot interface.

iPlot1.Channel(0).LoadDataFromFile(Filename) iPlot1.LoadDataFromFile(Filename)

SavePropertiesToFile This method will save out the properties for the specified channel to a tab delimited text file specified by Filename. Note, the file contains property information about the specified channel or all channels such as trace line width, line color, marker setup information, etc and does not contain XY data. The properties that are streamed out are generally only used with the LoadPropertiesFromFile method and not with external applications. Note the main interface’s SavePropertiesToFile method will stream out all properties of the control, not just the individual properties for each channel.

iPlot1.Channel(0).SavePropertiesToFile(Filename) iPlot1.SavePropertiesToFile(Filename)

Iocomp Components – Plot Pack Manual 127 Chapter 21 - Loading and Saving Data

LoadPropertiesFromFile This method will load in the properties for the specified channel from a text file specified by Filename. Note, the file contains property information about the specified channel or all channels such as trace line width, line color, marker setup information, etc and does not contain XY data. The properties that are streamed in are generally only used with the SavePropertiesToFile method and not with external applications. Note the main interface’s LoadPropertiesFromFile method will stream in all properties of the control, not just the individual properties for each channel.

iPlot1.Channel(0).LoadPropertiesFromFile(Filename) iPlot1.LoadPropertiesFromFile(Filename)

SaveAnnotationsToFile This method will save out all of the annotations objects to a tab delimited text file specified by Filename. The annotation data that is streamed out is generally only used with the LoadAnnotationsFromFile method and not with external applications

iPlot1.SaveAnnotationsToFile(Filename)

LoadAnnotationsFromFile This method will load in all of the annotations that were previously saved to a text file by the SaveAnnotationsToFile method. The properties that are streamed in are generally only used with the SavePropertiesToFile method and not with external applications.

iPlot1.LoadAnnotationsFromFile(Filename)

Data Log Formats The Plot Pack components also support real-time logging of channel data to a text file on your local hard drive. This differs from the Data Formats above in that data is appended to a text file (Tab Delimited) as data is being added to the chart.

You will need to ensure that the directory specified has already been created on the target ! data storage area before activating the log.

LogFileName This property specifies the path and filename of the log. If you are developing for a cross- platform application, then you will need to ensure that the path and filename are appropriate for all OS file systems or for the target OS file systems.

iPlot1.Channel(0).LogFileName = Filename

128 Iocomp Components – Plot Pack Manual Chapter 21 - Loading and Saving Data

LogBufferSize This property specifies the size of the buffer to use when logging channel data to the file specified by the LogFileName property. When data from the chart has filled the buffer, the buffered data is then written to the log file. This is useful if you want to spread out the disk write access by the plot component. (i.e. if you don’t use a buffer, then a write to the log is executed after every data point is added. This may not be desirable in some situations. With the buffer size set, you can have the component only write to the log after a specified amount of data has filled the buffer, therefore reducing the number of writes to the log file). The value specified is in units of # of data points.

iPlot1.Channel(0).LogBufferSize = 10

If you are using the log from the main interface, you will be writing out a log file that contains data for all channels. You must use the AddDataArray method to add data ! from the main interface if you are using the main interface logging feature.

LogActivate This method will start the logging of new data points to the specified file. Note that older data points will not be added to the log file, only new ones that have been added after executing this method.

iPlot1.Channel(0).LogActivate

LogDeactivate This property will stop the logging of new data points to the specified log file.

iPlot1.Channel(0).LogDeactivate

Iocomp Components – Plot Pack Manual 129 Chapter 21 - Loading and Saving Data

AddDataArray Example If you are using the logging feature from the main plot interface where you are logging all channels to a single log file, you have to use the AddDataArray method to add data to the channels. The first parameter refers to the common X Value for all of the channels, and the array contains one Y Value for each channel. The array type can be double or any variant type that can be converted to a double. The following example shows how to add data to the chart.

'Random Data dim TempArray(99) as Double forx=0to99 TempArray(x) = rnd(1)*100 next x iPlot1.AddDataArray XValue, TempArray 'Data From Some Other Source dim TempArray(99) as Double forx=0to99 TempArray(x) = YValueSource next x iPlot1.AddDataArray XValue, TempArray 'Your Data is already in array format iPlot1.AddDataArray XValue, YValuesArray

Also refer to the Adding Data Chapter for more information on using AddDataArray, about using AddDataArray in pseudo-Asynchronous mode, or for handling null or empty value data.

Image Formats There are also several image formats that are supported for saving static images of the plot component (except for the toolbar object). This is useful for exporting the image for use in an external reporting tool, for dynamic creation of images for ASP web pages, or for other uses where you need a “snapshot” graphic of the chart. Supported image formats are as follows…

• Enhanced Metafile Format (EMF) • Windows/OS2 Bitmap (BMP, RGB Encoded) • Independent JPEG Group Format (JPEG, JPG) • Portable Network Graphics Format (PNG, 16 million colors) {Coming Soon…}

Also See Chapter on Graphic Export.

130 Iocomp Components – Plot Pack Manual Chapter 22 - Graphical Export

Chapter 22 - Graphical Export

There are also several image formats that are supported for saving static images of the plot component (except for the toolbar object). This is useful for exporting the image for use in an external reporting tool, for dynamic creation of images for ASP web pages, or for other uses where you need a “snapshot” graphic of the chart. Supported image formats are as follows…

Enhanced Meta File Format This format is compact, and allows resizing in another application. This file type is only supported on Windows platforms and is not supported under Linux. We recommend that you use TrueType fonts (Vector Fonts) in the Plot component when using this file format since TrueType fonts resize better than bitmap-based fonts.

iComponent.SaveImageToMetaFile(Filename) iComponent.SaveImageToMetaFile("c:\images\plotimage001.emf")

Bitmap This format is generally used where you need to use a Windows-OS/2 compatible bitmap file. The file is uncompressed, so it is generally not recommended since other, compressed formats are available.

iComponent.SaveImageToBitmap(Filename) iComponent.SaveImageToBitmap("c:\ images \plotimage001.bmp")

JPEG This format is compact, lossy compressed, and is widely supported. However, we recommend that you use our EMF or PNG file types if possible since they produce smaller file sizes and the final graphic output is more suited for these other formats.

iComponent.SaveImageToJPEG(Filename, Compression, Progressive) iComponent.SaveImageToJPEG("c:\ images \plotimage001.emf", 100, True)

Note: Compression is a value between 0-100 and reflects the amount of lossy compression applied to the image. A value of 25 will give very good compression, but the image will be degraded. We recommend that you always use a value of 100. Progressive refers to the interlacing encoding used in some browsers.

PNG This format is compact, loss-less compressed (same quality as a bitmap, no loss of quality), and is widely supported. This file format is a replacement for the GIF standard (which is encumbered with patent issues, only supports 256 colors, and doesn’t compress as well as PNG), and is supported by all version 4.0 web browsers and above on all platforms. [Note, this format is not yet available…]

Iocomp Components – Plot Pack Manual 131 Chapter 22 - Graphical Export

Clipboard Transfer Method iComponent1.CopyToClipBoard()

This method will copy an enhanced metafile version of the chart to the standard clipboard for use elsewhere in your program. You can configure the data format of the image by using the CopyToClipBoardFormat property of the component to choose between the following supported image formats: JPEG, BMP, EMF.

GetBytesJPEG Method This method is useful in ASP web pages where you want to send a JPEG image of the Plot component to a web client. GetBytesJPEG allows you to send a JPEG image directly to the web client without using intermediate files.

Microsoft IIS Server ASP Page (VBScript) <%@ Language=VBScript %> <% 'Setup Response Response.Expires = 0 Response.Buffer = True Response.Clear

'Create ActiveX Control Set iPlotX1 = Server.CreateObject("iPlotLibrary.iPlotX")

'Set Some Properties iPlotX1.Width=500 iPlotX1.Height=300 iPlotX1.Labels(0).Caption = "Test Chart 1" iPlotX1.ToolBar(0).Visible = False

'Plot Some Random Data forx=0to100 iPlotX1.Channel(0).AddXY x, sin(x) * 100 next

'Stream JPEG Image Response.ContentType = "image/jpeg" Response.BinaryWrite(iPlotX1.GetBytesJPEG(100, TRUE))

'Cleanup Set iPlotX1 = Nothing %>

132 Iocomp Components – Plot Pack Manual Chapter 23 - Printing

Chapter 23 - Printing

The Iocomp Plot Pack components have built-in, basic capabilities for printing copies of your chart to a local or network printer. Features include…

• Ability to show or hide standard printer dialog before print • Set Page Orientation • Setup Page Margins

When you print out a copy of your chart, the entire image of the chart will be printed except for the toolbar, and the chart will be expanded to fit the entire page depending on your page orientation and page margin settings. The printing support in the Plot Pack components is designed to provide a very simple and easy to use interface for outputting your charts to paper. If you need more complex reporting capabilities, you will need to use a reporting package or custom code.

Printing Options Page Orientation Used to specify the orientation of the chart to be printed, modify the PrinterOrientation property..

iComponent1.PrinterOrientation = poPortriat

…or…

iComponent1.PrinterOrientation = poLandacape

Printer Dialog Used to specify that the standard print dialog is displayed when the Print method is executed, then set the PrintShowDialog property to TRUE.

iComponent1.PrintShowDialog = TRUE

Printer Document Name Used to specify the title of the document being printed. Generally, this value is displayed on the LCD display on printers that support displaying the printed document’s name as well as print job separator sheets. Some printer drivers require that this property be set to a non-null value.

iComponent1.PrintDocumentName = “Chart of X vs. Y”

Margins To set the paper margins, set the following properties to the margins you require. Units are in inches…

iComponent1.PrintMarginRight = 10 iComponent1.PrintMarginLeft = 10 iComponent1.PrintMarginTop = 10

Iocomp Components – Plot Pack Manual 133 Chapter 23 - Printing

iComponent1.PrintMarginBottom = 10

Top Margin FIGURE 23.1 Diagram showing Print Margin settings on a sample page in Landscape orientation. Chart Sizes to fill

Left Margin entire page inside of Right Margin specified margins

Bottom Margin

Simple Chart Print To print out a copy of the currently displayed chart in your program, execute the following method on the control…

iPlot1.Print()

This method will print a copy of the current chart, stretched to the size of the page up to the margin properties that were previously set without the toolbar.

Using with External Reporting Packages or Custom Code If you require more complex printing options, then you will need to use an external reporting package or your own customized code. For these other options, you can access a copy of the chart image for use as follows…

Clipboard Transfer iComponent1.CopyToClipBoard()

Use this option carefully. This method will be using your clipboard, and there is a possibility that other applications or even your application may be using the clipboard at ! the same time.

134 Iocomp Components – Plot Pack Manual Chapter 23 - Printing

IPictureDisp Object Transfer Image1.Picture = iComponent1.GetSnapShotPicture()

This method will return an IPictureDisp object image formatted as a metafile.

Save to Enhanced Metafile iComponent1.Save()

This method will save a copy of the chart image to an enhanced metafile format file for use elsewhere.

Printing Tips Many programmers like to see dark background charts with light colored channels and channel markers when viewing the Plot Components in a program. However, this color scheme doesn’t look very good on a printout and can waste printer toner, ink, and can lead to wrinkled paper on inkjet printers.

To counteract these printing issues, it is best to change the colors used in the chart just before printing, print out the chart, and then reset the colors back to their original settings. For example…

iComponent1.BeginUpdate() {Stops painting to the control to reduce flicker}

{Set background colors for Chart and DataView areas to a light color or white}

iComponent1.Print()

{Set background colors back to their original settings}

iComponent1.EndUpdate() {This resumes painting to the control}

Always, always, always use TrueType fonts to get the best results when saving to a graphic format or when printing. When using non-TrueType fonts, you may see distorted fonts or incorrect kerning.

Iocomp Components – Plot Pack Manual 135 Chapter 24 - Plot Pack Events

Chapter 24 - Plot Pack Events

Since not all component standards support events on the Plot Pack sub objects, you will find all events for objects such as the Channel or Axes on the Plot Pack component's main interface. For example, if you wish to utilize the "Data Point Click" event of the channel object, you would need to use the "OnClickDataPoint" event located on the component's main interface. The event will pass to you the index of the channel object that contained the data point that was clicked as well as information about the data point.

Printing Events OnBeforePrint Use OnBeforePrint to perform actions before the chart is sent to the printer. This event will fire just before the print is sent to the Printer, after the printer selection dialog is displayed. This event is generally used to make modifications to the chart before printing, such as inverting colors or setting colors to black and white for better looking printouts. Changes to the component between the OnBeforePrint and OnAfterPrint events will not be displayed on the screen. This is useful when you want to make changes for printing purposes only, and don’t want the screen to flash or change.

Visual Basic OnBeforePrint()

Visual C++: OnBeforePrint()

Borland Kylix/Delphi/C++ Builder property OnBeforePrint : TNotifyEvent;

OnAfterPrint This event is useful to undo changes you made in the OnBeforePrint event. Changes to the component between the OnBeforePrint and OnAfterPrint events will not be displayed on the screen.

Visual Basic: OnAfterPrint()

Visual C++: OnAfterPrint()

Borland Kylix/Delphi/C++ Builder: property OnAfterPrint: TNotifyEvent;

136 Iocomp Components – Plot Pack Manual Chapter 24 - Plot Pack Events

DataView Object Events OnClickAnnotation This event occurs whenever your application user clicks on an individual annotation object. The index of the annotation object is passed back, and you can use that index to access properties and methods of the annotation that was clicked. Note: the standard OnClick, OnMouseDown, and OnMouseUp events will still fire.

Visual Basic: OnClickAnnotation(ByVal Index As Long)

Visual C++: OnClickAnnotation(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnClickAnnotation : TiPlotObjectEvent;

OnClickDataPoint This event occurs whenever your application user clicks on an individual data point object. The index of the channel and the index of the data point is passed back, and you can use that channel index to access properties and methods of the channel as well as determine the X and Y coordinates of the data point that was clicked.

Note: the standard OnClick, OnMouseDown, and OnMouseUp events will still fire.

Visual Basic: OnClickDataPoint(ByVal ChannelIndex As Long, ByVal DataIndex As Long)

Visual C++: OnClickDataPoint(long ChannelIndex, long DataIndex)

Borland Kylix/Delphi/C++ Builder: type TiPlotClickDataPointEvent = procedure(ChannelIndex, DataIndex: Integer) of object; property OnClickDataPoint : TiPlotClickDataPointEvent;

Iocomp Components – Plot Pack Manual 137 Chapter 24 - Plot Pack Events

OnLimitLine1PositionChange This event occurs when the Line1Position property of a Limit object changes. The Index value passed is the Index of the Limit object that has had the Line1Position property change. The OldValue is the previous position of the limit line, and the NewValue is the new position of the limit line that caused this event to fire. These values are passed by value, and cannot be changed. Use the properties of the actual limit to make modifications.

Visual Basic: OnLimitLine1PositionChange(ByVal Index As Long, ByVal OldValue As Double, ByVal NewValue As Double)

Visual C++: OnLimitLine1PositionChange(long Index, double OldValue, double NewValue)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectDoubleValueChangeEvent = procedure(Index: Integer; OldValue, NewValue : Double) of object; property OnLimitLine1PositionChange : TiPlotObjectDoubleValueChangeEvent;

OnLimitLine2PositionChange This event occurs when the Line2Position property of a Limit object changes. The Index value passed is the Index of the Limit object that has had the Line2Position property change. The OldValue is the previous position of the limit line, and the NewValue is the new position of the limit line that caused this event to fire. These values are passed by value, and cannot be changed. Use the properties of the actual limit to make modifications.

Visual Basic: OnLimitLine2PositionChange(ByVal Index As Long, ByVal OldValue As Double, ByVal NewValue As Double)

Visual C++: OnLimitLine2PositionChange(long Index, double OldValue, double NewValue)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectDoubleValueChangeEvent = procedure(Index: Integer; OldValue, NewValue : Double) of object; property OnLimitLine2PositionChange : TiPlotObjectDoubleValueChangeEvent;

138 Iocomp Components – Plot Pack Manual Chapter 24 - Plot Pack Events

Data Cursor Object Events OnDataCursorChange This event occurs when either the Pointer1Position or Pointer2Position properties of a particular data cursor change.

Visual Basic: OnDataCursorChange(ByVal Index As Long)

Visual C++: OnDataCursorChange(long Index)

Borland Kylix/Delphi/C++ Builder: property OnDataCursorChange(Index : Integer) : TNotifyEvent;

Axis Object Events OnXAxisCustomizeLabel This event occurs before each X-Axis major tick label is painted on the control. Use this event to modify a major tick label. This event will fire for each label and the Index parameter specifies which label is about to be painted. Modify the DisplayText parameter to change the label. The ALabel parameter is passed by reference so that you may modify the label with your own text if desired.

Visual Basic: OnXAxisCustomizeLabel(ByVal Index As Long, ByVal Value As Double, ALabel As String)

Example: Private Sub iPlotX1_OnXAxisCustomizeLabel(ByVal Index As Long, ByVal Value As Double, ALabel As String) 'Examine the Value passed in the event. This event will fire for 'each label in the Axis (Index of the Axis is passed in the Index 'parameter), passing the Value of the Label in the Value 'parameter. Modify the ALabel string that is passed to change 'the label to any desired string. Note: Visual Basic supports 'double values in case statements. Select Case Value Case 0: ALabel = "Zero" Case 2: ALabel = "Two" Case 4: ALabel = "Four" Case 6: ALabel = "Six" Case 8: ALabel = "Eight" Case 10: ALabel = "Ten" End Select End Sub

Iocomp Components – Plot Pack Manual 139 Chapter 24 - Plot Pack Events

Visual C++: OnXAxisCustomizeLabel(long Index, double Value, BSTR FAR* ALabel)

Example: void CPlotcustomizelabeltestDlg::OnXAxisCustomizeLabel_m_iPlotX1(long Index, double Value, BSTR FAR* ALabel) { //Examine the Value passed in the event. This event will fire for //each label in the Axis (Index of the Axis is passed in the //Index parameter), passing the Value of the Label in the Value //parameter. Modify the ALabel string that is passed to change //the label to any desired string. //Note: Visual C++ does not support double values in a case //statement, so use if blocks instead. if (Value == 0) { *ALabel = ::SysAllocString(L"Zero"); }; if (Value == 2) { *ALabel = ::SysAllocString(L"Two"); }; if (Value == 4) { *ALabel = ::SysAllocString(L"Four"); }; if (Value == 6) { *ALabel = ::SysAllocString(L"Six"); }; if (Value == 8) { *ALabel = ::SysAllocString(L"Eight"); }; if (Value == 10) { *ALabel = ::SysAllocString(L"Ten"); }; }

Borland Kylix/Delphi/C++ Builder: type TiPlotAxesCustomizeLabelEvent = procedure(Index: Integer; Value: Double; var ALabel: String) of object; property OnXAxisCustomizeLabel : TiPlotAxesCustomizeLabelEvent;

OnXAxisMinChange This event occurs when the min property of the X-Axis changes. The Index value passed is the Index of the X-Axis object that has had the min property change. The OldValue is the previous min value of the X-Axis, and the NewValue is the new min of the X-Axis that caused this event to fire.

Visual Basic: OnXAxisMinChange(ByVal Index As Long, ByVal OldValue As Double, ByVal NewValue As Double)

Visual C++: OnXAxisMinChange(long Index, double OldValue, double NewValue)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectDoubleValueChangeEvent = procedure(Index: Integer; OldValue, NewValue : Double) of object; property OnXAxisSpanChange : TiPlotObjectDoubleValueChangeEvent;

140 Iocomp Components – Plot Pack Manual Chapter 24 - Plot Pack Events

OnXAxisSpanChange This event occurs when the span property of the X-Axis changes. The Index value passed is the Index of the X-Axis object that has had the min property change. The OldValue is the previous span value of the X-Axis, and the NewValue is the new span of the X-Axis that caused this event to fire.

Visual Basic: OnXAxisSpanChange(ByVal Index As Long, ByVal OldValue As Double, ByVal NewValue As Double)

Visual C++: OnXAxisSpanChange(long Index, double OldValue, double NewValue)

OnYAxisCustomizeLabel This event occurs before each X-Axis major tick label is painted on the control. Use this event to modify a major tick label. This event will fire for each label and the Index parameter specifies which label is about to be painted. Modify the DisplayText parameter to change the label. The ALabel parameter is passed by reference so that you may modify the label with your own text if desired.

Visual Basic: OnYAxisCustomizeLabel(ByVal Index As Long, ByVal Value As Double, ALabel As String)

Example: Private Sub iPlotX1_OnYAxisCustomizeLabel(ByVal Index As Long, ByVal Value As Double, ALabel As String) 'Examine the Value passed in the event. This event will fire for 'each label in the Axis (Index of the Axis is passed in the Index 'parameter), passing the Value of the Label in the Value 'parameter. Modify the ALabel string that is passed to change 'the label to any desired string. Note: Visual Basic supports 'double values in case statements. Select Case Value Case 0: ALabel = "Zero" Case 2: ALabel = "Two" Case 4: ALabel = "Four" Case 6: ALabel = "Six" Case 8: ALabel = "Eight" Case 10: ALabel = "Ten" End Select End Sub

Iocomp Components – Plot Pack Manual 141 Chapter 24 - Plot Pack Events

Visual C++: OnYAxisCustomizeLabel(long Index, double Value, BSTR FAR* ALabel)

Example: void CPlotcustomizelabeltestDlg::OnYAxisCustomizeLabel_m_iPlotX1(long Index, double Value, BSTR FAR* ALabel) { //Examine the Value passed in the event. This event will fire for //each label in the Axis (Index of the Axis is passed in the //Index parameter), passing the Value of the Label in the Value //parameter. Modify the ALabel string that is passed to change //the label to any desired string. //Note: Visual C++ does not support double values in a case //statement, so use if blocks instead. if (Value == 0) { *ALabel = ::SysAllocString(L"Zero"); }; if (Value == 2) { *ALabel = ::SysAllocString(L"Two"); }; if (Value == 4) { *ALabel = ::SysAllocString(L"Four"); }; if (Value == 6) { *ALabel = ::SysAllocString(L"Six"); }; if (Value == 8) { *ALabel = ::SysAllocString(L"Eight"); }; if (Value == 10) { *ALabel = ::SysAllocString(L"Ten"); }; }

Borland Kylix/Delphi/C++ Builder: type TiPlotAxesCustomizeLabelEvent = procedure(Index: Integer; Value: Double; var ALabel: String) of object; property OnYAxisCustomizeLabel : TiPlotAxesCustomizeLabelEvent;

OnYAxisMinChange This event occurs when the min property of the Y-Axis changes. The Index value passed is the Index of the Y-Axis object that has had the min property change. The OldValue is the previous min value of the Y-Axis, and the NewValue is the new min of the Y-Axis that caused this event to fire.

Visual Basic: OnYAxisMinChange(ByVal Index As Long, ByVal OldValue As Double, ByVal NewValue As Double)

Visual C++: OnYAxisMinChange(long Index, double OldValue, double NewValue)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectDoubleValueChangeEvent = procedure(Index: Integer; OldValue, NewValue : Double) of object; property OnYAxisSpanChange : TiPlotObjectDoubleValueChangeEvent;

142 Iocomp Components – Plot Pack Manual Chapter 24 - Plot Pack Events

OnYAxisSpanChange This event occurs when the span property of the Y-Axis changes. The Index value passed is the Index of the Y-Axis object that has had the min property change. The OldValue is the previous span value of the Y-Axis, and the NewValue is the new span of the Y-Axis that caused this event to fire.

Visual Basic: OnYAxisSpanChange(ByVal Index As Long, ByVal OldValue As Double, ByVal NewValue As Double)

Visual C++: OnYAxisSpanChange(long Index, double OldValue, double NewValue)

Plot Object Focus Events Note: the following Plot Object Focus Events are for focus changes within the component and not for general focus changes of the entire component. Use the container's events for the component to perform actions when the entire component loses or gets focus

OnGotFocusChannel Use OnGotFocusChannel to specify actions to perform when the Channel object obtains focus. The Index value passed is the Index of the object that has obtained focus.

Visual Basic: OnGotFocusChannel(ByVal Index As Long)

Example: Private Sub iPlotX1_OnGotFocusChannel(ByVal Index As Long) Dim x as long 'Loop and Hide Data Markers for All Channels forx=0toiPlotX1.ChannelCount iPlotX1.Channel(x).MarkersVisible = False next x

'Show Data Markers for the channel that obtained focus iPlotX1.Channel(Index).MarkersVisible = True End Sub

Visual C++: OnGotFocusChannel(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnGotFocusChannel : TiPlotObjectEvent;

Iocomp Components – Plot Pack Manual 143 Chapter 24 - Plot Pack Events

OnGotFocusDataCursor Use OnGotFocusDataCursor to specify actions to perform when the DataCursor object obtains focus. The Index value passed is the Index of the object that has obtained focus.

Visual Basic: OnGotFocusDataCursor(ByVal Index As Long)

Visual C++: OnGotFocusDataCursor (long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnGotFocusDataCursor : TiPlotObjectEvent;

OnGotFocusDataView Use OnGotFocusDataView to specify actions to perform when the DataView object obtains focus. The Index value passed is the Index of the object that has obtained focus.

Visual Basic: OnGotFocusDataView(ByVal Index As Long)

Visual C++: OnGotFocusDataView(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnGotFocusDataView : TiPlotObjectEvent;

Note: only one DataView is currently supported, so Index will always be 0.

OnGotFocusLegend Use OnGotFocusLegend to specify actions to perform when the Legend object obtains focus. The Index value passed is the Index of the object that has obtained focus.

Visual Basic: OnGotFocusLegend(ByVal Index As Long)

Visual C++: OnGotFocusLegend(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnGotFocusLegend : TiPlotObjectEvent;

Note: only one Legend is currently supported, so Index will always be 0.

144 Iocomp Components – Plot Pack Manual Chapter 24 - Plot Pack Events

OnGotFocusXAxis Use OnGotFocusXAxis to specify actions to perform when the X-Axis object obtains focus. The Index value passed is the Index of the object that has obtained focus.

Visual Basic: OnGotFocusXAxis(ByVal Index As Long)

Visual C++: OnGotFocusXAxis(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnGotFocusXAxis : TiPlotObjectEvent;

OnGotFocusYAxis Use OnGotFocusYAxis to specify actions to perform when the Y-Axis object obtains focus. The Index value passed is the Index of the object that has obtained focus.

Visual Basic: OnGotFocusYAxis(ByVal Index As Long)

Visual C++: OnGotFocusYAxis(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnGotFocusYAxis : TiPlotObjectEvent;

OnLostFocusChannel Use OnLostFocusChannel to specify actions to perform when the Channel object loses focus. The Index value passed is the Index of the object that has lost focus.

Visual Basic: OnLostFocusChannel(ByVal Index As Long)

Visual C++: OnLostFocusChannel(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnLostFocusChannel : TiPlotObjectEvent;

Iocomp Components – Plot Pack Manual 145 Chapter 24 - Plot Pack Events

OnLostFocusDataCursor Use OnLostFocusDataCursor to specify actions to perform when the DataCursor object obtains focus. The Index value passed is the Index of the object that has lost focus.

Visual Basic: OnLostFocusDataCursor(ByVal Index As Long)

Visual C++: OnLostFocusDataCursor(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnLostFocusDataCursor : TiPlotObjectEvent;

OnLostFocusDataView Use OnLostFocusDataView to specify actions to perform when the DataView object loses focus. The Index value passed is the Index of the object that has lost focus.

Visual Basic: OnLostFocusDataView(ByVal Index As Long)

Visual C++: OnLostFocusDataView(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnLostFocusDataView : TiPlotObjectEvent;

Note: only one DataView is currently supported, so Index will always be 0.

OnLostFocusLegend Use OnLostFocusLegend to specify actions to perform when the Legend object loses focus. The Index value passed is the Index of the object that has lost focus.

Visual Basic: OnLostFocusLegend(ByVal Index As Long)

Visual C++: OnLostFocusLegend(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnLostFocusLegend : TiPlotObjectEvent;

Note: only one Legend is currently supported, so Index will always be 0.

146 Iocomp Components – Plot Pack Manual Chapter 24 - Plot Pack Events

OnLostFocusXAxis Use OnLostFocusXAxis to specify actions to perform when the X-Axis object loses focus. The Index value passed is the Index of the object that has lost focus.

Visual Basic: OnLostFocusXAxis(ByVal Index As Long)

Visual C++: OnLostFocusXAxis(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnLostFocusXAxis : TiPlotObjectEvent;

OnLostFocusYAxis Use OnLostFocusYAxis to specify actions to perform when the Y-Axis object loses focus. The Index value passed is the Index of the object that has lost focus.

Visual Basic: OnLostFocusYAxis(ByVal Index As Long)

Visual C++: OnLostFocusYAxis(long Index)

Borland Kylix/Delphi/C++ Builder: type TiPlotObjectEvent = procedure(Index: Integer) of object; property OnLostFocusYAxis : TiPlotObjectEvent;

Standard Events OnMouseDown This event occurs when the user presses a mouse button and the mouse cursor is over the Plot Component.

Visual Basic: OnMouseDown(ByVal Button As Long, ByVal Shift As Long, ByVal X As Long, ByVal Y As Long)

Visual C++: OnMouseDown(short Button, short Shift, long X, long Y)

Borland Kylix/Delphi/C++ Builder: type TMouseEvent = procedure (Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer) of object; property OnMouseDown: TMouseEvent;

Iocomp Components – Plot Pack Manual 147 Chapter 24 - Plot Pack Events

OnMouseMove This event occurs when the user moves the mouse cursor over the Plot Component.

Visual Basic: OnMouseMove(ByVal Shift As Long, ByVal X As Long, ByVal Y As Long)

Visual C++: OnMouseMove(short Shift, long X, long Y)

Borland Kylix/Delphi/C++ Builder: type TMouseMoveEvent = procedure(Sender: TObject; Shift: TShiftState; X, Y: Integer) of object; property OnMouseMove: TMouseMoveEvent;

OnMouseUp This event occurs when the user releases a mouse button and the mouse cursor is over the Plot Component.

Visual Basic: OnMouseDown(ByVal Button As Long, ByVal Shift As Long, ByVal X As Long, ByVal Y As Long)

Visual C++: OnMouseDown(short Button, short Shift, long X, long Y)

Borland Kylix/Delphi/C++ Builder: type TMouseEvent = procedure (Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer) of object; property OnMouseUp: TMouseEvent;

148 Iocomp Components – Plot Pack Manual Chapter 25 - AutoScale and AutoLabel

Chapter 25 - AutoScale and AutoLabel

All axes support automatic scaling and formatting of their labels and tick marks. The automated scale (AutoScale feature) refers to the automatic scrolling of the axis with respect to newly added data and is related to the axis’ tracking feature. The AutoLabel feature refers to the 1-2-5 rules that ensure the scales look “human readable”, that is to say fall on major ticks and values that look good to a human.

1-2-5 Rule This rule refers to how the scales label positions and features are automatically calculated by the component. This means that the component attempts to ensure that the scale contains major tick labels increment by 1, 2, or 5 (or multiples such as 10, 100, 1000, etc) within the bounds that you setup using the Axis’ Min and Max properties. In short, the scale will attempt to fit in as many major tick labels as possible

For example, if your scale goes from –500 to +500, the component will attempt to fit as many labels between –500 and + 500 that are increment by 1, 2, or 5 and so on. For example, -500, - 400, -300, -200, -100, 0, 100, 200, 300, 400, 500 is a possible listing of major ticks in such as scale that would satisfy the 1-2-5 rule. Another example is –500, -250, 0, 250, 500. An example that wouldn’t fit would be –500, -389, -278, -167, -56, 56, 167, 278, 389, 500. Besides, that kind of scale doesn’t look “human readable”

FIGURE 25.1 Sample Chart showing X- Axis formatted with the human-readable 1-2-5 Rule

Which scale is used depends on the font size specified for the Axis’ labels. The scale will attempt to fit in a scale with the maximum number of labels possible. How many can fit depends several configurable factors.

Below you will find a list of rules used for the AutoScale and AutoLabel features. The component will go thorough the list in order and attempt to fit the maximum number of labels

Linear Scale The scale will attempt to fit the maximum number of labels where the major tick labels are divisible by 1, 2, or 5.

Date/Time Scale The scale will attempt to fit the maximum number of labels possible by moving through the following order starting from Milliseconds and going out to Years. For example, if generating

Iocomp Components – Plot Pack Manual 149 Chapter 25 - AutoScale and AutoLabel

labels on human-readable minutes is not possible, the scale will automatically switch to creating labels using hours instead. If that is not possible, it will move on to days, etc.

• Milliseconds: 1, 2, 5, 10, 20, 50, 100, 200, or 500 • Seconds: 1, 5, 10, 15, or 30 • Minutes: 1, 5, 10, 15, or 30 • Hours: 1, 2, or 12 • Days: 1, 7, or 14 • Months: 1, 2, 3, or 6 • Years: 1, 2, or 5

FIGURE 25.2 Sample Chart showing X-Axis formatted as Date/Time showing the hour, minute, and second in 24-hour format.

FIGURE 25.3 Sample Chart showing X-Axis formatted as Date/Time showing the day, month, hours,a nd seconds in12-hour format

Price32nds Scale The scale will attempt to fit the maximum number of labels possible where the major ticks are divisible by...

1/256, 2/256, 4/256, 1/32, 2/32, 4/32, 8/32, or 16/32

150 Iocomp Components – Plot Pack Manual Chapter 25 - AutoScale and AutoLabel

FIGURE 25.4 Sample Chart showing X-Axis formatted with the bond market Price 32nds Scale.

Log10 Scale The scale will attempt to fit the maximum number of labels possible where the major ticks are divisible by...

2, 5, 10, 20, 50, 100, or 200

FIGURE 25.5 Sample Chart showing Y-Axis formatted as a Log base 10- scale.

Modifying the 1-2-5 Rule DesiredIncrement If the 1-2-5 Rule doesn’t work in your particular situation, you can “tune” the AutoLabel feature by using the DesiredIncrement property of the axis. This property let’s you override the 1-2-5 rule and specify the increment used in the AutoLabel calculations

For example, let’s say you have a scale from 0 to 10. The Scale automatically creates a scale 0, 2.0, 4.0, 6.0, 8.0, 10.0.

Iocomp Components – Plot Pack Manual 151 Chapter 25 - AutoScale and AutoLabel

FIGURE 25.6 Sample Chart showing X-Axis formatted formatted with DesiredIncrment disabled.

But, you want the scale to increment by values of 2.5. So you would set the DesiredIncrement property to “2.5”, and if the new scale will fit in the space allotted, you would see a scale: 0, 2.5, 5.0, 7.5, 10.0.

For scales that do not scroll, you can also specify a fixed DesiredStart property to force the scale to start the first major tick at a specified value.

FIGURE 25.7 Sample Chart showing X-Axis formatted with the DesiredIncrement property set to “2.5”

Desired Start You can also force the AutoScale routine to start on a particular major tick value instead of the default Min value of the axis. Let’s say, for example you have a scale from 0 to 10. The initial chart starts the scale off at the minimum value of the scale which is 0.0…

FIGURE 25.8 Sample Chart showing X-Axis with DesiredStart disabled.

152 Iocomp Components – Plot Pack Manual Chapter 25 - AutoScale and AutoLabel

But, you want the first major tick to start off at 0.5. So you would set the DesiredStart property to 0.5, forcing the scale to start at 0.5…

FIGURE 25.9 Sample Chart showing X-Axis using the DesiredStart property set to “0.5”

Tracking Tracking refers to how the scale reacts when new data is added to the chart, such as smoothly scrolling to show new data that is added.

Refer to the chapter on Tracking for more information.

Iocomp Components – Plot Pack Manual 153 Chapter 26 - Visual C++ Disp vs. iDispatch Interface

Chapter 26 - Visual C++ Disp vs. iDispatch Interface

Visual C++ supports two different types of ways to interface with an ActiveX component...

Disp Interface [Late Binding, Class Wizard Default] This is the type of interface that is used if you add an ActiveX component to your project and use member variables to access your component. This type of interface is slower than the iDispatch interface, and is not recommended for our Plot Components.

FIGURE 26.1 Example screenshots of adding an ActiveX component wrapper class to your project for use with the late binding Disp Interface.

Disp Coding Example //Using the Disp Interface Index = m_iPlotX1.AddChannel(); m_iPlotX1.GetChannel(Index).SetMarkersStyle(4); //ipmsPlus m_iPlotX1.GetChannel(Index).SetTraceLineWidth(2); m_iPlotX1.GetChannel(Index).AddXY(XValue, YValue);

Sample data rates for our iPlotX component running on an AMD 900Mhz computer showing the speed differences between the Disp and iDispatch interface speed. One million data points were plotted on the chart, and the time taken to perform the plot was recorded below… • Disp Interface, AddXY Method: 85,000 data points/second • Disp Interface, AddXYArrays Method: 560,000 data points/second • iDispatch Interface, AddXY Method: 1,256,000 data points/second • iDispatch Interface, AddXYArrays Method: 516,000 data points/second

154 Iocomp Components – Plot Pack Manual Chapter 26 - Visual C++ Disp vs. iDispatch Interface

iDispatch Interface [Early Binding, High-Speed] This is the type of interface that is used if you add an ActiveX component to your form (by right-clicking on the form and selecting “Insert ActiveX Control”) or when you create an ActiveX component dynamically at runtime. This interface is used with your use the #import directive in your project to dynamically import the TLB during compilation.

The iDispatch Interface is much faster when accessing methods and properties of the Plot Pack component and is the recommended interface for using our components. Also, accessing sub-objects of the components such as channels is much easier and you are able to use the namespace of the components to access enumerated properties.

iDispatch Coding Example

//Using the iDispatch Interface Index = iPlotX1.AddChannel(); iPlotX1->Channel[Index].MarkersStyle = ipmsPlus; iPlotX1->Channel[Index].TraceLineWidth = 2; iPlotX1->Channel[Index].AddXY(XValue, YValue);

For example, to use the iDispatch Interface, do the following...

FIGURE 26.2 Inserting an ActiveX component without adding a wrapper class to your project.

Insert an ActiveX component onto your form by right clicking on the form and selecting “Insert ActiveX Component.”

Place the following code at the top of your form’s CPP file...

//Place at top of cpp file #import "iPlotLibrary.tlb" named_guids #include "atlbase.h" extern CComModule _Module; using namespace iPlotLibrary;

Iocomp Components – Plot Pack Manual 155 Chapter 26 - Visual C++ Disp vs. iDispatch Interface

To access the component placed on the form (we named the IDC of the component in this example “IDC_IPLOTX1”, refer to the following example. This example uses a local variable to access the component, but you can easily use a global variable instead.

double XData; double YData; CWnd* m_Wnd; IUnknown* m_iUnknown; CComPtr iPlotX1;

//Get interface to Plot Component //Assuming that name of component on form is IDC_IPLOTX1 in this example m_Wnd = GetDlgItem(IDC_IPLOTX1); m_iUnknown = m_Wnd->GetControlUnknown(); m_iUnknown->QueryInterface(__uuidof(iPlotLibrary::IiPlotX), \ (LPVOID*)&iPlotX1);

Now to access the component, use the newly created variable “iPlotX1” The syntax of accessing the component is similar to Visual Basic and Borland C++ Builder. Here are a ew examples...

//Disp Interface (Slow Speed) m_iComponentX1.DataView(0).SetGridShow(TRUE); m_iComponentX1.XAxis(0).SetMin(100); m_iComponentX1.YAxis(0).SetSpan(100); m_iComponentX1.Channel(0).SetName(“Channel 1”); m_iComponentX1.Legend(0).SetVisible(TRUE); m_iComponentX1.ToolBar(0).SetShowEditButton(FALSE); m_iComponentX1.Annotation(0).SetText(“Sample Annotation”); m_iComponentX1.DataCursor(0).SetStyle(3); //ipcsDeltaX m_iComponentX1.Limit(0).SetXAxisName(“X-Axis 1”); m_iComponentX1.Labels(0).SetCaption(“Chart Y vs. Time”);

//iDispatch Interface (High-Speed) iComponentX1->DataView[0]->GridShow = TRUE; ComponentX1->XAxis[0]->Min = 100; iComponentX1->YAxis[0]->Span = 100; iComponentX1->Channel[0]->Name = “Channel 1”; iComponentX1->Legend[0]->Visible = TRUE; iComponentX1->ToolBar[0]->ShowEditButton = FALSE; iComponentX1->Annotation[0]->Text = “Sample Annotation”; iComponentX1->DataCursor[0]->Style = ipcsDeltaX; iComponentX1->Limit[0]->XAxisName = “X-Axis 1”; iComponentX1->Labels[0]->Caption = “Chart Y vs. Time”;

Notice that you no longer have to use get and set methods to access properties or to access sub objects. Simply use the properties as you would in Visual Basic.

Since we are using the namespace for the iPlotLibrary, you can also use enumerated properties, such as “ipcsDeltaX” in the example above.

156 Iocomp Components – Plot Pack Manual Chapter 27 - Using With Database

Chapter 27 - Using With Database

Adding data to the Plot Pack component chart from a database is straightforward. Simply loop through the data in your recordset and add a data point from each record into the chart. The following issues should be kept in mind to increase performance or to perform more complex swapping of data.

Integrated Text File Saving and Loading The Plot Pack components natively support loading and saving of data from tab delimited text files on a per channel or per chart basis. Refer to the chapter entitled “Loading and Saving Data”.

Simple X and Y Data To add simple integer or double (floating point) data from your database to the chart, simply load your database recordset, and then loop through each record, adding each X and Y data point by using the AddData method (by passing X and Y values in double format)…

'Create Database Connection and Recordset 'Loop through recordset until EOF iPlot1.Channel(0).AddXY RecordFieldXValue, RecordFieldYValue 'End Loop

Time/Date X and Y Data To add Time or Date Based data from a database, you will first need to convert the value from its original format to a Double format before adding it to the chart if it is not already in Double format. (i.e. if the data is in string format as ‘March 1, 2001’ then it will need to be converted to it’s corresponding Date/Time double format value. For more information about Date/Time formats see the chapter entitled “Adding Data”)

Many development environments have functions that automate this procedure. For example, if the X value in the Database is a Time or Date value then you use the following…

'Create Database Connection and Recordset 'Loop through recordset until EOF DoubleFormatXValue = DateValue(RecordFieldXValue) iPlot1.Channel(0).AddXY DoubleFormatXValue, RecordFieldYValue 'End Loop

Don’t forget that if you are using Date/Time format values, you need to setup the associated axis to use DateTime formatted labels. Refer to the chapter entitled “Adding Data” for more information about DateTime format.

iPlot1.XAxis(0).LabelsFormatStyle = iptfDateTime iPlot1.YAxis(0).LabelsFormatStyle = iptfDateTime

Adding Very Large Amounts of Data to The Chart If you plan on adding very large amounts of data to the chart (millions of data points or more), then you have to take into account the memory limits of Windows Applications (2GB per application and associated components), network speed to transfer large amounts of data, and the processing time

Iocomp Components – Plot Pack Manual 157 Chapter 27 - Using With Database needed to move the data through memory or from a database located on your local hard drive or over a network.

1,000,000 data points = 22.35 MB of memory storage 5,000,000 data points = 111.75 MB of memory storage 10,000,000 data points = 223.50 MB of memory storage 25,000,000 data points = 558.75MB of memory storage 50,000,000 data points = 1.09 GB of memory storage

If you try and load all of this data at once, you will overload the PCI system bus or Ethernet Network since this is a huge amount of data to move at one time. You may want to consider loading the data dynamically as needed instead of trying to load all of the data at once.

Also see the chapter entitled “Memory Utilization” for more information.

158 Iocomp Components – Plot Pack Manual Chapter 28 - Layout Control Through Code

Chapter 28 - Layout Control Through Code

Generally, you will use the built-in property editor to setup and layout objects (layout objects plot objects such as the axes, data view, toolbar, and legend). Review the chapter entitled “Visual Layout Manger” for more information. You can, however, modify the placement of layout objects in your program’s code at run-time by using the following methods and properties.

Layout Manager The layout manager automatically adjusts the position of layout objects such as the axes, toolbar, and legend for you. If you are manually adjusting the layout of layout objects through code, it is helpful to disable the layout manager while you are making changes and then re-enable the layout manager when you are finished.

To Disable the Layout Manager, execute the following…

iPlot1.DisableLayoutManager

To Enable the Layout Manager, execute the following…

iPlot1.EnableLayoutManager

Layout Object ZOrder The ZOrder of a plot object determines how it is displayed in relation of other plot objects of the same type. Each plot object has a ZOrder property that determines how the layout object is painted on the control in relation to other layout objects. If two layout objects of the same type have the same ZOrder, then they are considered to be “stacked”.

For example, Y-Axis 1 & 2 have the same ZOrder, so they take up the same vertical position and are therefore “stacked”…

FIGURE 28.1 Diagram showing the first two Vertical object Z- Orders as well as two Y- Axes sharing the same Z- YAxis 2 Order resulting in them being stacked.

YAxis 0 Stacked Axes

YAxis 1

ZOrder 0 ZOrder 1

Iocomp Components – Plot Pack Manual 159 Chapter 28 - Layout Control Through Code

Layout Object StartPercent and StopPercent To specify how much area a particular layout object takes up, you will need to set the Start and Stop Percent properties. These properties are currently only supported by the X-Axis, Y-Axis, and Label objects.

A Start percent of 25% for a vertical layout object means that the layout object begins drawing 25% from the bottom of the area reserved for the axes. A Start percent of 25% for a horizontal layout object means that the layout object begins drawing 25% from the left side of the component.

A Stop percent of 75% for a vertical layout object means that the layout object ends drawing 75% from the bottom of the area reserved for the axes. A Stop percent of 75% for a horizontal layout object means that the layout object ends drawing 75% from the left side of the component.

Horizontal Layout Object

iPlot1.XAxis(0).StartPercent = 25 iPlot1.XAxis(0).StopPercent = 75

FIGURE 30.2 Diagram showing a Horizontal Layout Object with a Starting Percent of 25% and a Stopping Percent of 75%.

25% 75%

0% 100%

160 Iocomp Components – Plot Pack Manual Chapter 28 - Layout Control Through Code

Vertical Layout Object

iPlot1.YAxis(0).StartPercent = 25 iPlot1.YAxis(0).StopPercent = 75

100% FIGURE 30.3 Diagram showing a Vertical Layout Object 75% with a Starting Percent of 25% and a Stopping Percent of 75%.

25%

DataViewZVert and DataViewZHorz Since the DataView is both a horizontal and vertical layout object, you need to use these properties off of the main plot component interface to set the relative ZOrder position of the DataView in relation to other horizontal and vertical layout objects.

DataViewZVert To place the DataView in ZOrder #2 relative to other vertical layout objects, you would set the DataViewZVert property equal to 2.

iPlot1.DataViewZVert = 2

FIGURE 30.4 Diagram showing the relationship of the DataViewZVert YAxis 2 property and the DataView’s ZOrder as it fits with the Z-Order of other Vertical YAxis 0 Data View YAxis 3 Objects.

YAxis 1

ZOrder 0 ZOrder 1 ZOrder 2 ZOrder 3

Iocomp Components – Plot Pack Manual 161 Chapter 28 - Layout Control Through Code

DataViewZHorz To place the DataView in ZOrder #1 relative to other horizontal layout objects, you would set the DataViewZHorz property equal to 1.

iPlot1.DataViewZHorz = 1

FIGURE 30.5 ZOrder 2 XAxis 1 Diagram showing the relationship of the DataViewZHorz property and the DataView’s ZOrder as it fits with the Z-Order of other Horizontal ZOrder 1 Data View Objects.

ZOrder 0 XAxis 0

Toolbar and Legend Currently the Visual Layout Manager in the property editor does not support changing the ZOrder of the Toolbar. You can however change the ZOrder of the Toolbar relative to other horizontal layout objects (such as the DataView or X-Axes) by changing the ZOrder of the Toolbar through code at run-time. Note: this feature is not yet fully supported for positions other than the top of the component. The toolbar must always be the topmost ZOrder (i.e. the ZOrder must always be greater than other horizontal layout objects).

The Visual Layout Manager does support changing the ZOrder of the Legend in a graphical manner. You can also change the ZOrder of the Legend relative to other vertical layout objects (such as the DataView or Y-Axes) by changing the ZOrder of the Legend through code at runtime. The following would place the legend at the left side of the component…

iPlot1.Legend(0).ZOrder = 0

Only one toolbar and one legend are supported at this time. Always use an index value of 0 ! when accessing the ToolBar or Legend.

X and Y-Axes The plot component axes are designed to automatically take care of drawing, aligning, and maintaining the layout of the axes for you. You do, however, have control over several parameters that affect how the automated layout is handled.

162 Iocomp Components – Plot Pack Manual Chapter 28 - Layout Control Through Code

Note that this feature currently only supports the Axes layout objects. Also note that the stacking margin only applies to layout objects that touch each other and only affects the ends that touch. In the following example, the first Y-Axis (on the bottom) has a starting percent of 0 and ending percent of 50. The second Y-Axis (on top) has a starting percent of 50 and an ending percent of 100. The Stacking Ends Margin allocates additional space to separate the two stacked axes. The total spacing is 0.5 characters in this example, with the StackingEndsMargin values being cumulative. The StackingEndsMargin will have no effect on the ends of the ends of the axes unless they touch another axis

iPlot1.YAxis(0).StartPercent = 0 iPlot1.YAxis(0).StopPercent = 50 iPlot1.YAxis(0).StackingEndsMargin = 0.25

iPlot1.YAxis(1).StartPercent = 50 iPlot1.YAxis(1).StopPercent = 100 iPlot1.YAxis(1).StackingEndsMargin = 0.25

FIGURE 30.6 Example Chart showing the results of setting the stacked Y- Axes StackingEndsMargin property to “0.25”. 100%

50%

StackingEndsMargin (0.5 = 0.25 + 0.25)

Layout Object Horizontal This property should not be modified by the developer and is for internal use by the component to manage the layout and rotation of layout objects. To rotate the X and Y- Axes, use the XYAxesReverse property off of the main plot component interface…

iPlot1.XYAxesReverse = True

All axes margins use units of character widths and heights. This allows the component to dynamically adjust the scales based upon the font used instead of using rigid pixel specifications. A value of 0.25 would be equivalent to size (horizontal or vertical depending on if the margin relates to a horizontal or vertical margin) of a single character from the font being used in the layout object.

Iocomp Components – Plot Pack Manual 163 Chapter 28 - Layout Control Through Code

Plot Component Outer Margin You can change the inner margin of the plot component, thereby creating a margin between the layout objects and the edge of the component. The margin values are specified in pixels.

The following example sets a 5-pixel margin around the inside of the Plot Component…

iPlot1.OuterMarginLeft = 5 '5 Pixel Margin iPlot1.OuterMarginRight = 5 '5 Pixel Margin iPlot1.OuterMarginTop = 5 '5 Pixel Margin iPlot1.OuterMarginBottom=5'5Pixel Margin

FIGURE 30.7 Diagram showing the Outer Margin properties OuterMarginTop

OuterMarginLeft Layout Objects OuterMarginRight

OuterMarginBottom

Full Layout Through Code Eample The following example demonstrates adding an additional X-Axis and two additional Y-Axes, moving the X-Axis and Y-Axes by manipulating the ZOrder of all of the appropriate layout objects, and then adjusting two of the Y-Axes to be stacked. The code assumes you have added a fairly large iPlot component to your form and you are placing the code in your form load event.

You don’t have to hand-code the layout of objects unless you wish or need to do so. You can always use the Visual Layout Manager to arrange the layout objects without using any code in your program. Refer to the chapter entitled “Visual Layout Manager” for more information about using the Visual Layout Manager..

The output from the program should look like the following…

164 Iocomp Components – Plot Pack Manual Chapter 28 - Layout Control Through Code

FIGURE 30.8 Example Output from the Full Lsyout Through Code Example.

Y-Axis (0) X-Axis (1) Label (0) Y-Axis (2) X-Axis (0)

Y-Axis (1)

Visual Basic/VBA/VBScript 'Add one additional X-Axis 'There is already one X-Axis in the chart by default iPlotX1.AddXAxis

'Add two additional Y-Axes 'There is already one Y-Axis in the chart by default iPlotX1.AddYAxis iPlotX1.AddYAxis

'Disable the Layout Manager so that it doesn't interfere 'with our manual layout code iPlotX1.DisableLayoutManager

'Configure ZOrder of Horizontal Layout Objects iPlotX1.XAxis(0).ZOrder = 0 iPlotX1.DataViewZHorz = 1 iPlotX1.XAxis(1).ZOrder = 2 iPlotX1.Labels(0).ZOrder = 3 iPlotX1.ToolBar(0).ZOrder = 4

'Configure ZOrder of Vertical Layout Objects 'Note that the first two Y-Axes will have the same ZOrder, 'making them stacked axes

Iocomp Components – Plot Pack Manual 165 Chapter 28 - Layout Control Through Code

iPlotX1.YAxis(0).ZOrder = 0 iPlotX1.YAxis(1).ZOrder = 0 iPlotX1.DataViewZVert = 1 iPlotX1.YAxis(2).ZOrder = 2 iPlotX1.Legend(0).ZOrder = 3

'Configure the Start and Stop Percent of the two Y-Axes we wish 'to stack iPlotX1.YAxis(0).StartPercent = 0 iPlotX1.YAxis(0).StopPercent = 50 iPlotX1.YAxis(1).StartPercent = 50 iPlotX1.YAxis(1).StopPercent = 100

'Configure the Stacking Ends Margins for each of the stacked axes 'to allow for a separation total of half of a character between the 'ends of the axes that touch each other iPlotX1.YAxis(0).StackingEndsMargin = 0.25 iPlotX1.YAxis(1).StackingEndsMargin = 0.25

'Assign the Grid to use the Y-Axis on the far right so that the 'Grid looks consistent iPlotX1.DataView(0).GridYAxisName = iPlotX1.YAxis(2).Name

'Re-Enable the Layout Manager iPlotX1.EnableLayoutManager

Delphi/Kylix //Add one additional X-Axis //There is already one X-Axis in the chart by default iPlot1.AddXAxis;

//Add two additional Y-Axes //There is already one Y-Axis in the chart by default iPlot1.AddYAxis; iPlot1.AddYAxis;

//Disable the Layout Manager so that it doesn't interfere with //our manual layout code iPlot1.DisableLayoutManager;

//Configure ZOrder of Horizontal Layout Objects iPlot1.XAxis[0].ZOrder := 0; iPlot1.DataViewZHorz := 1; iPlot1.XAxis[1].ZOrder := 2; iPlot1.Labels[0].ZOrder := 3; iPlot1.ToolBar[0].ZOrder := 4;

//Configure ZOrder of Vertical Layout Objects //Note that the first two Y-Axes will have the same ZOrder, making //them stacked axes iPlot1.YAxis[0].ZOrder := 0; iPlot1.YAxis[1].ZOrder := 0; iPlot1.DataViewZVert := 1; iPlot1.YAxis[2].ZOrder := 2; iPlot1.Legend[0].ZOrder := 3;

//Configure the Start and Stop Percent of the two Y-Axes we wish to //stack iPlot1.YAxis[0].StartPercent := 0;

166 Iocomp Components – Plot Pack Manual Chapter 28 - Layout Control Through Code

iPlot1.YAxis[0].StopPercent := 50; iPlot1.YAxis[1].StartPercent := 50; iPlot1.YAxis[1].StopPercent := 100;

//Configure the Stacking Ends Margins for each of the stacked axes //to allow for a separationtotal of half of a character between the //ends of the axes that touch each other iPlot1.YAxis[0].StackingEndsMargin := 0.25; iPlot1.YAxis[1].StackingEndsMargin := 0.25;

//Assign the Grid to use the Y-Axis on the far right so that the //Grid looks consistent iPlot1.DataView[0].GridYAxisName := iPlot1.YAxis[2].Name;

//Re-Enable the Layout Manager iPlot1.EnableLayoutManager;

Visual C++ [Disp Interface] Place the following include statements at the top of your cpp file… #include "iplotx.h" #include "iplotaxisx.h" #include "iplotlegendx.h" #include "iplottoolbarx.h" #include "iplotdataviewx.h" #include "iplotlabels.h" ======//Add one additional X-Axis //There is already one X-Axis in the chart by default m_iPlotX1.AddXAxis();

//Add two additional Y-Axes //There is already one Y-Axis in the chart by default m_iPlotX1.AddYAxis(); m_iPlotX1.AddYAxis();

//Disable the Layout Manager so it doesn't interfere with manual //layout code m_iPlotX1.DisableLayoutManager();

//Configure ZOrder of Horizontal Layout Objects m_iPlotX1.GetXAxis(0).SetZOrder(0); m_iPlotX1.SetDataViewZHorz(1); m_iPlotX1.GetXAxis(1).SetZOrder(2); m_iPlotX1.GetLabels(0).SetZOrder(3); m_iPlotX1.GetToolBar(0).SetZOrder(4);

//Configure ZOrder of Vertical Layout Objects. Note that the first //two Y-Axes will have the same ZOrder, making them stacked axes m_iPlotX1.GetYAxis(0).SetZOrder(0); m_iPlotX1.GetYAxis(1).SetZOrder(0); m_iPlotX1.SetDataViewZVert(1); m_iPlotX1.GetYAxis(2).SetZOrder(2); m_iPlotX1.GetLegend(0).SetZOrder(3);

//Configure the Start and Stop Percent of the two Y-Axes we wish //to stack m_iPlotX1.GetYAxis(0).SetStartPercent(0); m_iPlotX1.GetYAxis(0).SetStopPercent(50); m_iPlotX1.GetYAxis(1).SetStartPercent(50);

Iocomp Components – Plot Pack Manual 167 Chapter 28 - Layout Control Through Code

m_iPlotX1.GetYAxis(1).SetStopPercent(100);

//Configure the Stacking Ends Margins for each //of the stacked axes to allow for a separation //total of half of a character between the ends //of the axes that touch each other m_iPlotX1.GetYAxis(0).SetStackingEndsMargin(0.25); m_iPlotX1.GetYAxis(1).SetStackingEndsMargin(0.25);

//Assign the Grid to use the Y-Axis on the far right //so that the Grid looks consistent

m_iPlotX1.GetDataView(0).SetGridYAxisName(m_iPlotX1.GetYAxis(2).GetName ());

//Re-Enable the Layout Manager m_iPlotX1.EnableLayoutManager();

Visual C++ [High-Speed iDispatch Inteface] Place the following include statements at the top of your file… //Place at top of cpp file #import "iPlotLibrary.tlb" named_guids #include "atlbase.h" extern CComModule _Module; using namespace iPlotLibrary; ======double XData; double YData; CWnd* m_Wnd; IUnknown* m_iUnknown; CComPtr iPlotX1;

//Add two additional Y-Axes //There is already one Y-Axis in the chart //by default iPlotX1->AddYAxis(); iPlotX1->AddYAxis();

//Disable the Layout Manager so that //it doesn't interfere with our manual //layout code iPlotX1->DisableLayoutManager();

//Configure ZOrder of Horizontal Layout Objects iPlotX1->XAxis[0]->ZOrder = 0; iPlotX1->DataViewZHorz = 1; iPlotX1->XAxis[1]->ZOrder = 2;

168 Iocomp Components – Plot Pack Manual Chapter 28 - Layout Control Through Code

iPlotX1->Labels[0]->ZOrder = 3; iPlotX1->ToolBar[0]->ZOrder = 4;

//Configure ZOrder of Vertical Layout Objects //Note that the first two Y-Axes will have the //same ZOrder, making them stacked axes iPlotX1->YAxis[0]->ZOrder = 0; iPlotX1->YAxis[1]->ZOrder = 0; iPlotX1->DataViewZVert = 1; iPlotX1->YAxis[2]->ZOrder = 2; iPlotX1->Legend[0]->ZOrder = 3;

//Configure the Start and Stop Percent of the //two Y-Axes we wish to stack iPlotX1->YAxis[0]->StartPercent = 0; iPlotX1->YAxis[0]->StopPercent = 50; iPlotX1->YAxis[1]->StartPercent = 50; iPlotX1->YAxis[1]->StopPercent = 100;

//Configure the Stacking Ends Margins for each //of the stacked axes to allow for a separation //total of half of a character between the ends //of the axes that touch each other iPlotX1->YAxis[0]->StackingEndsMargin = 0.25; iPlotX1->YAxis[1]->StackingEndsMargin = 0.25;

//Assign the Grid to use the Y-Axis on the far right //so that the Grid looks consistent iPlotX1->DataView[0]->GridYAxisName = iPlotX1->YAxis[2]->Name();

//Re-Enable the Layout Manager iPlotX1->EnableLayoutManager();

C++ Builder //Add one additional X-Axis //There is already one X-Axis in the chart //by default iPlot1->AddXAxis();

//Add two additional Y-Axes //There is already one Y-Axis in the chart //by default iPlot1->AddYAxis(); iPlot1->AddYAxis();

//Disable the Layout Manager so that //it doesn't interfere with our manual //layout code iPlot1->DisableLayoutManager();

//Configure ZOrder of Horizontal Layout Objects iPlot1->XAxis[0]->ZOrder = 0; iPlot1->DataViewZHorz = 1; iPlot1->XAxis[1]->ZOrder = 2; iPlot1->Labels[0]->ZOrder = 3; iPlot1->ToolBar[0]->ZOrder = 4;

//Configure ZOrder of Vertical Layout Objects //Note that the first two Y-Axes will have the

Iocomp Components – Plot Pack Manual 169 Chapter 28 - Layout Control Through Code

//same ZOrder, making them stacked axes iPlot1->YAxis[0]->ZOrder = 0; iPlot1->YAxis[1]->ZOrder = 0; iPlot1->DataViewZVert = 1; iPlot1->YAxis[2]->ZOrder = 2; iPlot1->Legend[0]->ZOrder = 3;

//Configure the Start and Stop Percent of the //two Y-Axes we wish to stack iPlot1->YAxis[0]->StartPercent = 0; iPlot1->YAxis[0]->StopPercent = 50; iPlot1->YAxis[1]->StartPercent = 50; iPlot1->YAxis[1]->StopPercent = 100;

//Configure the Stacking Ends Margins for each //of the stacked axes to allow for a separation //total of half of a character between the ends //of the axes that touch each other iPlot1->YAxis[0]->StackingEndsMargin = 0.25; iPlot1->YAxis[1]->StackingEndsMargin = 0.25;

//Assign the Grid to use the Y-Axis on the far right //so that the Grid looks consistent iPlot1->DataView[0]->GridYAxisName = iPlot1->YAxis[2]->Name();

//Re-Enable the Layout Manager iPlot1->EnableLayoutManager();

170 Iocomp Components – Plot Pack Manual Chapter 29 - Performance Tuning

Chapter 29 - Performance Tuning

By default, the Plot Components are designed to provide real-time performance even at high data rates on most system and application configurations. However, there are certain limitations and realities of the Windows and Linux operating systems, as well as graphics and processor hardware considerations.

For example, you will have no problem displaying tens of thousands of data points per second on a chart on a standard Windows 95/98/ME/NT/2000 or Linux system. However, the operating system can only draw to the screen at a certain rate depending on your processor speed, video card speed, system load, and/or the pixel size of the area being drawn on the video display.

Overall Component Speed = (Component Size) * (Frame Rate) * (System Speed) * (Video Card Speed) * (System Load)

To achieve the best real-time performance with extremely high data rates and frame rates, you will need to take the following items into consideration when setting up the component and or your computer system…

Component Size This is by far the most important item that affects the perceived speed and processor usage on your system.

For example, when you display a video file on a standard system (high frame rate video, 500Mhz processor, 64MB Ram, 1024x768 system), you will see the processor usage climb as you increase the size of the video window. This happens because the operating system has to draw more pixels to the screen as you increase the size of the window.

This is also the case with components. If you try to run a Plot component at full screen (1024x768 for example), the operating system has to work harder to draw the increased number of pixels to the system.

Frame Rate All of Iocomp’s components include properties and methods that allow you to control how often the control is repainted when changes are made to the components such as adding data or scrolling axes. Properties and methods that allow this control are: AutoFrameRate, UpdateFrameRate, BeginUpdate, and EndUpdate. These features allow you to either automatically or manually control how often the control’s display area is updated.

If you will be adding data points in real-time, we recommend that you set AutoFrameRate to True so that we can optimize the repainting of the control. However, if you will not e adding data in real-time (working with a static dataset), then we recommend turning off this feature since AutoFrameRate optimizations rely on continuously updated data coming into the channel.

AutoFrameRate The AutoFrameRate property specifies whether the control automatically controls the frame repaint rate. With AutoFrameRate enabled, the control will automatically throttle the number of

Iocomp Components – Plot Pack Manual 171 Chapter 29 - Performance Tuning

repaints per second that the control executes according to the number of frame per second specified in the UpdateFrameRate property. By using the Auto Frame Rate feature, you can control the number of repaints that the operating system has to make for the control, therefore reducing the amount of processing time used by this component.

iComponent1.AutoFrameRate = TRUE

UpdateFrameRate The UpdateFrameRate property specifies the frame rate at which the control automatically repaints in frame per second. Every time a data point is plotted or when a user scrolls the axes, the control has to repaint itself to reflect the new changes.

iComponent1.UpdateFrameRate = 10

The frame rate is used to improve performance by controlling the number of times the control repaints itself per second. To activate automatic frame rate control, the UpdateFrameRate property must be non zero. You can also use the manual BeginUpdate and EndUpdate method to manually control repainting even if the UpdateFrameRate feature is turned on.

Each time a change occurs to the control that requires a repaint, the control will determine if a new frame needs to be displayed. The FrameTime is one second divided by the UpdateFrameRate. If a change occurs to the control before the FrameTime has elapsed, the control is not repainted. If a change occurs to the control after the FrameTime has elapsed, the control is repainted and the next frame is started.

There must be a steady stream of changes to the control that require repainting for the automatic frame rate control to function correctly. The rate of change per second must be greater than the UpdateFrameRate for the desired frame rate to be achieved. Once changes to the control that require repainting have been stopped, call the EndUpdate method to force the control to repaint the last changes that may be cached.

When the frame rate control is inactive, the control will attempt to repaint when a change is made to the control that requires a repaint. The actual number of repaints per second is dependent of the system hardware, system activity, and the number of requests being made to repaint the control.

Note: if the user is interacting with the component, such as scrolling axes, clicking toolbar buttons, etc, the UpdateFrameRate is ignored. This allows the control to repaint quickly when the user is using the UI of the component so that it doesn’t appear sluggish with very slow Update Rates.

172 Iocomp Components – Plot Pack Manual Chapter 29 - Performance Tuning

BeginUpdate This method is used to manually stop all painting to the control if needed. This is useful if you plan on adding a very large amount of data to the chart or wish to make many changes to the chart, but don’t want the chart to repaint until you have completed your operations.

iComponent1.BeginUpdate

EndUpdate This method is used in conjunction with the AutoFrameRate feature mentioned above. It can also be used to manually resume all painting to the control if needed when AutoFrameRate is turned off.

iComponent1.EndUpdate

System Hardware Most modern or new computer systems are easily capable of displaying real-time data to the video display. If you need to display our controls with very high data rates on large video displays with large component sizes, then you will need to ensure that your computer hardware is up to the task.

Processor Having a faster processor generally will improve overall performance of your system and will increase the speed of draws to your video screen. Most modern systems (approximately 400Mhz or higher) have processors fast enough to handle most real-time applications used with our controls.

Memory The amount of memory is generally not that important to the speed of displaying data to the screen. The amount of RAM memory only comes into play when you are buffering many millions of data points into the chart, and have very low amounts of RAM in your system. If you run out of physical RAM, the operating system has to use the hard disk to store additional program memory, which is significantly slower than using physical RAM. See the next chapter regarding Memory Utilization of our Plot Pack components.

Note: Windows NT and 2000 allow you to set specific minimum and maximum sizes for the virtual memory swap file. If you will be storing may millions of data points in the chart, ensure that your maximum virtual memory swap file settings are set to accommodate the expected memory usage.

Video Card Many computer manufacturers have opted to include video card chipsets into the system bios/chipset. Generally, these types of video chipsets are not designed for displaying high-speed data to the video display. Also, some video cards that are included with systems are similarly not designed for displaying high-speed data.

Iocomp Components – Plot Pack Manual 173 Chapter 29 - Performance Tuning

Many people ask about their processor usage being very high when adding data at very high data rates. Generally this is not a problem since repaints to the screen have very low priority on the system, and if other processes need processor time during very heavy system loads, the repaints will be dropped. Our component attempts to use more processor power to keep up with the requested number of repaints, but will defer to other processes that need processor time when needed. By using the AutoFrameRate feature of our components, you can reduce the actual processor load on the system due to repaints by our controls if needed.

It is recommended that you use a high quality (many are not expensive), accelerated video card in your system if you will be using very large component sizes or video resolutions.

In the following example we will create a temporary variable to hold the channel sub object and will loop through 1,000,000 data points. You can flip between the method used in the example above and the example shown below to see the difference in speed. (Approximately 2x-4x faster using the local variable method shown below depending on your compiler).

Visual Basic Private Sub PlotButton_Click() Dim x As Long Dim XData As Double Dim YData As Double Dim TempChannel as iPlotChannelX

Set TempChannel = iPlotX1.Channel(0)

Forx=1To1000000 'Increment X Data XData = XData + 1 'Generate Random Y Data YData = Rnd(1) * 100 'Plot XY Data Pair TempChannel.AddXY XData, YData Next x End Sub

Visual C++ [Disp Interface] //Place at top of cpp file #include "iplotx.h" #include "iplotchannelx.h"

174 Iocomp Components – Plot Pack Manual Chapter 29 - Performance Tuning

void CFormDlg::OnPlotButton() { double XData; double YData; CiPlotChannelX TempChannel;

XData = 0; YData = 0;

TempChannel = m_iPlotX1.GetChannel(0);

for(int i=0; i<1000000; i++) { //Increment X Data XData = XData + 1; //Generate Random Y Data YData = (rand()/(double)RAND_MAX)*100; //Plot XY Data Pair TempChannel.AddXY(XData, YData); }; }

Visual C++ [High-Speed iDispatch Interface] //Place at top of cpp file #import "iPlotLibrary.tlb" named_guids #include "atlbase.h" extern CComModule _Module; using namespace iPlotLibrary;

void CFormDlg::OnPlotButton() { double XData; double YData; ..CWnd* m_Wnd; ..IUnknown* m_iUnknown; ..CComPtr iPlotX1; CComPtr tempChannel;

//Get interface to Plot Component //Assuming that name of component on form is IDC_IPLOTX1 in //this example ..m_Wnd = GetDlgItem(IDC_IPLOTX1); ..m_iUnknown = m_Wnd->GetControlUnknown(); m_iUnknown->QueryInterface(__uuidof(iPlotLibrary::IiPlotX), \ (LPVOID*)&iPlotX1);

tempChannel = iPlotX1->Channel[0];

XData = 0; YData = 0;

for(int i=0; i<1000000; i++) { //Increment X Data XData = XData + 1; //Generate Random Y Data YData = (rand()/(double)RAND_MAX)*100; //Plot XY Data Pair

Iocomp Components – Plot Pack Manual 175 Chapter 29 - Performance Tuning

tempChannel->AddXY(XData, YData); }; }

Also see chapter "Visual C++ Disp vs. iDispatch Interface" for more information about the High-Speed iDispatch Interface.

Internet Explorer [Client-Side, VBScript] Internet Explorer Plot Pack Example

VB.NET Private Sub PlotButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles PlotButton.Click Dim x As Long Dim XData As Double Dim YData As Double Dim TempChannel As iPlotLibrary.IiPlotChannelX

TempChannel = AxiPlotX1.get_Channel(0)

For x=1To 1000000 'Increment X Data XData = XData + 1 'Generate Random Y Data YData = Rnd(1) * 100

176 Iocomp Components – Plot Pack Manual Chapter 29 - Performance Tuning

'Plot XY Data Pair TempChannel.AddXY(XData, YData) Next x End Sub

C#.NET

private void PlotButton_Click(object sender, System.EventArgs e) { double XData = 0; double YData = 0

//Get and cache interface to channel object iPlotLibrary.IiPlotChannelX TempChannel = axiPlotX1.get_Channel(0);

//Create and seed random number generator object Random rnd = new Random(unchecked((int)DateTime.Now.Ticks));

//Plot data points for (int i = 1; i <= 1000000; i++) { //Increment X Data XData = XData + 1; //Generate Random Y Data YData = rnd.NextDouble() * 100; //Plot XY Data Pair TempChannel.AddXY(XData, YData); }; }

Iocomp Components – Plot Pack Manual 177 Chapter 30 - Memory Utilization

Chapter 30 - Memory Utilization

The Plot Pack components include several mechanisms for controlling the amount of RAM memory that is used to store channel data. By storing all or some of the data for each channel, the plot component makes it possible to use the built in scrolling, zooming, and cursor tools to be able to look at historical data and to be able to print and save that data to other formats.

The following sections will discuss how the Plot Pack components store data and how to control the amount of RAM memory that is used to suit your needs.

Data Storage Bytes Maximum # Per Meaning of Data Data Style Data Points Point The original data style for the component. This data 24 ipdsStandard set supports all of the features of the component and 89,478,485 bytes stores values in double-precision format. A single-precision, compact data storage type that uses 8 bytes per data point. This data set does not support the following features...· 8 ipdsCompact Empty Data Points 268,435,455 bytes Null Data Points Individual Marker Hiding Individual Marker Styles An single-precision, extremely compact data storage type for fixed-interval data sets that uses 4 bytes per data point. The first and second data point x-values added to the channel determine the fixed- interval used for the entire data set. For example, if the first data point's X-Value is 1, and the second data point's X-Value is 6, then the X-Value interval between all data points in this channel will be fixed at 5 (Interval = 6 - 1 = 5). All future X-Values will 4 ipdsCompactInterval 536,870,911 be ignored. This was done to keep backward bytes compatibility with previous log files and data sets. This data set does not support the following features...· Empty Data Points Null Data Points Individual Marker Hiding Individual Marker Styles Non-Fixed X-Interval Data Points Table 32.1

178 Iocomp Components – Plot Pack Manual Chapter 30 - Memory Utilization

Memory Usage Calculations [Standard Data Set Style] Since the plot pack components are designed to handle asynchronous data channels (i.e. the data points from one channel don’t have to be in sync with data points in another channel), each data point use 24 bytes data point to store the double values for

2 doubles and a Boolean value are used to represent one data point. 2 Double Values = 16 bytes (double = 8 bytes) Extended Feature Storage = 8 bytes Total = 16+8=24bytes per data point

Therefore, each data point that you add to the chart takes up 24 bytes of memory. If you expect to add 1 million (1,000,000) data points to your chart, you can expect to use…

24 bytes * 1,000,000 = 24,000,000 bytes 24 million bytes / 1024 bytes per KB = 23,437.50 KB 23,437.50 KB / 1024 KB per MB = 22.89 MB for 1,000,000 Data Points

…a total of 22.89 MB for all 1 million data points. If you have 5 channels with 100,000 data points added to each channel that would be…

24 bytes * 5 channels * 100,000 = 12,000,000 bytes 12 million bytes / 1024 bytes per KB = 11,718.75 KB 11,718.75KB / 1024KB = 11.44MB in 5 channels, total 500,000 Data Points

…a total of 11.44MB of data storage needed for 5 channels with 100,000 data points each channel.

2GB Application RAM Barrier Under the Windows 32-bit operating system, each application is limited to using a total 2GB of RAM Memory (2048 MB). This includes memory usage by everything in the program, including variables in your code and memory used by all components in the application (ActiveX, VCL, or CLX components). Keep this in mind when determining how much data you can fit into the chart as exceeding the 2GB RAM Usage barrier can result in out of memory or other program and system errors. If you run into this issue, then either use the Ring Buffer feature of the Plot Pack, reduce the number of data points added to the chart, or periodically save the data to an external file and clear out the buffer before adding additional data points. Future versions of Windows will support larger memory usage sizes. Consult your development environment documentation and Windows documentation for more information about future updates to this limitation

Note: In our research, we have determined that the real-world, actual maximum amount of memory, regardless of how little memory is used in other parts of your application, that a single component can utilize is approximately 1.3GB depending on the system and particular Operating System. Of course, the more memory that you application uses, the lower this value will be.

Under Linux (CLX components only) the amount of memory accessible by an application depends on your kernel version, kernel build, and development environment. This can range between 2GB and 64GB depending on your situation, but is generally a 2GB limit for most distributions. Consult your development environment documentation and Linux distribution documentation for more information.

Iocomp Components – Plot Pack Manual 179 Chapter 30 - Memory Utilization

Channel Memory Statistics At runtime, you can access various channel statistics such as memory utilization from either the run-time property editor or from code…

DataPointSize The number of bytes used by each data point added to the chart. This value depends on the Data Style used by the chart. See the Data Style chart above for the currently supported styles and their data point sizes. This value is useful for your own, internal memory calculations in your code.

MaxDataPoints The maximum theoretical number of data points that you can fit into the chart. For 32-bit Windows, this represents the maximum theoretical number of data points that will fit into the 2GBprocess memory limitation ( minus the application’s memory footprint) imposed by Windows. In our own research and testing, the actual real-world limitation under 32- bit Windows is 1.3GB. This may change in future 32-bit or 64-bit versions of Windows.

Capacity The number of data points that have been allocated for the channel. This value is increased by 25% whenever your actual number of data points added to the channel exceeds the memory capacity of the channel. This is done to reduce the number of memory allocations. If we were to increase the memory allocation for each data point added to the chart, there would be a large overhead in doing this and would result in slow or sluggish performance. The only drawback to this is that the amount of memory “reserved” by the operating system will always be greater than the actual number of data points used. You have to always trade off memory utilization for performance.

MemoryUsed This is identical to Capacity, but represents the number of bytes currently allocated by the channel.

Resource Memory vs. RAM Memory RAM Memory Modern operating systems such as Microsoft Windows 95/98/ME/NT/2000 and Linux support Virtual Memory and can handle the addition of data sets of this size. This means that in a system with…

• 64MB of Physical RAM • 128MB of Virtual Memory

…you can support 192 MB of data from the operating system and running applications.

If you are using 1,000,000 data points in your chart (22.89 MB of data), this can easily fit in your available system RAM memory. If you need additional memory, increase the allocation of virtual memory (See your System control panel or operating system documentation) or install additional RAM modules.

180 Iocomp Components – Plot Pack Manual Chapter 30 - Memory Utilization

Resource Memory Resource Memory, on the other hand, depends on your operating system and is not related to the amount of Physical RAM or Virtual Memory you have allocated for your operating system. Resources refer to memory allocated to brushes, pens, windows, font managers, and other operating system dependent resources. Operating systems such as Windows 95/98/ME have a smaller limit on the amount of resources that can be allocated at any one time compared to Windows NT/2000/XP systems. This is a function of the operating system and does not matter how much RAM you have installed, even if you have gigabytes of memory installed.

This resource memory barrier limits the number of programs, windows, and controls that you can have open at any one time. You should have no problem running several Plot Pack components (Service Pack 1 release or greater) in your application.

You can run approximately 1500 windows + controls on a Windows 95/98/ME system, and approximately 3000 windows + controls on a Windows NT/2000 system. Windows XP is expected to have even higher limits. Note that this is highly dependent on other applications, services, and other programs running on your system and is intended only as a guide.

Ring Buffer By default, the plot components store all data that has been added to available system RAM memory. To control the amount of memory that is used by the charts, you can take advantage of the Ring Buffer support in the plot components.

The Ring Buffer is a FIFO (First-In First-Out. In other words, when the buffer is full, the first data point added is the first data point to be overwritten) type buffer where you specify the maximum amount of data points that can fit in the buffer. Once that maximum number is exceeded, then data is removed from the buffer starting with the first data points that were initially added.

The RingBufferSize is specified in the number of data points allowed in the buffer for this particular channel. This property setting does not affect other channels.

When you set the Ring Buffer to a non-zero value, then memory will be allocated for that number of data points whether or not those data points actually exist. The advantage to this type of buffer is that you will always know if the buffer you have set exceeds the ! available RAM + Virtual Memory on your system ahead of time, instead of find this out after running the chart overnight!

Iocomp Components – Plot Pack Manual 181 Chapter 30 - Memory Utilization

To enable the Ring Buffer for a particular channel, set the RingBufferSize property for the number of data points that you wish to remain in the buffer for a specific channel.

iPlot1.Channel(0).RingBufferSize = 10000

To disable the ring buffer and storage all data to available memory (up to the 2GB per application limit), set the ring buffer property to zero…

iPlot1.Channel(0).RingBufferSize = 0

FIGURE 32.1 Newly Added Ring Buffer (FIFO) Data Points [Head] Oldest Data Overwritten [Tail]

182 Iocomp Components – Plot Pack Manual Chapter 31 - Implementing Toolbar Externally

Chapter 31 - Implementing Toolbar Externally

The built-in toolbar is intended to be a very simple and easy to use toolbar, providing basic user tools and functionality for the Plot Pack components. If you need a more advanced toolbar, or if you want to include functionality for other features of your application, you will need to use an external toolbar control.

The Plot Pack components have interfaces that allow you to easily map and perform the same functions as the built-in toolbar. Many development environments come with their own toolbar controls and you can find many other third-party toolbars with many advanced features. You will need to use our toolbar interfaces in the event code that is generated by the toolbar that you use. Each function interface will perform the same action as if the user had clicked on the corresponding built-in toolbar button.

Methods that are available to perform toolbar functions are as follows…

Resume Button

iComponent.ToolBar(0).DoButtonClickResume

Pause Button

iComponent.ToolBar(0).DoButtonClickPause

Axes Scroll Mode Button

iComponent.ToolBar(0).DoButtonClickScrollAxesMode

Axes Zoom Mode Button

iComponent.ToolBar(0).DoButtonClickZoomAxesMode

Zoom In Button

iComponent.ToolBar(0).DoButtonClickZoomOut

Zoom Out Button

iComponent.ToolBar(0).DoButtonClickZoomIn

Select Button

iComponent.ToolBar(0).DoButtonClickSelect

Iocomp Components – Plot Pack Manual 183 Chapter 31 - Implementing Toolbar Externally

Zoom Box Button

iComponent.ToolBar(0).DoButtonClickZoomBox

Cursor Button

iComponent.ToolBar(0).DoButtonClickCursor

Edit Button

iComponent.ToolBar(0).DoButtonClickEdit

Copy Button

iComponent.ToolBar(0).DoButtonClickCopy

Save Button

iComponent.ToolBar(0).DoButtonClickSave

Print Button

iComponent.ToolBar(0).DoButtonClickPrint

Currently, only one toolbar is supported. Always use ToolBar(0) when referencing the ! toolbar. In a future release, the Plot Components will support multiple toolbars.

184 Iocomp Components – Plot Pack Manual Chapter 32 - Implementing Legend Externally

Chapter 32 - Implementing Legend Externally

The built-in legend automatically provides the following functionality…

• Channel Trace Line Style and Color Listing • Channel Marker Style and Color Listing • Channel Name Listing • Channel Associated X-Axis • Channel Associated Y-Axis • Channel Current X/Y Coordinate

FIGURE 32.1 Sample Chart showing various items supported by the built-in legend.

… if you wish to implement your own legend outside of our component, you can emulate the features listed above as follows…

Channel Name Listing The value displayed in the Title column is actually not the ChannelName property, but the ChannelTitle property. The ChannelTitle property controls what is displayed in the Title column. To access a particular Channel Title, use the following…

iPlot1.Channel(0).ChannelTitle

…where 0 is the Channel index corresponding to the first channel.

To access all of the Channel Titles in a loop, execute the following…

Forx=0toiPlot1.ChannelCount -1 ChannelTitleTextString = iPlot1.Channel(x).ChannelTitle Next x

Iocomp Components – Plot Pack Manual 185 Chapter 32 - Implementing Legend Externally

Channel Trace Line Style and Color Listing The colored line displayed in the first represents the line style and color of the channel’s trace line. Note that the width of the line is not represented and that the line style is simulated to make it easier to distinguish among the different line styles available. To access a particular Channel Line Style or Line Color, use the following…

iPlot1.Channel(0).TraceLineStyle iPlot1.Channel(0).Color

…where 0 is the Channel index of the 1st channel. The following line styles are available…

Line Style Integer Value iplsDash 0 iplsDashDot 1 iplsDashDotDot 2 iplsDot 3 iplsSolid 4 Table 32.1

To access all of the Channel Trace Line Styles and Colors in a loop, execute the following…

Forx=0toiPlot1.ChannelCount -1 ChannelLineStyleValue = iPlot1.Channel(x).TraceLineStyle ChannelLineColor = iPlot1.Channel(x).Color ChannelLineStyle = iPlot1.Channel(x).TraceLineStyle Next x

FIGURE 32.2 Legend showing each channel’s Channel Trace Line and Channel Data Marker

Channel Trace Line Channel Data Marker

186 Iocomp Components – Plot Pack Manual Chapter 32 - Implementing Legend Externally

Channel Marker Style and Color Listing The colored marker displayed in the first represents the marker style and color of the channel’s marker. There are several properties that affect the look of a Channel Marker. A marker is drawn using a style to determine the shape of the marker, a pen (for drawing the outline), and a brush (for drawing the “fill”). To access the properties of markers for a particular channel, use the following…

iPlot1.Channel(0).MarkersBrushColor iPlot1.Channel(0).MarkersBrushStyle iPlot1.Channel(0).MarkersBrushUseChannelColor iPlot1.Channel(0).MarkersPenColor iPlot1.Channel(0).MarkersPenStyle iPlot1.Channel(0).MarkersPenUseChannelColor iPlot1.Channel(0).MarkersPenWidth iPlot1.Channel(0).MarkersSize iPlot1.Channel(0).MarkersStyle

…where 0 is the Channel index corresponding to the first channel. The following marker styles, brush styles are line styles are available…

Markers Style Integer Value ipmsCircle 0 ipmsSquare 1 ipmsDiamond 2 ipmsCross 3 ipmsPlus 4 ipmsTriangleUp 5 ipmsTriangleDown 6 ipmsTriangleLeft 7 ipmsTriangleRight 8 Table 32.2

Brush Style Integer Value bsSolid 0 bsClear 1 bsHorizontal 2 bsVertical 3 bsFDiagonal 4 bsBDiagonal 5 bsCross 6 bsDiagCross 7 Table 32.3

Iocomp Components – Plot Pack Manual 187 Chapter 32 - Implementing Legend Externally

Pen Style Integer Value psSolid 0 psDash 1 psDot 2 psDashDot 3 psDashDotDot 4 psClear 5 Table 32.4

Channel Associated X-Axis To obtain the associated X-Axis for a particular channel, use the following…

iPlot1.Channel(0).XAxisName

Channel Associated Y-Axis To obtain the associated Y-Axis for a particular channel, use the following…

iPlot1.Channel(0).YAxisName

Channel Current X/Y Coordinate The X and Y columns in the legend display the current X and Y coordinates for the most recently added data point for a particular channel. In the example below, the green channel (Channel 6) shows a current Y value of 30, which corresponds to the X-Value displayed in the graph and in the legend.

FIGURE 32.3 Legend showing the last added data point’s X and Y value for each channel.

188 Iocomp Components – Plot Pack Manual Chapter 32 - Implementing Legend Externally

To access any particular X or Y coordinate of a particular data point, use the following where Index is the index of the data point being requested (0 would be the first data point, 1 the second, 2 the third, etc.)…

XValue = iPlot1.Channel(0).DataX(Index) YValue = iPlot1.Channel(0).DataY(Index)

To access the X and Y coordinate of the most recently added data point, use the following…

XValue = iPlot1.Channel(0).DataX(iPlot1.Channel(0).Count – 1) Yvalue = iPlot1.Channel(0).DataY(iPlot1.Channel(0).Count – 1)

Iocomp Components – Plot Pack Manual 189 Chapter 33 - ASP (Active Server Pages)

Chapter 33 - ASP (Active Server Pages)

Working with ASP pages in conjunction with a Microsoft IIS server (Windows NT 4.0, Windows 2000, Windows XP) allows you to instantiate our component on the server side, add data to the chart, and then stream an image of the chart to your end user without using temporary files. This is all done without needing to run a copy of our component on the web browser client, allowing for cross-platform support of our component in static mode.

Here is a simple example that shows how to create a Plot component on the web server, set some properties of the component, add some data, and then stream out a JPEG image of the component to your client by using the Response object. ASP Page code is interpreted on the web server before it is sent to the client, so the following script would be replaced with a JPEG image in the resulting HTML code sent to the browser.

Microsoft IIS Server ASP Page (VBScript) <%@ Language=VBScript %> <% 'Setup Response Response.Expires = 0 Response.Buffer = True Response.Clear

'Create ActiveX Control Set iPlotX1 = Server.CreateObject("iPlotLibrary.iPlotX")

'Set Some Properties iPlotX1.Width=500 iPlotX1.Height=300 iPlotX1.Labels(0).Caption = "Test Chart 1"

iPlotX1.ToolBar(0).Visible = False

'Plot Some Random Data forx=0to100 iPlotX1.Channel(0).AddXY x, sin(x) * 100 next

'Stream JPEG Image Response.ContentType = "image/jpeg" Response.BinaryWrite(iPlotX1.GetBytesJPEG(100, TRUE))

'Cleanup Set iPlotX1 = Nothing %>

190 Iocomp Components – Plot Pack Manual Chapter 34 - Internet Explorer (Client Side)

Chapter 34 - Internet Explorer (Client Side)

Our ActiveX version of our Plot Pack components can be used to display Real-Time chart data in the Microsoft Internet Explorer Browser. This chapter covers running our Plot Pack ActiveX components on a client’s Internet Explorer Browser. If you only require static images to be displayed on a users machine and you wish to support all operating systems and browsers other than Microsoft Internet Explorer and Windows, then please refer to our chapter on ASP (Active Server Pages) and/or Apache Web Modules.

The following requirements must be met to be able to display Real-Time data from your network server to your local client’s web browser…

The client must be running 32-bit Windows. The client must be running Microsoft Internet Explorer 3.01 or higher version You must provide code or another ActiveX component in your HTML webpage code to transfer data from the web server or other network server or computer. If your web page will be acquiring data from the client’s machine or if you will be statically embedding your data in the web page (or statically through ASP or other server side scripts), then this is not needed. SOAP as well as direct database- linking support will be provided in a future release.

Netscape and The Mozilla project do have solutions for embedding ActiveX controls in their browsers on Windows machines with varying degrees of success. Some solutions support properties and events, others do not. Iocomp does not support these solutions at ! this time, but will support future versions of Netscape, Mozilla, and other browsers when they attain sufficient support for embedding ActiveX controls.

Creating the Plot Pack ActiveX Object in Your Web Page To create an ActiveX object on the client’s machine, you would need to include the following html code in the body section of your web page…

Many HTML development tools such as InterDev and FrontPage will automatically generate this code for you, and will also stream out design-time properties of the control to the html document for you. If you are using an HTML development tool that doesn’t automatically generate this code for you, you will need to manually type in the information as needed.

ClassID List for Plot Pack Components

• iPlot 1791C036-8981-492A-BD28-F2331BC9B7C7

• iXYPlot D1CAE8F4-6DFF-4187-B1B8-DDCF91F98A8A

Iocomp Components – Plot Pack Manual 191 Chapter 34 - Internet Explorer (Client Side)

Refer to Appended entitled ActiveX HTML Properties and Events for a listing of all of the supported properties and events than can be used with our Plot Pack components in an HTML web page.

Installing the Plot Pack ActiveX Control on the Client To automatically install and update our Plot Pack ActiveX controls on your client machine, you will need to modify the “object” tag used in the previous section as follows…

The addition of codebase=”pathname/iPlotLibrary.cab#2,0,0,0” instructs Internet Explorer to download, install, and register the Plot Pack ActiveX components (compressed in a CAB file) under the following conditions…

1. The Plot Pack ActiveX is not installed on the client’s computer 2. The version of the Plot Pack ActiveX installed on the client’s computer is less than the version specified after the # symbol. Notice that the version number separator is “,” and not “.”.

To obtain a digitally signed, pre-prepared CAB file for the Plot Pack or any of our ActiveX components, navigate to our downloads web page at http://www.iocomp.com/download

To obtain the version number of the ActiveX component contained in our pre-prepared CAB file, open the file in a Zip utility (such as WinZip) and view the contained INF file. That file will contain the full version information about the contained ActiveX component

Don’t uncompress or modify the CAB file’s supplied by Iocomp Software. Simply copy the CAB file to your server, and reference it in the codebase parameter of the object tag. If you need to place our ActiveX in your own self-created CAB file, then you will need to obtain a digital certificate from a Cert provider such as Versign or Thawte. By using our digitally signed CAB files or using your own digitally signed CAB file, your clients can leave their Internet Security Settings set on High.

Licensing the Plot Pack ActiveX Control All ActiveX controls that require licensing must have an LPK file specified in each web page that uses that control. Since only one LPK file can be specified in any one web page, it is recommended that you generate an LPK file for all ActiveX controls (no matter which vendor) that you may be using in your web pages.

To integrate the LPK file into your web page, you will need to associate the LPK file with the Microsoft License Manager control that is built into the Internet Explorer browser as follows…

192 Iocomp Components – Plot Pack Manual Chapter 34 - Internet Explorer (Client Side)

The CLASSID used is for the Microsoft License Manager control and not the other ! ActiveX controls used in your web page!

To generate an LPK file, you will need to obtain the LPK Tool program from Microsoft. You can download this tool from Microsoft’s Website and from their Internet Explorer Toolkit.

Accessing the Plot Pack ActiveX Control from VBScript If you are familiar with Microsoft Visual Basic or VBA from Microsoft Office products, you should find the VBScript language to be almost identical. Accessing the chart from your VBScript code follows the same rules as Visual Basic. Consult documentation or books on how to use VBScript, or consult our example below and in the Examples Section of our Support Website.

AddXY Example

VBScript does not support variable types. When you dimension your variables, do not give a type. All variable types in VBScript are Variants.

Iocomp Components – Plot Pack Manual 193 Chapter 34 - Internet Explorer (Client Side)

Full Source Example

FIGURE 34.1 Example Internet Explorer output for the Full Source Example.

Internet Explorer Plot Pack Example

194 Iocomp Components – Plot Pack Manual Chapter 35 - OPC (OLE For Process Control)

Chapter 35 - OPC (OLE For Process Control)

OPC, or OLE for Process Control, is a standard for linking properties and channels of our components to hardware signals or configurations from industry standard OPC servers. Most of our components now include support for linking properties to OPC servers, allowing them to be automatically updated or to update the OPC server automatically without writing code!

OPC is a specification or set of written rules and procedures for the way multiple software programs ("applications") can talk to each other. The OPC specification was created by users and software developers in the manufacturing/process control industry to serve the needs of the manufacturing automation/process control industry specifically. The specification is managed by volunteer effort and administered by the independent OPC Foundation.

The OPC Add-On features are included as a free upgrade to our current Version 2.x component products. Each development license comes with a free OPC distribution license for development and testing purposes. If you choose to distribute our components with the OPC features enabled, additional OPC distribution licenses are available.

Iocomp Component OPC Add-On Features • OPC Client capability built into most of the ActiveX controls in the 3 Component Packages we offer. See component list for details on which controls offer OPC capabilities. • Connect to OPC Servers supporting the Data Access 1.x and 2.x specifications. Intuitive Point and Click Configuration including item browsing • Support for connecting to local and remote (via DCOM) OPC Servers • Properties automatically update with live process data without any user code once connected to OPC server items. • For controls with user input enabled, the control can automatically write data to the OPC server - user input is easily disabled both at design and runtime to provide write-protection • User configurable update rate (in millisecond units) on each control - tune performance to application needs • OPC item connections can be programmatically added and removed using code for users wanting to create sophisticated applications that change their behavior at runtime based on operating conditions. • Connect one or many properties to OPC items - for example - tie configuration settings for min/max ranges to OPC items to allow the control to adapt on the fly to changing conditions • Supported development environments - Visual Basic, Visual C++, Delphi, and C++ Builder*.

Developer Benefits • Ease of configuration and use • Reduced engineering time • Faster time to completion for your projects • Little expertise of OPC interface specifics and coding details required • Affordable distribution licensing models available including runtime free distribution

Iocomp Components – Plot Pack Manual 195 Chapter 35 - OPC (OLE For Process Control)

OPC Tutorial To use the OPC features in the Plot pack is simple and straightforward. The following tutorial will guide you through the steps of setting up an OPC connection to a Channel in the Plot Pack at design-time. You can easily accomplish the same thing at run-time through your own code, and that will be covered later in this chapter.

Open the built-in property editor of the iPlot or iXYPlot component. In this example, we are using only one channel, but you can setup individual OPC connections to as many channels as you wish. Each OPC connection is tied to one and only one channel, so everything is kept separate. You will notice that there are 6 items that you will need to configure to get everything to work...

• Computer: this is the name of the computer that has the OPC server running. This can be the system that you are currently using (use the word "Local") or can be any computer on your LAN. • OPC Server: this is the name of the OPC server running on the computer previously specified. • Item: this is the name of the data item on the OPC server that you wish to connect to. • UpdateRate: this is the "desired" data update rate that you are requesting from the server. This will instruct the OPC server to send data update to you at this rate, but there is no guarantee that the OPC server will actually do this. Depends on the OPC Server. • AutoConnect: if this is checked, when the component is created, the connection to the OPC server will immediately be made and data will begin plotting immediately. To control this manually, uncheck this box and then use the OPCActivate and OPCDeactivate methods of the individual channel. • X-Value Source: each data point is made up of two double values, the X-Value Coordinate and the Y-Value Coordinate. The Y-Value coordinate is obtained from the OPC Server Item. The X-Value coordinate is obtained form the source that you select here. FIGURE 35.1 Design-time property editor showing X-Value Source combo.

196 Iocomp Components – Plot Pack Manual Chapter 35 - OPC (OLE For Process Control)

You can type in the above information manually, or you can use the built-in browsing panels by clicking on the button next to the item.

FIGURE 35.2 OPC browser windows for Computer, OPC Server, and OPC Item.

Computer Browser OPC Server Browser OPC Item Browser

To be able to receive data from an OPC server, you need to supply all of the three values above. The name of the computer is the NetBios name of the computer on the network, and the name is always preceded by two back slashes "\\". The OPC Server is the name of the server software running on the specified networked Computer. If the OPC Server is running on your local machine, use the name "Local" without any backslashes. The OPC Item is typically a double or floating point Item Tag that supplies data to the channel.

FIGURE 35.3 OPC browser windows showing the items chosen above in their respective property boxes.

Iocomp Components – Plot Pack Manual 197 Chapter 35 - OPC (OLE For Process Control)

The next two options control the "requested' speed at which updates are sent to the channel by the OPC Server as well as connection options at startup. By "requested", we mean that you are requesting that the OPC Server send you updates according to the number of milliseconds you suggest in the UpdateRate field. Depending on the OPC server, this may not be guaranteed but will be honored by the OPC Server 90%+ of the OPC servers in existence.

The Auto Connect option controls whether or not an automatic connection is made to the OPC server when the component is created on the form. You can utilize the following methods to manually initiate the connection or to break the connection to the OPC server at runtime...

iPlotX1.Channel(0).OPCActivate iPlotX1.Channel(0).OPCDeactivate

FIGURE 35.4 OPC Browser showing the available X-Value Source selections.

The final setting controls what X-Value Coordinate is paired with each data update from the OPC Server (which is the Y Value Coordinate) when plotting a data point to the channel.

198 Iocomp Components – Plot Pack Manual Chapter 35 - OPC (OLE For Process Control)

Here are the possible values...

Value Meaning iopcxvsOPCServerTimeStamp Whenever data is received, the X-Coordinate will be obtained from the OPC Server's Time Stamp iopcxvsSystemTimeStamp Whenever data is received, the X-Coordinate will be obtained from the local computer's System Time Stamp. iopcxvsElapsedTime Whenever data is received, the X-Coordinate will be obtained from the time (In Date/Time Format, be sure to setup the X-Axis for Date/Time values)elapsed since the ResetElapsedStartTime procedure has been called. iopcxvsElapsedSeconds Whenever data is received, the X-Coordinate will be obtained from the time elapsed (In Seconds, not in Date/Time format) since the ResetElapsedStartTime procedure has been called. Table 35.1

Now, when you connect to the OPC server, every time an update is sent to the channel from the OPC server, the channel will plot a data point. The X-Coordinate will be obtained from the X- Value Source Option specified, and the Y Coordinate will be obtained from the OPC Item data that is sent from the OPC Server. The data point will then be plotted on the channel!

It is important that you setup the X-Axis associated with the channel to use Date/Time formatting when using the first three X-Value Source Options: iopcxvsOPCServerTimeStamp, iopcxvsSystemTimeStamp, and iopcxvsElapsedTime as ! the actual value used will be in Date/Time format. The iopcxvsElapsedSeconds option does not use Date/Time format.

Iocomp Components – Plot Pack Manual 199 Appendix A - Plot Pack Property Editors

Appendix A - Plot Pack Property Editors

Control General FIGURE A.1

User Can Edit Objects: Use to specify whether your application user can open the runtime property editor by right-clicking on a plot object and select a popup “Edit” menu item. Only the “Edit” popup items are disabled when this option is unchecked. User Can Add/Remove Channels: Use to specify whether or not a user can use the run-time property editor to add and remove channels. Clip Annotations To Axes: Use to specify whether annotations clip to the axes they are assigned to or whether they can be drawn outside of the axes bounds. This only has a real effect if the associated X and/or Y-Axis of the annotation does not span 100% of the DataView area (i.e. Stacked Axes). Editor Form Style: Use to specify whether the run-time property editor is modal or a “non-modal, stay- on top”-type of dialog. Setting this to Stay On Top is useful in Visual Basic where you want your underlying program code to continue executing while the run-time property editor is being used. Copy To ClipBoard Format: Use to specify the image format used when using the built-in copy to clipboard functions of the Plot Component. Auto Frame Rate: Use AutoFrameRate to specify whether the control automatically activates the repaint frame rate control. When the AutoFrameRate is set to true, the control automatically calls BeginUpdate when the control is performing its next repaint. From then on, the control repaint frame rate is equal to the UpdateFrameRate no matter how many changes are maid to the control every second.

200 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Update Frame Rate: Use UpdateFrameRate to get or set the frame rate at which the control repaints.

The frame rate is used to improve performance by controlling the number of times the control repaints itself per second. To activate automatic frame rate control, the UpdateFrameRate property must be non zero and the BeginUpdate method must be called. To deactivate automatic frame rate control, call the EndUpdate method.

The frame rate can be manually controlled by using the BeginUpdate and EndUpdate methods. Make sure that the UpdateFrameRate property is set to 0 to disable automatic frame rate control. Your code will need to keep track of the last update before beginning a new frame. To begin a new frame, call the EndUpdate method and then the BeginUpdate method to start the next frame. Background Color: Use BackgroundColor to read or change the background color of the control. Border Style: Use BorderStyle to provide the control with a three-dimensional beveled look. Value Meaning ibsNone No border. ibsRaised The outer border is raised. ibsLowered The outer border is lowered. Outer Margin: Use OuterMarginLeft, OuterMarginRight, OuterMarginTop, or OuterMarginBottom to set the margin between the left, right, top, or bottom side edge of the control and the internal drawn elements. The values are specified in pixels.

Iocomp Components – Plot Pack Manual 201 Appendix A - Plot Pack Property Editors

Control Title FIGURE A.2

Note: this property page has been depreciated. The title property now modifies Label Index#0. These properties are provided for backward compatibility only. Title Visible: Use to show or hide the main chart title displayed above the DataView area. Title Text: Use to set the Title Text of the main chart title. Title Margin: Use to set the margin between the bottom of the title and the DataView area. Title Font: Use to se the font of the title.

These properties have been depreciated in favor of our multiple label support. Please use the ! Labels tab to set properties for the Title Label and other labels in the Plot Component.

202 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Control Print FIGURE A.3

Show Dialog: Use PrinterShowDialog to specify whether the printer setup dialog is shown to the user when the PrintChart method is called. If Enabled, the user can select a local or network printer, specify the orientation, number of copies, and etc before actually printing the chart. Orientation: Use PrinterOrientation to set the orientation of the chart on the printed page. Value Meaning poPortrait Portrait poLandscape Landscape Margin: The left, right, top, and bottom margins on the printed page. Document Name: Used to set the document name displayed on some printer displays when the document is being printed.

Iocomp Components – Plot Pack Manual 203 Appendix A - Plot Pack Property Editors

Control Hints FIGURE A.4

Hints Show: Use HintsShow to specify whether Help Hints are shown for the entire control. Hints Pause: Use HintsPause to get or set the time interval that passes before the control's Help Hint appears when the user places the mouse pointer on a object. The HintsPause value is in milliseconds. Hints Hide Pause: Use HintsHidePause to get or set the time interval to wait before hiding the Help Hint if the mouse has not moved from the object. The HintsHidePause value is in milliseconds.

Control Images FIGURE A.5

204 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Add: Use to add a bitmap image to the component’s built-in image list. Images are used in other parts of the component such as in the Bitmap Annotations. All bitmaps added to a particular image list must have the same dimensions as the first image. If the added image size differs from the first image, then it will be either cropped, if it is too large, or padded with the transparent color and centered(the color of the lower-right-hand pixel of the image), if it is too small. There are currently three custom image lists supported. Remove: Remove the selected image from the image list. Clear: Use to clear out all images from the image list.

Control File I/O FIGURE A.6

Log File Name: Use LogFileName to get or set the filename (including path) for the log file. This is the log file for all axes.

Warning! All channels must be synchronized. You must use the AddDataArray method when adding data to the plot component when using the main plot interface’s logging feature. If you wish to use asynchronous channels, then you must use the LogFileName logging feature off of each channel.

Iocomp Components – Plot Pack Manual 205 Appendix A - Plot Pack Property Editors

Log Buffer Size: Use LogBufferSize to get or set the size of the log buffer. When logging is active, data will flow into the log buffer if the LogBufferSize is greater than 0. When the buffer is filled, then data will be written to the log file and the buffer cleared. This is useful if you want to regulate how often data is written to the log file. If this value is 0, then data is written to the log file after every new data point is added to the chart.

The value is in number of data points per channel. If you have 5 channels and set this value to 10, then the log will be written to and the buffer cleared after 50 data points have been accumulated.

Warning! All channels must be synchronous. You must use the AddDataArray method when adding data to the plot component when using the main plot interface’s logging feature. If you wish to use asynchronous channels, then you must use the LogBufferSize logging feature off of each individual channel.

Note: if the log is deactivated, the buffer will automatically be flushed to the log file and cleared. Properties Save: Call SavePropertiesToFile to stream out all of the properties of the plot component to a file. Properties Load: Call LoadPropertiesFromFile to stream in all of the properties of the plot component from a file.

Translation FIGURE A.7

Add: Adds a translation string pair to the list of translations. Remove: Removes the selected translation from the list of translations. ClearAll: Removes all translations from the list of translations. Save: Exports a tab delimited text file of translation string pairs. Load: Loads a tab delimited text file of translation string pairs. Original String: The English string in the original component to be translated. Case-sensitive. Leading and trailing spaces are NOT ignored.

206 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Replacement String: The translated string, which replaces the Original String.

Annotation Defaults FIGURE A.8

Font: Specifies the default font attributes used when creating annotation objects. Pen Color: Specifies the pen color used when drawing the annotation object. Pen Style: Use MarkersPenStyle to get or set the pen style used when drawing data markers. Value Meaning psSolid A solid line psDash A line made up of a series of dashes psDot A line made up of a series of dots psDashDot A line made up of alternating dashes and dots psDashDotDot A line made up of a serious of dash-dot-dot combinations No line is drawn (used to omit the line around shapes that psClear draw an outline using the current pen) A solid line, but one that may use a dithered color if psInsideFrame Width is greater than 1 Pen Width: Use MarkersPenWidth to get or set the pen width used when drawing data markers. Brush Color: Use MarkersBrushColor to get or set the brush color used to draw data markers. Brush Style: Use MarkersBrushStyle to get or set the brush style used when drawing data markers. Value Meaning bsSolid Solid bsClear Clear bsHorizontal Horizontal Lines bsVertical Vertical Lines Diagonal Bottom-Left bsFDiagonal to Top-Right Diagonal Top-Left to bsBDiagonal Bottom-Right

Iocomp Components – Plot Pack Manual 207 Appendix A - Plot Pack Property Editors

Value Meaning Combination of bsCross bsHorizontal and bsVertical Combination of bsDiagCross bsFDiagonal and bsBDiagonal

Visual Layout Manager FIGURE A.9

How To Use: The Layout Manager is a visual, graphical representation of the individual plot component objects as they are drawn on the component. You can drag-and-drop individual items to reposition them within the control. You can also change the width and height of objects by placing your mouse cursor over one of the ends of the objects (look for the cursor to change to a double arrow) and dragging them to the desired size. If you drop one axes object on another, and they do not overlap, then the axes will stack on top of one another. To flip the X and Y-Axes, right click anywhere in the Layout Manager for a menu item to rotate the X and Y-Axes. Toolbar: The Toolbar object. This item cannot be moved at this time. A feature to reposition this item will be added in future versions. Label: The Label Object. In this example, the only label in the component is named “Title”. There must always be at least one label in the component for backward compatibility with older versions, though it can be hidden. Data View: The object which contains the plotted data. All objects move in relation to this object, so it is fixed. X-Axis: An individual X-Axis. If you have added multiple X-Axes, there would be multiple X-Axis objects which you could reorder or stack. Y-Axis: An individual Y-Axis. If you have added multiple Y-Axes, there would be multiple Y-Axis objects which you could reorder or stack. Legend: The Legend Object. This object cannot be flipped at this time, only moved. Only one Legend object is supported at this time.

208 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Channels General FIGURE A.10

Channel List: A listing of the channels that have been added to the Chart. Add Button: Adds a channel to the list Remove Button: Removes the selected channel from the list Name: Use Name to set the Plot Object’s name. This name can then be used to reference the object. There is no restrictions on the length of the name or the characters used. Title: Use TitleText to get or set the title text for the channel. This is the title that is displayed in the legend for this channel. Ring Buffer Size: Use RingBufferSize to get or set the size of the data buffer used for storing channel data. By setting this property to a non-zero value, the ring buffer feature is enable. To disable the ring buffer feature, set this property to 0. The ring buffer will remain a constant size no matter how many data points are added to the channel and will act like a FIFO (First In First Out). Visible: Use the Visible property to show or hide a specific Plot Object. Visible In Legend: Use VisibleInLegend to specify whether the channel is shown in the legend. Popup Enabled: Use the PopupEnabled property to enable or disable the Popup Menu of a Plot Object. The Popup Menu is shown when a user right-clicks on this Plot Object.

Setting this property to FALSE is useful if you don’t want the Popup Menu functionality of this Plot Object in your particular application.

Note: when the Enabled property is set to FALSE, then this property will have no effect and the Popup will be disabled. Fast Draw: Enables or disables the Fast Draw feature. This feature dramatically speeds up redraws to the screen if you are displaying large data sets (>100000 data points). Color: Use Color to get or set the color of the channel. The Color property is used by the Trace drawing routine and is used by default for the Markers and Fill drawing routines.

Iocomp Components – Plot Pack Manual 209 Appendix A - Plot Pack Property Editors

Data Style: Use to set the type of dataset that the channel will use. Some styles use more memory per data point to utilize expanded features of the component while other styles use less memory (and correspondingly faster access speeds, memory utilization, and max # of data points supported) with a more limited feature set. Maximum # Bytes of Data Per Data Points (32-bit Value Meaning Point Windows) The original data style for the component. This data set supports all ipdsStandard of the extended features of the 24 bytes 89,478,485 component and stores values in double-precision format. A single-precision, compact data storage type that uses 8 bytes per data point. This data set does not support the following features...· ipdsCompact 8 bytes 268,435,455 Empty Data Points Null Data Points Individual Marker Hiding Individual Marker Styles An single-precision, extremely compact data storage type for fixed- interval data sets that uses 4 bytes per data point. The first and second data point x-values added to the channel determine the fixed-interval used for the entire data set. For example, if the first data point's X-Value is 1, and the second data point's X-Value is 6, then the X-Value interval between all data points in this channel will be fixed at ipdsCompactInterval 4 bytes 536,870,911 5 (Interval = 6 - 1 = 5). All future X- Values will be ignored. This was done to keep backward compatibility with previous log files and data sets. This data set does not support the following features...· Empty Data Points Null Data Points Individual Marker Hiding Individual Marker Styles Non-Fixed X-Interval Data Points X-Axis Name: Use XAxisName to get or set the name of the x-axis used for plotting the channel x data against. If the XAxisName is not a valid x-axis name, the channel data will not be drawn. Y-Axis Name: Use YAxisName to get or set the name of the Y-Axis used for plotting the channel y data against. If the YAxisName is not a valid Y-Axis name, the channel data will not be drawn. X-Axis Tracking Enabled: Use XAxisTrackingEnabled to specify whether the channel sends tracking data to its assigned x-axis.

210 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Y-Axis Tracking Enabled: Use YAxisTrackingEnabled to specify whether the channel sends tracking data to its assigned Y-Axis.

Channel Trace FIGURE A.11

Visible: Use TraceVisible to specify whether the channel trace line is visible. Typically the trace line is hidden for a scatter type plot. Line Style: Use TraceLineStyle to get or set the line style of the channel trace line. Value Meaning iplsSolid A solid line iplsDash A line made up of a series of dashes iplsDot A line made up of a series of dots iplsDashDot A line made up of alternating dashes and dots iplsDashDotDot A line made up of a serious of dash-dot-dot combinations Line Width: Use TraceLineWidth to get or set the pen width used when drawing the channel trace line.

Iocomp Components – Plot Pack Manual 211 Appendix A - Plot Pack Property Editors

Interpolation FIGURE A.12

Style: The type of interpolation used to draw the trace line between data points in the channel. To turn off the trace line, go back to the trace tab and uncheck “Visible”. Value Meaning ipistStraightLine Draws a straight trace line between each data point. Draws a curve based on Cubic Spline curve fitting ipistCubicSpline interpolation equations. Draws a curve based on Polynomial Interpolation curve fitting equations and is only good for small data sets ipistPolynomial (~100 data points)Polynomial degree is fixed at [n – 1] or [n =number of data points] Draws a curve based on Rational Interpolation curve fitting equations. This is an alternative to the ipistRational ipistPolynomial Interpolation with functions that have poles. This interpolation is good for small to medium- sized data sets. Draws a curve based on Differential Interpolation. This style draws horizontal and vertical lines between data points. A line is drawn horizontal between one point’s X ipistDifferential and Y-Value to the next data point’s X-Value. A vertical line is then drawn perpendicular from the end point up or down to the Y-Value of the second data point.

212 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Channels Markers FIGURE A.13

Show: Use MarkersVisible to specify whether the data markers are visible. Allow Individual: Use MarkersAllowIndividual to specify whether the DataMarkerShow and DataMarkerStyle properties are used to draw individual data point data markers.

When this property is set to True, then the data markers are initially drawn using the MarkersStyle property but can be modified individually with the DataMarkerShow and DataMarkerStyle properties. When this property is set to False, then all of the data markers are drawn using the MarkersStyle property of the channel. Style: Use MarkersStyle to get or set the style of the data markers. Value Meaning ipmsCircle Circle ipmsSquare Square ipmsDiamond Diamond ipmsCross Cross ipmsPlus Plus ipmsTriangleUp Triangle Pointing Up ipmsTriangleDown Triangle Pointing Down ipmsTriangleLeft Triangle Pointing Left ipmsTriangleRight Triangle Pointing Right ipmsVerticalLine A Vertical Line ipmsHorizontalLine A Horizontal Line Size: Use MarkersSize to get or set the size of data markers. The MarkersSize value is in pixels. Pen Use Channel Color: Use MarkersPenUseChannelColor to specify whether markers use the channel color for the pen color. When MarkersPenUseChannelColor is set to True, the pen uses the color of the Color property. When MarkersPenUseChannelColor is set to False, the pen uses the color of the MarkersPenColor property. Pen Style: Use MarkersPenStyle to get or set the pen style used when drawing data markers.

Iocomp Components – Plot Pack Manual 213 Appendix A - Plot Pack Property Editors

Value Meaning psSolid A solid line psDash A line made up of a series of dashes psDot A line made up of a series of dots psDashDot A line made up of alternating dashes and dots psDashDotDot A line made up of a serious of dash-dot-dot combinations No line is drawn (used to omit the line around shapes that psClear draw an outline using the current pen) A solid line, but one that may use a dithered color if psInsideFrame Width is greater than 1 Pen Color: Use MarkersPenColor to get or set the pen color used to draw data markers. Pen Width: Use MarkersPenWidth to get or set the pen width used when drawing data markers. Brush Use Channel Color: Use MarkersBrushUseChannelColor to specify whether markers use the channel color for the brush color. When MarkersBrushUseChannelColor is set to True, the brush uses the color of the Color property. When MarkersBrushUseChannelColor is set to False, the brush uses the color of the MarkersBrushColor property. Brush Style: Use MarkersBrushStyle to get or set the brush style used when drawing data markers. Value Meaning bsSolid Solid bsClear Clear bsHorizontal Horizontal Lines bsVertical Vertical Lines bsFDiagonal Diagonal Bottom-Left to Top-Right bsBDiagonal Diagonal Top-Left to Bottom-Right Combination of bsHorizontal and bsCross bsVertical Combination of bsFDiagonal and bsDiagCross bsBDiagonal Brush Color: Use MarkersBrushColor to get or set the brush color used to draw data markers.

214 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Channels Bar FIGURE A.14

Enabled: Use to turn on the bar feature of the channel. When the feature is turned on, a bar of the specified Width starting at the specified Reference will be drawn to the Data point’s Y coordinate. Width: Use to specify the width of the bar in units of the X-Axis. Reference: Use to specify the point at which the bar begins to draw in units of the Y-Axis. Pen Use Channel Color: Use to specify whether the color of the pen used to draw the bar is derived from the channel’s color or the Pen Color property. Pen Style: Use to specify the style of the pen used to draw the bar. Pen Color: Use to specify the color of the pen used to draw the bar. Pen Width: Use to specify the width of the pen used to draw the bar. Brush Use Channel Color: Use to specify whether the color of the brush used to draw the bar is derived from the channel’s color or the Brush Color property. Brush Style: Use to specify the style of the brush used to draw the bar. Brush Color: Use. To specify the color of the brush used to draw the bar

Iocomp Components – Plot Pack Manual 215 Appendix A - Plot Pack Property Editors

Channels Fill FIGURE A.15

Enabled: Use FillEnabled to specify whether a fill is drawn underneath the channel data. Use Channel Color: Use FillUseChannelColor to specify whether the fill uses the channel color when drawing the fill underneath the channel data. When FillUseChannelColor is set to True, the fill color used is the Color property value. When FillUseChannelColor is set to False, the fill color used is the FillColor property value. Reference: Use FillReference to get or set the reference line that the fill is drawn to on the Y-Axis. Color: FillColor to get or set the brush color used to paint the fill under the data. Style: Use FillStyle to get or set the brush style used when drawing the fill underneath the channel data. Value Meaning bsSolid Solid bsClear Clear bsHorizontal Horizontal Lines bsVertical Vertical Lines bsFDiagonal Diagonal Bottom-Left to Top-Right bsBDiagonal Diagonal Top-Left to Bottom-Right bsCross Combination of bsHorizontal and bsVertical bsDiagCross Combination of bsFDiagonal and bsBDiagonal

216 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Channels Digital FIGURE A.16

Enabled: Use DigitalEnabled to specify whether the data in the channel is interpreted as digital or analog data.. If DigitalEnabled is TRUE, then values of 0 and 1 are plotted against DigitalReferenceLow and DigitalReferenceHigh respectively.

Y coordinate values that are equal to 0 (i.e. Value = 0) are plotted on the scale at the Y coordinate specified by DigitalReferenceLow.

X coordinates that are not equal to 0 (i.e. 0 < Value > 0) are plotted on the scale at the Y coordinate specified by DigitalReferenceHigh. Reference High: Use DigitalReferenceHigh to get or set the Y coordinate for digital high values or Logic = TRUE used for plotting data points while in Digital Mode when the value is not equal to 0 (i.e. 0 < Value > 0). Reference Low: Use DigitalReferenceLow to get or set the Y coordinate for digital low values or Logic = FALSE used in Digital Mode while in Digital Mode when the value is equal to 0 (i.e. Value = 0). Reference Style: Use DigitalReferenceStyle to get or set the formatting style of a digital channel. Value Meaning DigitalReferenceLow and DigitalReferenceHigh ipdrScale properties are interpreted as actual values on the associated Y-Axis Scale DigitalReferenceLow and DigitalReferenceHigh properties are interpreted as a percentage of the distance ipdrPercent from the bottom of the DataView (0%) and the top of the DataView (100%) [Note: Acceptable values are between 0 and 100]

Iocomp Components – Plot Pack Manual 217 Appendix A - Plot Pack Property Editors

Channel File I/O FIGURE A.17

Log File Name: Use LogFileName to get or set the filename (including path) for the log file. This is the log file only for the associated channel.

Note: Channels may be synchronous or asynchronous. If you are only using synchronous data, you can use the LogFileName logging feature off of the main component interface to save all channel data to a single log file. Buffer Size: Use LogBufferSize to get or set the size of the log buffer. When logging is active, data will flow into the log buffer if the LogBufferSize is greater than 0. When the buffer is filled, then data will be written to the log file and the buffer cleared. This is useful if you want to regulate how often data is written to the log file. If this value is 0, then data is written to the log file after every new data point is added to the chart.

Note: Channels may be synchronous or asynchronous. If you are only using synchronous data, you can use the LogBufferSize logging feature off of the main component interface to save all channel data to a single log file.

Note: if the log is deactivated, the buffer will automatically be flushed to the log file and cleared. Properties Save: Call SavePropertiesToFile to stream out all of the properties of the associated channel to a file. Properties Load: Call LoadPropertiesFromFile to stream in all of the properties of the associated channel from a file.

218 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Channel OPC FIGURE A.18

Computer: The name of the OPC server that you wish to connect this channel to. Each channel can have their own independent settings. OPC Server: The name of the OPC server running on the computer specified by “Computer” Item: The name of the data item on the OPC Server that you wish to connect the channel to. UpdateRate: Use to specify the “requested” update rate from the server in milliseconds. The actual update rate is dictated by the server, so this is only a request. Auto Connect: Use to instruct the component to automatically create a connection to the server and begin to acquire data immediately during component creation. X-Value Source: Use to specify how X-data is acquired for each incoming piece of Y-data. Value Meaning Whenever data is received, the X-Coordinate will be iopcxvsOPCServerTimeStamp obtained from the OPC Server's Time Stamp Whenever data is received, the X-Coordinate will be iopcxvsSystemTimeStamp obtained from the local computer's System Time Stamp. Whenever data is received, the X-Coordinate will be obtained from the time (In Date/Time Format, be sure to iopcxvsElapsedTime setup the X-Axis for Date/Time values)elapsed since the ResetElapsedStartTime procedure has been called. Whenever data is received, the X-Coordinate will be obtained from the time elapsed (In Seconds, not in iopcxvsElapsedSeconds Date/Time format) since the ResetElapsedStartTime procedure has been called.

Iocomp Components – Plot Pack Manual 219 Appendix A - Plot Pack Property Editors

Cursors General FIGURE A.19

Cursor Name: Use Name to set the Plot Object’s name. This name can then be used to reference the object. There is no restrictions on the length of the name or the characters used. Cursor Style: Use Style to get or set the style of the data cursor object. The style determines the type and behavior of the cursor.

Note: data points are interpolated when used with the iPlot component.

These are the possible values: Value Meaning Displays Data Point’s ValueX and ValueY with a single pointer line for the iPlot component and a ipcsValueXY cross-hair (two pointer lines) for the iXYPlot component. Displays Data Point’s ValueX with a single pointer ipcsValueX line Displays Data Point’s ValueY with a single pointer ipcsValueY line Displays Data Points’ X Span between to pointer ipcsDeltaX lines.Use ValueX to retrieve the X Span. Displays Data Points’ Y Span between to pointer ipcsDeltaY lines.Use ValueY to retrieve the Y Span. Displays Frequency between two pointer lines. Uses scale values and CursorScaler property of the ipcsInverseDeltaX associated channel’s X-Axis. Use ValueX to retrieve the calculated value.

220 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Cursor Channel Name: Use ChannelName to get or set the name of the channel used for referencing. This property associates a particular channel’s data with the cursor. Data from the channel is then used by the cursor to display individual data points, ranges, and other cursor calculated values. Pointer 1 Position: Use Pointer1Position to get or set the position of the first cursor pointer. The units of the Pointer1Position are in reference to the DataView area in percent. Therefore the only valid values are between 0 and 100.

If the data cursor is horizontal, the position is in reference to the Y-Axis side of the DataView area with 0 being the bottom of the DataView and 100 being the top of the data view.

If the data cursor is vertical, the position is in reference to the X-Axis side of the DataView area with 0 being the left side of the DataView and 100 being the right side of the data view.

For data cursors of style ValueXY (iPlot Component Only), ValueX, and ValueY, this property sets the position of the single cursor line used with these data cursor styles. Pointer 2 Position: Use Pointer2Position to get or set the position of the second cursor pointer. The units of the Pointer2Position are in reference to the DataView area in percent. Therefore the only valid values are between 0 and 100.

For data cursors of style ValueXY (iPlot Component Only), ValueX, and ValueY, this property is ignored since they don’t have a second cursor line.. Pointer Color: Use Color to get or set the color of the data cursor line or lines. This property is overridden if the UseChannelColor property is set to True. Use Channel Color: Use UseChannelColor to specify whether the data cursor line use the channel color for the line color. When UseChannelColor is set to True, the data cursor line is drawn using the associated Channel’s Color property. When UseChannelColor is set to False, the data cursor line is drawn using the Data Cursor’s Color property. Cursor Font: Use Font to change the font attributes of the data cursor hint. Popup Enabled: Use the PopupEnabled property to enable or disable the Popup Menu of a Plot Object. The Popup Menu is shown when a user right-clicks on this Plot Object.

Setting this property to FALSE is useful if you don’t want the Popup Menu functionality of this Plot Object in your particular application.

Note: when the Enabled property is set to FALSE, then this property will have no effect and the Popup will be disabled.

Iocomp Components – Plot Pack Manual 221 Appendix A - Plot Pack Property Editors

Cursors Hint FIGURE A.20

Show: Use HintShow to specify whether the hint is shown next to the data cursor in the DataView area. You will generally want to leave this value set to TRUE so that the X and/or Y values of the cursor are displayed next to the cursor.

When this property is set to false, you will need to use the OnCursorChange event to be notified when the cursor moves so that you can externally display or react to the X and Y values of the cursor.. Hide On Release: Use HintHideOnRelease to specify whether the hint is automatically hidden when the user releases the mouse button. The hint will be shown when the user selects, clicks down, and while moving the cursor in the DataView area. If this property is set to True, then the hint will immediately be hidden when the mouse is released. Position: Use HintPosition to get or set the position of a hint object next to a data cursor. The value is specified in percent of the horizontal or vertical range of the DataView Area.

If HintPosition = 25 and the cursor is horizontal, then the left-side of the hint will be 25% of the distance from the left side of the DataView area.. If HintPosition = 60 and the cursor is vertical, then the top side of the hint will be 60% of the distance from the top side of the DataView area. Orientation Side: Use HintOrientationSide to get or set the orientation of the hint displayed next to the cursor.

Note: the orientation will automatically be flipped if a cursor is moved in such a way as to move the hint window outside of the DataView area (i.e. there is no room between the cursor and the edge of the DataView boundaries).

These are the possible values: Value Meaning Displays the hint to the right of a vertical cursor and iosBottomRight below a horizontal cursor.

222 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Value Meaning Displays the hint to the left of a vertical cursor and iosTopLeft above a horizontal cursor.

Cursors Menu Items FIGURE A.21

Value XY Visible: Use MenuItemVisibleValueXY to specify whether right-click, context-sensitive menu for the data cursor object displays the “ValueXY” entry. This menu item allows the user to change the cursor to display both X and Y values. Value X Visible: Use MenuItemVisibleValueX to specify whether right-click, context-sensitive menu for the data cursor object displays the “ValueX” entry. This menu item allows the user to change the cursor to display only X values. Value Y Visible: Use MenuItemVisibleValueY to specify whether right-click, context-sensitive menu for the data cursor object displays the “ValueY” entry. This menu item allows the user to change the cursor to display only Y values. Delta X Visible: Use MenuItemVisibleInverseDeltaX to specify whether right-click, context-sensitive menu for the data cursor object displays the “InverseDeltaX” entry. This menu item allows the user to change the cursor to display the inverse of the range of X values between two cursor lines (value = 1/range). This is typically used in conjunction with the Axis CursorScaler property to display calculated frequency values. Delta Y Visible: Use MenuItemVisibleDeltaY to specify whether right-click, context-sensitive menu for the data cursor object displays the “DeltaY” entry. This menu item allows the user to change the cursor to display the range of Y values between two cursor lines. Inverse Delta X Visible: Use MenuItemVisibleInverseDeltaX to specify whether right-click, context- sensitive menu for the data cursor object displays the “InverseDeltaX” entry. This menu item allows the user to change the cursor to display the inverse of the range of X values between two cursor lines (value = 1/range). This is typically used in conjunction with the Axis CursorScaler property to display calculated frequency values.

Iocomp Components – Plot Pack Manual 223 Appendix A - Plot Pack Property Editors

Value XY Caption: Use MenuItemCaptionValueXY to specify the caption of the “ValueXY” right- click, run-time popup menu for the data cursor object. This is useful for customizing the menu for application specific descriptions. The menu item allows the user to change the cursor to display both X and Y values. Value X Caption: Use CaptionValueX to specify the caption of the “ValueX” right-click, run-time popup menu for the data cursor object. This is useful for customizing the menu for application specific descriptions. The menu item allows the user to change the cursor to display only X values. Value Y Caption: Use MenuItemCaptionValueY to specify the caption of the “ValueY” right-click, run-time popup menu for the data cursor object. This is useful for customizing the menu for application specific descriptions. The menu item allows the user to change the cursor to display only Y values. Delta X Caption: Use MenuItemCaptionDeltaX to specify the caption of the “DeltaX” right-click, runtime popup menu for the data cursor object. This is useful for customizing the menu for application specific descriptions. The menu item allows the user to change the cursor to display the range of X values between two cursor lines. Delta Y Caption: Use MenuItemCaptionDeltaY to specify the caption of the “DeltaY” right-click, runtime popup menu for the data cursor object. This is useful for customizing the menu for application specific descriptions. The menu item allows the user to change the cursor to display the range of Y values between two cursor lines. Inverse Delta X Caption: Use MenuItemCaptionDeltaX to specify the caption of the “InverseDeltaX” right-click, run-time popup menu for the data cursor object. This is useful for customizing the menu for application specific descriptions. The menu item allows the user to change the cursor to display the inverse of the range of X values between two cursor lines (value = 1/range). This is typically used in conjunction with the Axis CursorScaler property to display calculated frequency values..

Limits General FIGURE A.22

224 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Name: Use Name to set the Plot Object’s name. This name can then be used to reference the object. There is no restrictions on the length of the name or the characters used. Style: Use Style to get or set the style of the limit object. The style determines the type of the limit and how it is drawn on the screen and manipulated.

These are the possible values: Value Meaning Displays a single line perpendicular to the X-Axis at iplsLineX a position specified by Line1Position. Displays a single line perpendicular to the Y-Axis at iplsLineY a position specified by Line1Position. Displays a filled or two line band perpendicular to the iplsBandX X-Axis specified by the Line1Position and . Displays a filled or two line band perpendicular to the iplsBandY Y-Axis specified by the Line1Position and Line2Position properties. Displays a filled or two line band using elements (upper and lower limit values specified for a iplsPolyBandX particular Y-Axis positions) added by the AddBandElement method. Displays a filled or two line band using band elements (upper and lower limit values specified for a iplsPolyBandY particular Y-Axis positions) added by the AddBandElement method.

Line 1 Position: Use Line1Position to get or set the position of the first limit line. The units of the Line1Position are in reference to the values on the referenced axis of interest. This property is used for all limit line styles.

For limit lines of style LineX and LineY, this property sets the position of the single limit line used with these limit styles. CursorStyle Position Value Meaning References the X-Axis scale referenced in the iplsLineX XAxisName property. References the Y-Axis scale referenced in the iplsLineY YAxisName property. For limit lines of style BandX and BandY, this property sets the position of the first cursor line with these fill-region or dual-line data limit line styles. For limit lines of style PolyBandX or PloyBandY, this property is ignored. CursorStyle Position Value Meaning References the X-Axis scale referenced in the iplsBandX XAxisName property. References the Y-Axis scale referenced in the iplsBandY YAxisName property. iplsPolyBandX Property Ignored. Use AddBandElement. iplsPolyBandY Property Ignored. Use AddBandElement.

Iocomp Components – Plot Pack Manual 225 Appendix A - Plot Pack Property Editors

Line 2 Position: Use Line2Position to get or set the position of the second limit line. The units of the Line2Position are in reference to the values on the referenced axis of interest.

For limit lines of style LineX and LineY, this property is ignored. CursorStyle Position Value Meaning iplsLineX Property Ignored. Use Line1Position instead. iplsLineY Property Ignored. Use Line1Position instead. For limit lines of style BandX and BandY, this property sets the position of the second cursor line with these fill-region or dual-line data limit line styles. For limit lines of style PolyBandX or PloyBandY, this property is ignored. CursorStyle Position Value Meaning References the X-Axis scale referenced in the iplsBandX XAxisName property. References the Y-Axis scale referenced in the iplsBandY YAxisName property. iplsPolyBandX Property Ignored. Use AddBandElement. iplsPolyBandY Property Ignored. Use AddBandElement. Fill Style: Use FillStyle to get or set the fill style used when drawing the fill between limit lines. This property has no effect if the Limit Style property is set to iplsLineX or iplsLineY.

These are the possible values: Value Meaning bsSolid Solid. Clear. No fill will be created, but two solid lines of line width 1 using the Limit’s Color property will be bsClear drawn at the Line1Position and Line2Position positions. bsHorizontal Horizontal Lines. bsVertical Vertical Lines. bsFDiagonal Diagonal Bottom-Left to Top-Right. bsBDiagonal Diagonal Top-Left to Bottom-Right. bsCross Combination of bsHorizontal and bsVertical. bsDiagCross Combination of bsFDiagonal and bsBDiagonal. Line Style: Use LineStyle to get or set the line style of the limit line or lines. This property is ignored if the Limit’s Style property is set to iplsBandX, iplsBandY, iplsPolyBandX, or iplsPolyBandY.

These are the possible values: Value Meaning psSolid A solid line. psDash A line made up of a series of dashes. psDot A line made up of a series of dots. psDashDot A line made up of alternating dashes and dots. A line made up of a series of dash-dot-dot psDashDotDot combinations. psClear No line is drawn. A solid line, but one that may use a dithered color if psInsideFrame Width is greater than 1.

226 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Note: Only the psInsideFrame style will produce a dithered color to match a Color property that is not in the color table. All others choose the closest color from the Windows color table. Note: Dotted or dashed pen styles are not available when the Width property is not 1 or 0. Line Width: Use LineWidth to get or set the pen width used when drawing the limit line or lines. This property is ignored if the Limit’s Style property is set to iplsBandX, iplsBandY, iplsPolyBandX, or iplsPolyBandY. Color: Use Color to get or set the color of the limit line or lines… Value Meaning Displays a single line perpendicular to the X-Axis at iplsLineX a position specified by Line1Position. Displays a single line perpendicular to the Y-Axis at iplsLineY a position specified by Line1Position. Displays a filled or two line perpendicular to the X- iplsBandX Axis specified by the Line1Position and Line2Position properties. Displays a filled or two line band perpendicular to the iplsBandY Y-Axis specified by the Line1Position and Line2Position properties. Displays a filled or two line band using elements (upper and lower limit values specified for a iplsPolyBandX particular Y-Axis positions) added by the AddBandElement method. Displays a filled or two line band using band elements (upper and lower limit values specified for a iplsPolyBandY particular Y-Axis positions) added by the AddBandElement method. X-Axis Name: Use XAxisName to get or set the name of the X-Axis used for referencing. This property is used by the Line1Position, Line2Position, and AddBandElement properties and methods for positioning the limit line or lines against the specified X-Axis. Y-Axis Name: Use YAxisName to get or set the name of the Y-Axis used for referencing. This property is used by the Line1Position, Line2Position, and AddBandElement properties and methods for positioning the limit line or lines against the specified Y-Axis.

Iocomp Components – Plot Pack Manual 227 Appendix A - Plot Pack Property Editors

Labels FIGURE A.23

Name: Use Name to set the Plot Object’s name. This name can then be used to reference the object. There is no restrictions on the length of the name or the characters used. Visible: Use the Visible property to show or hide a specific Plot Object. Font: Use Font to change the font attributes of the Label Object text. Caption: Use Caption to get or set the Label Object display text. To hide the caption, see the Visible property of the Label Object .

Note: for backward compatibility, the TitleText property will always modify the Caption property of Label Index 0. Alignment: Set Alignment to specify how the text is aligned within the ClientRect of the label object.

These are the possible values: Value Meaning iahCenter Text is centered in the control. iahLeft Text is left-justified: Begins at the left edge of the control. iahRight Text is right-justified: Ends at the right edge of the control. Margin: Use Margin to get or set the margin between the Caption and the top, bottom, left, and right of the Label Object. The Margin values is in percent of the title font height or width.

228 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Axes General FIGURE A.24

Name: Use Name to set the Plot Object’s name. This name can then be used to reference the object. There is no restrictions on the length of the name or the characters used. Min: Use Min to get or set the minimum value that will be displayed on the axis. Span: Use Span to get or set the range displayed on the axis. Desired Start: Use DesiredStart to get or set the desired start for the axis scale. This property will affect what value will be on the first major tick of the axis.

Let’s say the Axis starts at 0, but you want it to start at 9. Setting this value to 9 will instruct the Axis to start the first major tick on 9 and then follow the DesiredIncrement property for all further major ticks.

Note: due to performance issues, this property only has effect if the value exists in the visible axis (i.e. the value must be equal to or between the axis’ min and max values). This feature is only intended to be used with static scales (scales that do not scroll).

Set this property to 0 to disable this feature and use the default 1-2-5 rules.

Iocomp Components – Plot Pack Manual 229 Appendix A - Plot Pack Property Editors

Desired Increment: Use DesiredIncrement to get or set the desired increment for the axis scale.

If this property is set to 0, then the AutoScale feature of the axis scale will automatically adjust the scale to follow a 1-2-5 rule, which ensures that the scale major ticks and labels fall along “human-readable” whole numbers such as “0,25,50,75,100”, “0,10,20,30,40,50,60,70,80,90,100”, etc. depending on your min and span property settings.

If this property is greater than zero, the AutoScale feature will attempt to create a scale using your increment values depending on your min and span property settings, adding major ticks and labels that will fit in the area used by the scale. If the AutoScale finds that not all of the labels will fit in the scale area (depends on your font properties), then it will attempt to fit as many labels as possible using this setting.

For example, if you want the scale to increment by values of “2.5”, and your min and span properties are 0 and 50, then the AutoScale code will attempt to create a scale with “0, 2.5, 5.0, 7.5, 10, 12.5, …, 40, 42.5, 45, 47.5, 50”. If not all of the labels can fit in the space allocated to the scale, it will attempt to fit as many labels as possible using the 1-2-5 rule.. Scale Type: Use ScaleType to get or set the type of scale. When the scale type is set to ipstLog10, the Min and Span properties are restricted to being greater than 0. Value Meaning ipstLinear Linear ipstLog10 Logarithmic Base 10 Visible: Use the Visible property to show or hide a specific Plot Object. Grid Lines Visible: Use to specify whether the grid-lines drawn for this axis are shown or hidden. Enabled: Use the Enabled property to enable or disable the UI (User Interface) of a Plot Object.

When this property is set to TRUE, then the UI functionality (ability to move a scale, scroll a list, click on buttons, etc) of the Plot Object is enabled. Note that setting this property to TRUE will not override other properties that affect the UI of this Plot Object.

When this property is set to FALSE, then the UI functionality of the Plot Object is disabled. Note that this will override all other properties that affect the UI of this Plot Object.

Note: when a Plot Object is disabled, the Plot Object will not “look disabled” like standard textboxes or labels. Only the UI will be disabled. Popup Enabled: Use the PopupEnabled property to enable or disable the Popup Menu of a Plot Object. The Popup Menu is shown when a user right-clicks on this Plot Object.

Setting this property to FALSE is useful if you don’t want the Popup Menu functionality of this Plot Object in your particular application.

Note: when the Enabled property is set to FALSE, then this property will have no effect and the Popup will be disabled. Reverse Scale: Use ReverseScale to specify whether the scale is reversed. If ReverseScale is False, the axis goes from left to right for horizontal orientation or bottom to top for vertical orientation. If ReverseScale is True, the axis goes from right to left for horizontal orientation, or top to bottom for vertical orientation.

230 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Restore Values On Resume: Use RestoreValuesOnResume to set whether or not the axis restores the original axis parameters and values that were in effect when the Pause All Tracking Button is clicked. All parameters (such as axis min and span) are restored when the Resume All Tracking Button is clicked and this property is set to TRUE. Master UI Input: Use MasterUIInput to set this axis to be the Master User Interface for all axes of this type.

For example, let’s say you have three (3) Y-Axes. If you set this property to TRUE on the first Y-Axis, then all UI (User Input, such as mouse or keyboard input) on that axis will be applied to all other Y-Axes. The X-Axes will not be affected as they are not Y-Axes (i.e. they are not the same type).

This is useful if you want the scrolling action of one axis to be synchronized with all other axes of the same type. If you want all Axes of the same type to be synchronized, set this property to TRUE on all of them. If you want all Axes to be independent, set this property to FALSE on all of them.

Axes Title FIGURE A.25

Axes Title Show: Use TitleShow to specify whether the axis title is shown. Axes Title Text: Use Title to get or set the title text for the axis. To hide the title, use the TitleShow property. Axes Title Margin: Use TitleMargin to get or set margin between the axis title and axis scale labels. TitleMargin represents the percentage of a character size and is based on the TitleFont used for the axis. A value of 0.5 is equal to half the size of a character. Axes Title Font: The Font for the Title.

Iocomp Components – Plot Pack Manual 231 Appendix A - Plot Pack Property Editors

Axes Labels FIGURE A.26

Min Length: Use LabelsMinLength to get or set the minimum label length used in calculating the number of scale labels (Major Ticks) during AutoScale. This property has no effect if the axis is not horizontal.

AutoScale automatically calculates the number of scale labels based on the LabelsFont, LabelSeparation, and LabelsMinLength to ensure labels that are in a human readable format (1- 2-5 Rule). Precision: Use LabelsPrecision to get or set the precision of the axis labels. The actual number of digits shown to the right of the decimal place depends on the setting of the LabelsPrecisionStyle property.

For example, if LabelsPrecision is 1, LabelsPrecisionStyle is set to ipsFixedDecimalPoints, and the value is 40.56 then the label text will be formatted to display “40.6”. To show integers only, set LabelsPrecision to 0. Margin: Use LabelsMargin to get or set the spacing between the major tick and major tick labels. LabelsMargin represents the percentage of a character size and is based on the LabelsFont used for the axis. A value of 0.5 is equal to half the size of a character. Label Separation: Use LabelSeparation to get or set the minimum separation between scale labels. LabelSeparation represents the percentage of a character size and is based on the LabelsFont used for the axis. A value of 0.5 is equal to half the size of a character. The actual separation maybe greater due to the AutoScale reducing the number of major ticks to keep the scale labels in a human readable format (1-2-5 Rule).

232 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Min Length Auto Adjust: Use LabelsMinLengthAutoAdjust to specify whether the LabelsMinLength property is automatically adjusted as the minimum required label length increases.

The LabelsMinLength property is stored when the TrackingEnabled property is set to False. The LabelsMinLength property will be restored to the previous value when TrackingEnabled property is set back to True. Precision Style: Use PrecisionStyle to specify how the LabelsPrecision property is interpreted when formatting scale labels. When PrecisionStyle is set to ipsSignificantDigits, the number of digits to the right of the decimal point is automatically calculated to ensure that the span of the values will show enough significant digits.

For Example :

LabelsPrecision = 3 LabelsPrecisionStyle = ipsSignificantDigits Span = 50

Number of digits shown to the right of the decimal point = 1 Value Meaning Precision property specifies the number of significant ipsSignificantDigits digits Precision property specifies the number of digits to the ipsFixedDecimalPoints right of the decimal point Format Style: Use LabelsFormatStyle to get or set the formatting style of scale labels. Value Meaning iptfValue Simple Value (ex. 198678.567) iptfExponent Exponential (ex. 2.35E+002) iptfPrefix Prefix (ex. 2.2K) iptfDateTime Date/Time (ex. 3 Jan 01 5:23:44) ex. 100.231This format is used in the Bond and Securities Market. Displayed where 23 is in 32nds and 1 is in 256ths. So in decimal the price above is: 100 iptfPrice32nds +23/32 + 1/256. Pass the actual double value of 100.72265625 to display it as Price32nds format as 100.231. Date Time Format: Use DateTimeFormat to get or set the Date/Time formatting string for the labels. See FormatDateTime for specific values.

Iocomp Components – Plot Pack Manual 233 Appendix A - Plot Pack Property Editors

Axes Tracking FIGURE A.27

Enabled: Use TrackingEnabled to specify whether the axis will adjust itself to new tracking data from the channels. Depending on the TrackingStyle, When the TrackingEnabled property is set to True, the axis will scroll or compress based on the new tracking data. Style: Use TrackingStyle to specify how the axis adjusts itself in response to new tracking data if off scale. Value Meaning Will adjust the Min or Span property to keep the new iptsScaleMinMax tracking data in view Will adjust the Max property if necessary to keep the iptsScaleMax new tracking data in view Will adjust the Min property if necessary to keep the iptsScaleMin new tracking data in view If the data is off axis, the scale will be adjusted to show iptsScrollSmooth the data at the end of the scale If the data is off axis, the scale will be adjusted to show iptsScrollPage the data at the beginning of the scale Align First Style: Use TrackingAlignFirstStyle to specify how the axis aligns itself when it receives it first piece of tracking data. If there is more than one channel sending tracking data, only the data from the first channel is used to set the first alignment. To force the axis to realign to the next piece of tracking data, call the ResetFirstAlign method. Value Meaning Axis is adjusted to show first data point on the ipafsMin beginning of the scale Axis is adjusted to show first data point on the end of ipafsMax the scale

234 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Value Meaning Axis is unchanged if first data point is in view. If out of ipafsAuto view then the axis is adjusted to show first data point on the beginning of the scale ipafsNone Axis is not adjusted on the first data point Scroll Compress Max: Use TrackingScrollCompressMax to get or set the maximum span value when compressing the scale. When new tracking data is received and the TrackingEnabled is set to True, the Span property will be increased (Compressed) to include the tracking data if the current Span property is less than the TrackingScrollCompressMax. To disable this feature, set TrackingScrollCompressMax to 0.

Axes Cursor FIGURE A.28

Cursor Precision: Use CursorPrecision to get or set the precision of the cursor ToolTips. The actual number of digits shown to the right of the decimal place depends on the setting of the LabelsPrecisionStyle property. For example, if CursorPrecision is 1, LabelsPrecisionStyle is set to ipsFixedDecimalPoints, and the value at the current cursor position is 40.56 then the cursor ToolTip text will be formatted to display “40.6” (actual display of one data point, two data points, or a calculated value depends on the cursor’s property settings). To show integers only, set LabelsPrecision to 0. Note: this is a property of the Axis and not of the cursor object since the scale will be determining the precision of the data displayed in the cursor if the cursor is setup to use this axis for obtaining scale data. To modify properties of the cursor object or to associate a cursor with this axis object, refer to iPlotDataCursorX.

Iocomp Components – Plot Pack Manual 235 Appendix A - Plot Pack Property Editors

Cursor Scalar: Use CursorScaler to get or set the desired scalar for the cursor associated with this axis scale. CursorScaler is only used with cursors that have their Style property set to InverseDeltaX, typically used for frequency calculations. The Scalar is a multiplier used to convert this axis’ units to seconds format so that the cursor can property display the frequency calculation. For example, if the axis units are ms (milliseconds or 1/1,000th of a second), then you would need to set the Scalar to 1,000 to convert from ms to seconds. If the units are µs (microseconds or 1/1,000,000th of a second), then the Scalar should be set to 1,000,000 to convert from µs to seconds. If your units are already in seconds on this axis, then you would set the Scalar to 1.

Axes Scroll FIGURE A.29

Min/Max Enabled: Use ScrollMinMaxEnabled to specify whether scrolling of the axis is fixed to a range of values specified by ScrollMax and ScrollMin. If this property is set to True, then the axis will stop scrolling when ScrollMax and/or ScrollMin are reached on the scale. Min: Use ScrollMin to set a fixed maximum limit on scrolling of the axis. If the user attempts to scroll the axis past this point on the axis and ScrollMinMaxEnabled is set to True, the axis will not scroll past the specified maximum point. Max: Use ScrollMax to set a fixed maximum limit on scrolling of the axis. If the user attempts to scroll the axis past this point on the axis and ScrollMinMaxEnabled is set to True, the axis will not scroll past the specified maximum point.

236 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Axes Scale FIGURE A.30

Major Length: Use MajorLength to get or set the axis major ticks length. Minor Length: Use MinorLength to get or set the axis minor ticks length. Minor Count: Use MinorCount to get or set the number of axis minor ticks shown. MinorCount should be set to one less than the desires number of minor sections. For example, if you want 5 minor sections, set MinorCount to 4. Scale Lines Color: The color of the lines used to draw the scale. Inner Margin: Use InnerMargin to get or set the margin between the axis line and the side towards the data view. The InnerMargin value is in pixels. Outer Margin: Use OuterMargin to get or set margin between the axis labels or the axis title if shown and the side away form the data view. The OuterMargin value is in pixels. Stacking Ends Margin: Use StackingEndsMargin to get or set the margin at the end of the axis when stacked. StackingEndsMargin represents the percentage of a character size and is based on the LabelFont used for the axis. A value of 0.5 is equal to half the size of a character. Start Percent: Use StartPercent to get or set the starting position within the plot layout drawing area where the layout object is drawn. The reference for 0% is the bottom or left of the data view and depends on the orientation of the layout object. The reference for 100% is the top or right of the data view and depends on the orientation of the layout object. Currently, only the axes support the StartPercent and StopPercent properties. The legend, and toolbar ignore the StartPercent and StopPercent properties. Stop Percent: Use StopPercent to get or set the stopping position within the plot layout drawing area where the layout object is drawn. The reference for 0% is the bottom or left of the data view and depends on the orientation of the layout object. The reference for 100% is the top or right of the data view and depends on the orientation of the layout object. Currently, only the axes support the StartPercent and StopPercent properties. The legend, and toolbar ignore the StartPercent and StopPercent properties.

Iocomp Components – Plot Pack Manual 237 Appendix A - Plot Pack Property Editors

Axes Cartesian FIGURE A.31

Style: Use MajorLength to get or set the axis major ticks length. Value Meaning This style formats the axis as a non-Cartesian style axis that is placed along the edge of the DataView. This is ipcsNone the default setting and represents the original axis style of the Plot Components. This style formats the axis as a master Cartesian axis. There must be one axis that has the ipcsMaster style ipcsMaster set. A master Cartesian axis is centered along perpendicular sides of the DataView. This style formats the axis as a child Cartesian axis. A child Cartesian axis is positioned perpendicular to the opposite axis type specified by the ipcsChild CartesianChildRefAxisName property, and the position is specified by the CartesianChildRefValue property of the child Cartesian axis. Child Ref Axis Name: Use CartesianChildRefAxisName to get or set the name of the Axis used for referencing the axis. The specified Axis Name refers to the perpendicular axis scale that will be used to position this Child Cartesian Axis when using the CartesianChildRefValue property. This property only affects Axes that have their CartesianStyle set to ipcsChild.. Child Ref Value: Use CartesianChildRefValue to get or set the position of a Child Cartesian Axis along it's perpendicular reference axis specified by the CartesianChildRefAxisName property. This property only affects Axes that have their CartesianStyle set to ipcsChild.

238 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Legend FIGURE A.32

Visible: Use the Visible property to show or hide a specific Plot Object. Enabled: Use the Enabled property to enable or disable the UI (User Interface) of a Plot Object. When this property is set to TRUE, then the UI functionality (ability to move a scale, scroll a list, click on buttons, etc) of the Plot Object is enabled. Note that setting this property to TRUE will not override other properties that affect the UI of this Plot Object. When this property is set to FALSE, then the UI functionality of the Plot Object is disabled. Note that this will override all other properties that affect the UI of this Plot Object. Note: when a Plot Object is disabled, the Plot Object will not “look disabled” like standard textboxes or labels. Only the UI will be disabled. Popup Enabled: Use the PopupEnabled property to enable or disable the Popup Menu of a Plot Object. The Popup Menu is shown when a user right-clicks on this Plot Object. Setting this property to FALSE is useful if you don’t want the Popup Menu functionality of this Plot Object in your particular application. Note: when the Enabled property is set to FALSE, then this property will have no effect and the Popup will be disabled. Column Spacing: Use ColumnSpacing to get or set the spacing between columns in the legend. ColumnSpacing represents the percentage of a character size and is based on the Font used in the Legend. A value of 0.5 is equal to half the width of a character. Channel Name Max Width: Use ChannelNameMaxWidth to specify the maximum channel name width allowed in the Legend before word wrapping occurs. This property allows you to set a maximum width of the Channel Name column, allowing those channel names that exceed this width to word-wrap to the next line.. Row Spacing: Use RowSpacing to get or set the spacing between rows in the legend. RowSpacing represents the percentage of a character size and is based on the Font used in the Legend. A value of 0.5 is equal to half the height of a character. Font: The font used in the Legend. Margin: Use OuterMarginLeft, OuterMarginRight, OuterMarginTop, or OuterMarginBottom to set the margin between the left, right, top, or bottom side edge of the control and the internal drawn elements. The values are specified in pixels.

Iocomp Components – Plot Pack Manual 239 Appendix A - Plot Pack Property Editors

Column Titles Visible: Use ColumnTitlesVisible to specify whether the column titles are visible in the legend. Column Titles Font: Use ColumnTitlesFont to change the attributes of the column titles font. To change to a new font, specify a new IFontDisp object. Background Transparent: Use the BackGroundTransparent property to specify whether the background behind the legend shows through. Background Color: Use BackGroundColor to get or set the background color of the legend. Selected Item Background Color: Use SelectedItemBackGroundColor to get or set the background color of selected items in the legend. Selected Item Font: The font of the selected item. Show Column Line: Use ShowColumnLine to specify whether the line column is shown in the legend. Show Column Marker: Use ShowColumnMarker to specify whether the marker column is shown in the legend. Show Column X-Axis Title: Use ShowColumnXAxisTitle to specify whether the X-Axis title column is shown in the legend. Show Column Y-Axis Title: Use ShowColumnYAxisTitle to specify whether the Y-Axis title column is shown in the legend. Show Column X-Value: Use ShowColumnXValue to specify whether the x value column is shown in the legend. The value displayed is the last x value added to the channel. The formatting of the text is control by the formatting of the X-Axis that the channel is using. Show Column Y-Value: Use ShowColumnYValue to specify whether the y value column is shown in the legend. The value displayed is the last y value added to the channel. The formatting of the text is control by the formatting of the Y-Axis that the channel is using. Show Column Y-Max: Use ShowColumnYMax to specify whether the Y-Maximum Value for each channel is shown in the legend. Show Column Y-Min: Use ShowColumnYMin to specify whether the Y Minimum Value for each channel is shown in the legend. Show Column Y-Mean: Use ShowColumnYMean to specify whether the Y Mean Value for each channel is shown in the legend.

240 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

ToolBar FIGURE A.33

Visible: Show or hide entire toolbar. Enabled: Use the Enabled property to enable or disable the UI (User Interface) of a Plot Object.

When this property is set to FALSE, then the UI functionality of the Plot Object is disabled. Note that this will override all other properties that affect the UI of this Plot Object.

Setting this property to FALSE is useful if you don’t want the Popup Menu functionality of this Plot Object in your particular application.

Note: when the Enabled property is set to FALSE, then this property will have no effect and the Popup will be disabled.

Iocomp Components – Plot Pack Manual 241 Appendix A - Plot Pack Property Editors

Zoom In/Out Factor: Use ZoomInOutFactor to get or set the Toolbar Zoom button zoom factor. When your application user clicks on either the Zoom In or Zoom Out buttons, or you use the toolbar methods DoButtonClickZoomIn or DoButtonClickZoomOut, the chart axes will be zoomed according to this factor.

When the ScaleType is set to Linear...

To zoom in our out by 100% set the value to 2 To zoom in our out by 50% set the value to 1.5 A setting of 1 will have no effect, and the zoom in and out capability will be disabled. (Zoom Value must always be greater or equal to 1)

When the ScaleType is set to Logarithmic...

This property has no effect. Log based scales always zoom in our out by 100%, or by a factor of 2 . Show: Determines whether a button is shown on the toolbar or not. Button Meaning Resume Button: Resumes tracking on ALL axes Pause Button: Pauses tracking for ALL axes Axes Mode Buttons: Changes the mode that the axes are in when using the mouse. The first icon puts the axes in scroll

mode. The second icon puts the axes in zoom mode. Zoom In/Out Buttons: Zooms ALL axes in our out.

Select Button: Used for selecting items in the data view area. Generates events that can be used by the programmer to react to selection of items such as data points, annotations, areas of the data view, etc. Zoom Box Button: Allows the user to draw a "Zoom Box" on the DataView area to zoom ALL axes. Cursor Button: Show or hide all data cursors. Values for each channel are displayed in a hint window next to the cursor(s). Edit Button: Brings up the Run-Time property editor for the user to change most control properties. Copy Button: Copies the current component image to the Windows' clipboard. Save Button: Brings up a dialog to allow the user to save chart data to currently supported file types. Print Button: Allows user to print image of chart to printer. See Print properties for more information.

242 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Data View General FIGURE A.34

Enabled: Use the Enabled property to enable or disable the UI (User Interface) of a Plot Object.

When this property is set to FALSE, then the UI functionality of the Plot Object is disabled. Note that this will override all other properties that affect the UI of this Plot Object.

Setting this property to FALSE is useful if you don’t want the Popup Menu functionality of this Plot Object in your particular application.

Note: when the Enabled property is set to FALSE, then this property will have no effect and the Popup will be disabled. Background Transparent: Use BackGroundTransparent to specify whether the background behind the data view shows through. Background Color: Use BackGroundColor to get or set the background color of the data view. Grid Show: Use GridXAxisName to get or the name of the X-Axis used for displaying X-Axis major and minor lines in the grid. Use GridLineShowXMajors and GridLineShowXMinors to specify which ticks are used to draw grid lines. Stacked Axes Note: If you are using stacked axes, you will probably want to set this property to “”. This string value will instruct the grid to draw to the major tick lines for each individual X-Axis.

Iocomp Components – Plot Pack Manual 243 Appendix A - Plot Pack Property Editors

Grid X-Axis Name: Use GridXAxisName to get or the name of the X-Axis used for displaying X-Axis major and minor lines in the grid. Use GridLineShowXMajors and GridLineShowXMinors to specify which ticks are used to draw grid lines.

If you are using stacked axes, it is recommended that you use an additional invisible axis to ensure that the grid lines extend over the entire Plot Data View area. If not, then the grid lines will only be drawn to the X-Axis specified, and will not be drawn to areas where the X-Axis has been restricted by the StartPercent and StopPercent properties of that Axis. Grid Y-Axis Name: Use GridXAxisName to get or the name of the Y-Axis used for displaying Y-Axis major and minor lines in the grid. Use GridLineShowYMajors and GridLineShowYMinors to specify which ticks are used to draw grid lines. Stacked Axes Note: If you are using stacked axes, you will probably want to set this property to “”. This string value will instruct the grid to draw to the major tick lines for each individual X-Axis. Line Color: Use GridLineColor to get or set the color of the grid lines drawn in the data view.

Data View Grid Lines FIGURE A.35

Color: Use to specify the overall/default color of the grid lines. You can override specific X-Axis and Y-Axis Major and Minor tick line settings using properties on the X-Majors, X-Minors, Y- Majors, and Y-Minors Tabs. Major Style: Use the GridLineMajorStyle property to get or set the line style of grid lines drawn from major ticks (major ticks from axes specified by the GridXAxisName and GridYAxisName properties). You can override specific X-Axis and Y-Axis Major and Minor tick line settings using properties on the X-Majors, X-Minors, Y-Majors, and Y-Minors Tabs. Value Meaning ipglsSolid A solid line ipglsDash A line made up of a series of dashes ipglsDot A line made up of a series of dots

244 Iocomp Components – Plot Pack Manual Appendix A - Plot Pack Property Editors

Value Meaning ipglsDot A line made up of a series of dots Minor Style: Use the GridLineMinorStyle property to get or set the line style of grid lines drawn from minor ticks (minor ticks from axes specified by the GridXAxisName and GridYAxisName properties). You can override specific X-Axis and Y-Axis Major and Minor tick line settings using properties on the X-Majors, X-Minors, Y-Majors, and Y-Minors Tabs. Value Meaning ipglsSolid A solid line ipglsDash A line made up of a series of dashes ipglsDot A line made up of a series of dots ipglsDot A line made up of a series of dots Show Left: Specifies whether the left border grid line is shown. Show Right: Specifies whether the right border grid line is shown. Show Top: Specifies whether the top border grid line is shown. Show Bottom: Specifies whether the bottom border grid line is shown. X-Majors, X-Minors, Y-Majors, Y-Minors Show: Use to specify whether grid lines for this specific axis tick type are shown. X-Majors, X-Minors, Y-Majors, Y-Minors Custom: Use to specify whether the below “Custom Properties” override the overall grid settings specified previously for this Axis tick type. X-Majors, X-Minors, Y-Majors, Y-Minors Custom Color: Use to specify the grid line color for this Axis tick type. X-Majors, X-Minors, Y-Majors, Y-Minors Custom Width: Use to specify the grid line width for this Axis tick type. X-Majors, X-Minors, Y-Majors, Y-Minors Custom Style: Use to specify the grid line style for this Axis tick type.

Iocomp Components – Plot Pack Manual 245 Appendix B - Getting Started with Microsoft Visual Basic 6.0

Appendix B - Getting Started with Microsoft Visual Basic 6.0

Introduction The easiest way to get started using ActiveX components in a Visual Basic project is to simply drop-down a component and open the property editor. In this section, we will cover creating a simple project, dropping down an Iocomp ActiveX component, and modifying the component’s properties using the built-in property editor. We will also cover creating an event handler and writing some Visual Basic code to modify the component.

Adding Component to Project Each Visual Basic project needs to be configured with a set of component that will be available to it. To add our components to the list of available components in your component pallet, right- click on the component pallet and select “Components…”…

FIGURE B.1 To make an ActiveX component available for use with your application, right-click on your component pallet and select “Components…”.

The list of components presented represents the available ActiveX components on your computer system. Scroll down the list and place a check mark next to “Iocomp Plot Pack”… FIGURE B.2 View of the available ActiveX components on your computer system. Select “Iocomp Plot Pack” to make our Plot Components available to your application. The components will then show up in the Visual Basic component pallet.

246 Iocomp Components – Plot Pack Manual Appendix B - Getting Started with Microsoft Visual Basic 6.0

Adding Component To Form To add a component to a Visual Basic form, simply click once on the iPlotX icon (shown depressed in Figure B.3), … FIGURE B.3 To add a component to the form, click on the component icon in the Visual Basic component pallet.

…then click and drag out the component on your form to the size you desire… FIGURE B.4 Click and drag out the component to the desired size.

FIGURE B.5 View of an iPlotX component on a Visual Basic form. The component is named “iPlotX1” as show in the Visual Basic property editor.

Iocomp Components – Plot Pack Manual 247 Appendix B - Getting Started with Microsoft Visual Basic 6.0

Custom Property Editor You can use the Visual Basic-provided propery editor, shown in figure B.6 in the lower-right- hand corner, to change some properties of the component at design-time. However, we recommend that you use our own Custom Property Editor, which provides access to the component that the Visual Basic property editor cannot provide.

To open our custom property editor, simply right-click on the component and select “Properties”… FIGURE B.6 To open the Plot Component’s Custom Propety Editor, right- click on the component and select “Properties”.

The custom property editor is organized into different tabs, representing the layout and structure of the Plot Pack components.

FIGURE B.7 View of the General Component Property Editor Tab.

For example, the Channel tab allows you to add and remove channels from the component at Design-Time, something that the Visual Basic property editor cannot do.

248 Iocomp Components – Plot Pack Manual Appendix B - Getting Started with Microsoft Visual Basic 6.0

FIGURE B.8 View of the Channel Property Editor Tab.

Accessing Component Through Code The custom property editor allows you to make changes to the component while designing your application. However, you will probably need to make changes to the component or to modify aspects of the component at run-time as well in your Visual Basic code.

Setting Properties and Calling Methods To access any component placed on a form, you will need to know the name of the component you need to access. By default, the first iPlotX component is named “iPlotX1”, but you can name the component anything you wish, such as “GraphXYZ”. You will use the name of the component to access properties and methods of the component as follows…

iPlotX1.Property iPlotX1.Method

iPlotX1.PrintMarginTop = 10 iPlotX1.AddChannel

…as well as access sub-objects of the components…

iPlotX1.Channel(0).Color = vbRed iPlotX1.XAxis(0).Min = -50 iPlotX1.YAxis(0).Span = 100

Events Like all modern Windows development environments, Visual Basic applications are “Event Driven”. This means that your program executes according to events, usually generated by user clicks of the mouse or keyboard buttons.

Iocomp Components – Plot Pack Manual 249 Appendix B - Getting Started with Microsoft Visual Basic 6.0

FIGURE B.9 View of the Visual Basic code window and the Form Load event. Some initialization of the iPlotX1 component is accomplished here after the form loads, but before it is shown to your user.

Small snippets of code, known as Event Handlers, are written to handle situations such as a click of a button, or when a user selects a particular menu item in your application. These event handlers only “fire” or execute when the associated event occurs, such as an “OnClick” event running in response to a mouse click on a component.

The Plot Pack components, as well as the Visual Basic form that they reside on, have a list of events that are available to allow you to respond to events either generated by the user doing something with the component, or to respond to events generated by the component itself. These events include OnXAxisMinChange (this event fires when the minimum displayed value of the X-axis changes, usually due to the user scrolling the X-Axis), or OnBeforePrint (this event fires just before a chart is sent to the printer using our own built-in printing routines, usually due to the user clicking on the Print toolbar button or due to your code calling the PrintChart method), and so on.

To create an event handler for a particular event in the Plot Component, navigate to the Visual Basic code window. There are two combo boxes at the top of the window. The left-hand side has a list of all components (including the form) that are on this form. Select the Iocomp Plot Pack component you are working with (by default named iPlotX1). Next, select an available event from the combo box on the right. The list of events will vary depending on the component.

Figure B.9 shows the Load event for the form (shown as Form_Load). This event fires when the form is initially created, so we do some initial setup of the iPlot component on the form before it is shown to the user.

Some events will pass you information to tell you some additional information other than just that the event was fired. For example, the OnClickDataPoint event tells you that a data point was clicked, but how do you know which data point was clicked? This event passes you two pieces of information, ChannelIndex and DataIndex to tell you which channel was clicked and the index of the data point that was clicked.

250 Iocomp Components – Plot Pack Manual Appendix B - Getting Started with Microsoft Visual Basic 6.0

FIGURE B.10 View of the Visual Basic code window and the Plot Pack OnClickDataPoint event. Notice that the event handler passes you the channel index and the index of the data point that was clicked.

Example OnClickDataPoint code as shown in Figure B.10 Private Sub iPlotX1_OnClickDataPoint(ByVal ChannelIndex As Long, ByVal DataIndex As Long) MsgBox "You clicked Channel#" & ChannelIndex & " and data point at coordinates x:" & iPlotX1.Channel(0).DataX(DataIndex) & ", y:" & iPlotX1.Channel(0).DataY(DataIndex) End Sub

Iocomp Components – Plot Pack Manual 251 Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Introduction The easiest way to get started using ActiveX components in a Visual C++ project is to simply drop-down a component and open the property editor. In this section, we will cover creating a simple MFC dialog-based project, dropping down an Iocomp ActiveX component, and modifying the component’s properties using the built-in property editor. We will also cover creating an event handler using the Visual C++ Class Wizard and writing some Visual C++ code to modify the component using the Disp interface.

You can use both the Disp (late-binding, slow speed) and iDispatch(early-binding, high speed) interface if you wish. You would use the Disp interface where required, and use the iDispatch interface where you want to utilize the high speed interface in loops, for example.

Adding Component To Project Each Visual C++ project needs to be configured with a set of component that will be available to it. In this example, we are working with a MFC Dialog-based application. To add our components to the list of available components in your component pallet, open the “Project” menu, select “Add to Project”, and then finally select “Components and Controls…”…

FIGURE C.1 To add an ActiveX component to your project, click on the “Project”, select “Add To Project”, and then open the “Components and Controls…” menu.

252 Iocomp Components – Plot Pack Manual Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Open the folder “Registered ActiveX Controls”…

FIGURE C.2 Select “Registered ActiveX Controls” to view a list of ActiveX controls on your computer system.

…and then look through the list for “iPlotX Control” and press “Insert”.

FIGURE C.3 Select each individual ActiveX component you wish to add to your project.

Select OK to insert the component into your project, and have Visual C++ automatically generate classes (aka ActiveX wrapper files)…

FIGURE C.4 Click OK to confirm.

Iocomp Components – Plot Pack Manual 253 Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Click OK to confirm the generation of the ActiveX wrapper file classes, leaving all defaults checked…

FIGURE C.5 You can generally accept the default class generation. Click OK to complete the importation process.

Click ‘Close” to close the dialog.

FIGURE C.6 Click Close to close the dialog.

254 Iocomp Components – Plot Pack Manual Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Adding Component To Form Notice that the iPlotX icon now shows in your component pallet toolbox. To add our iPlot component to your form, select the icon button in the toolbox…

FIGURE C.7 To add a component to the form, click on the component icon in the Visual C++ component pallet.

Iocomp Components – Plot Pack Manual 255 Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

…and then click and drag the component onto the form to the size you desire.

FIGURE C.8 Click and drag out the component to the desired size.

256 Iocomp Components – Plot Pack Manual Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Notice the second combo box, this is the IDC name of the component, by default “IDC_IPLOTX1”. You will generally not use this name in your code, but will use the Visual C++ Class wizard to generate a member variable so that you can access the control through code.

FIGURE C.9 View of an iPlotX component on a Visual C++ MFC form. The component’s IDC name is “IDC_IPLOTX1” as show in the combo boxes above.

Iocomp Components – Plot Pack Manual 257 Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Custom Property Editor All of our ActiveX components include our own Custom Property Editor, which provides access to the component that the Visual C++ property editor list cannot provide.

To open our custom property editor, simply right-click on the component and select “Properties iPlotX Control Object”.

FIGURE C.10 To open the Plot Component’s Custom Propety Editor, right-click on the component and select “Properties iPlotX Control Object”.

The custom property editor is organized into different tabs, representing the layout and structure of the Plot Pack components. Notice the top row of tabs. Our Custom Property editor pages are all located under the tab entitled “Control”, and the “About” tab is provided by us to detail the version number of the ActiveX control and other Iocomp specific information.

The “General” and “All” tabs belong to and are provided by Visual C++ itself.

258 Iocomp Components – Plot Pack Manual Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

FIGURE C.11 View of the General Component Property Editor Tab.

For example, the Channel tab allows you to add and remove channels from the component at Design-Time, something that the Visual C++ “All” tab list of properties cannot accomplish. FIGURE C.12 View of the Channel Property Editor Tab.

Accessing Component Through Code When you first add a control to a form in a MFC Visual C++ project, the control is assigned a Control ID, by default “IDC_IPLOTX1”. However, in Visual C++, you need to do an additional step to be able to access the control in your C++ code when using the DispRemember that you can mix the Disp(late-binding, slow interface) and iDispatch(early-binding, high-speed interface) interfaces if you wish. This appendix will cover using just the Disp interface. Refer to the next appendix for information on using the iDispatch interface.

Adding Member Variable To access the ActiveX component on the form, you need to create what is called a Member Variable”. To do this, right-click anywhere on your form or your C++ code window, and select “Class Wizard”. Then select the “Member Variables” tab and click the “Add Variable…” button…

Iocomp Components – Plot Pack Manual 259 Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

FIGURE C.13 To add a member variable, open the MFC ClassWizard, navigate to the “Member Variables” tab, select the Control ID of the Plot Component, and then click the “Add Variable” button.

Next, make up a variable name for this component. It must be a unique name, and this name will be used in your C++ source code when accessing the component when using the DISP (late binding, slow speed) interface. Member variables generally start with “m_”, then the class name of the component “iPlotX”, and then a number with the first component getting “1”, or finally “m_iPlotX1”.

FIGURE C.14 Specify a member variable name for this component. This name will be used in your Visual C++ code to access the component. By convention, member variable names generally begin with “m_”.

Setting Properties and Calling Methods When using member variables to access ActiveX components, Visual C++ does not understand the concept of properties. All ‘properties” in the component are actually accessed through “Get” and “Set” methods. For example, to set the BackgroundColor property, you would call the SetBackGroundColor method on the component as follows…

m_iComponentX1.SetBackGroundColor(0x000000FF); //Red

…or if you want to access a method on a Plot Component sub-object, you would do the following, on the channel for example…

m_iComponentX1.GetChannel(0).SetColor(0x000000FF); //Red

…of if you simply want to call a regular method, to add a data point for example…

m_iComponentX1.GetChannel(0).AddXY(10, 25.6); //Add a Data Point

260 Iocomp Components – Plot Pack Manual Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Fonts: Using the Disp (Late Binding, Slow-Speed, Member Variable) Interface All of our components that have font properties that make it easy to deal with fonts in our components when developing under Microsoft Visual C++. To set the Font's Color property, there is a special, single property to do this...

m_iComponentX1.SetFontColor(0x0000FFFF); //Yellow Font Color

To set other Font Properties, do the following...

//Add this include statement to the top of your file #include "font.h";

...and then do the following...

//Setup Local Variables in your code COleFont MyFont; CY FontSize;

//Get a copy of the font from the component MyFont = m_iComponentX1.GetFont();

//Set the Font Size FontSize.int64 = 240000; //Point Size 24 (24 * 10000 = 240000) MyFont.SetSize(FontSize);

//Set the Font Name MyFont.SetName("Times New Roman");

//Set Various Font Styles MyFont.SetBold(TRUE); MyFont.SetItalic(FALSE); MyFont.SetUnderline(FALSE); MyFont.SetStrikeThrough(FALSE);

//Set the font back on the component m_iComponentX1.SetFont(MyFont);

Event Handlers Like all modern Windows development environments, Visual C++ applications are “Event Driven”. This means that your program executes according to events, usually generated by user clicks of the mouse or keyboard buttons.

The Plot Pack components, as well as the Visual C++ MFC form that they reside on, have a list of events that are available to allow you to respond to events either generated by the user doing something with the component, or to respond to events generated by the component itself. These events include OnXAxisMinChange (this event fires when the minimum displayed value of the X-axis changes, usually due to the user scrolling the X-

Iocomp Components – Plot Pack Manual 261 Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

Axis), or OnBeforePrint (this event fires just before a chart is sent to the printer using our own built-in printing routines, usually due to the user clicking on the Print toolbar button or due to your code calling the PrintChart method), and so on.

To create an event handler for a particular event in the Plot Component, you will need to use the MFC ClassWizard to map Object Messages to Member Functions in your code. Whenever a particular message for an event will be routed to the specified Member Function.

Openthe MFC Classwizard by right-clicking anywhere on your form or in your Visual C++ code window and selecting “ClassWizard…”. In the “Message Maps” tab, select the Object ID for the Plot Component from the list of “Object IDs”. In the listbox to the right, select the event you wish to map. This example shows maping the OnLimitLine1PositionChange event… FIGURE C.15 To map an event message to a member function (aka Event Handler), select the Object ID, then select the Message to map, then click the “Add Function…” button.

You are then asked to name the Member Function that will be executed whenever this event is fired. The name that Visual C++ picks is generally messy, so you will probably want to rename it to something understandable…. FIGURE C.16 Specify a name for the Event Handler member function. Pick any unique name. The new Event Handler will be displayed in the “Member Functions” listbox. To view the member function so that you can add code to the event handler, double-click on the “OnLimitLine1PositionChangeiPlotX1” entry.

262 Iocomp Components – Plot Pack Manual Appendix C - Getting Started with Microsoft Visual C++ 6.0 (Disp Interface)

FIGURE C.17 After adding the member function, it will be listed in the lower “Member functions” listbox. Double-click or select and click “Edit Code” to edit the Event Handler code.

FIGURE C.18 View of the Visual C++ code window and the Plot Pack OnLimitLine1Position Change event. Notice that the event handler passes you the Data Cursor index, the value of the line’s previous position, and the line’s new position value.

Iocomp Components – Plot Pack Manual 263 Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

Adding Component To Project When using the iDispatch interface, you do not need to add the Plot Pack ActiveX components to your project. Visual C++ will automatically import the TLB interface file each time you build your project, and will use this imported information along with a CCOM pointer to access the component.

Adding Component To Form To add a component to your form, you can either select the Iocomp Plot Pack component from the component pallet if you imported the ActiveX into your project (this was done if you plan on using the Disp interface in addition to iDispatch). Or, you can simply right-click on the form and select “Insert ActiveX Control…”, which will add the component to your form without importing the control… FIGURE D.1 To add an ActiveX component to your project, right-click on your form and select “Insert ActiveX Control”.

264 Iocomp Components – Plot Pack Manual Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

Next, scroll through the list of registered ActiveX components on your system and select “iPlotX Control”. FIGURE D.2 Select the “iPlotX Control” from the list of available ActiveX components registered on your computer system.

The component will automatically be placed on the form for you. You can then resize the component as you wish.

Notice the second combo box, this is the IDC name of the component, by default “IDC_IPLOTX1”. You will generally not use this name in your code, but will create a CCOM pointer variable in your project so that you can access the control through code. FIGURE D.3 The component will automatically be dropped into your form. You can manually resize the component as you desire.

Custom Property Editor All of our ActiveX components include our own Custom Property Editor, which provides access to the component that the Visual C++ property editor list cannot provide.

To open our custom property editor, simply right-click on the component and select “Properties iPlotX Control Object”.

Iocomp Components – Plot Pack Manual 265 Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

FIGURE D.4 To open the Plot Component’s Custom Propety Editor, right-click on the component and select “Properties iPlotX Control Object”.

The “General” and “All” tabs belong to and are provided by Visual C++ itself. FIGURE D.5 View of the General Component Property Editor Tab.

For example, the Channel tab allows you to add and remove channels from the component at Design-Time, something that the Visual C++ “All” tab list of properties cannot accomplish.

266 Iocomp Components – Plot Pack Manual Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

FIGURE D.6 View of the Channel Property Editor Tab.

Remember that you can mix the Disp(late-binding, slow interface) and iDispatch(early-binding, high-speed interface) interfaces if you wish. This appendix will cover using just the iDispatch interface. Refer to the previous appendix for information on using the Disp interface.

Adding CCOM Pointer Variable To access the ActiveX component on the form, you need to create what is called CCOM pointer to the control. To do this, add the following code to the top of your form’s cpp file…

#import "iPlotLibrary.tlb" named_guids #include "atlbase.h" extern CComModule _Module;

Next, you will need to configure your project to point to the location of our ActiveX OCX and TLB files. Open the “Tools” and “Options…” menu. Select the “Directories” tab and add the directory where our ActiveX files are stored, usually in your system directory.

The TLB file is only needed during development and compilation. You do not need to distribute it with your application. Only the iPlotLibrary.ocx file needs to be distributed with your application, along with other files required by your Visual C++ ! application.

Iocomp Components – Plot Pack Manual 267 Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

Next, you will need to decide the scope of the CCOM variable. Are you simply going to be using the CCOM variable in a single procedure, or are you going to be accessing the CCOM variable from all over your application. If you need a global CCOM variable pointer, define the CCOM variable in your dialog’s header file. If you just need a temprary CCOM varaible in a procedure, define it there instead…

CComPtr iComponentX1;

Next, we need to assign the CCOM pointer variable to the component on the form. In this example, the IDC name of the component is “IDC_IPLOTX1”. You will need to look at the property page of the actual component to determine the name to use here.

CWnd* m_Wnd; IUnknown* m_iUnknown;

//Get interface to Plot Component m_Wnd = GetDlgItem(IDC_IPLOTX1); m_iUnknown = m_Wnd->GetControlUnknown(); m_iUnknown->QueryInterface (__uuidof(iPlotLibrary::IiPlotX), (LPVOID*)&iComponentX1);

It is also sometimes helpful to just get a CCOM pointer to a channel or other Plot Component sub-object instead of the entire Plot Component. To get a CCOMpointer to the channel, do the following…

CComPtr tempChannel;

//Get interface to Channel tempChannel = iComponentX1->Channel[0];

Setting Properties and Calling Methods When using a CCOM pointer to access ActiveX components, Visual C++ understands the concept of properties with some parts of ActiveX component. This differs from the Disp interface where all ‘properties” in the component are accessed through “Get” and “Set” methods. Some properties, such as For example, to set the BackgroundColor property, you would call the Put_BackGroundColor as follows…

iComponentX1->PutBackGroundColor(0x000000FF); //Red

…or if you want to access a method on a Plot Component sub-object, you would do the following, on the channel for example…

iComponentX1->Channel[0].SetColor(0x000000FF); //Red

…If you need to set an enumerated property, such as the channel Interpolation Style, you will need to refer to the Iocomp ActiveX help file on this property and enter the style as follows…

iComponentX1->Channel[0]->InterpolationStyle = iPlotLibrary::ipistDifferential;

268 Iocomp Components – Plot Pack Manual Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

…of if you simply want to call a regular method, to add a data point for example…

m_iComponentX1->Channel[0]->AddXY(10, 25.6); //Add a Data Point

Fonts: Using the iDispatch (Early Binding, High-Speed) Interface All of our components that have font properties that make it easy to deal with fonts in our components when developing under Microsoft Visual C++. To set the Font's Color property, there is a special, single property to do this...

iComponentX1->SetFontColor(0x0000FFFF); //Yellow Font Color

To set other Font Properties, do the following...

//Add this include statement to the top of your file #include "font.h";

...and then do the following...

//Setup Local Variables in your code COleFont MyFont; CY FontSize;

//Get a copy of the font from the component MyFont = iComponentX1->GetFont();

//Set the Font Size FontSize.int64 = 240000; //Point Size 24 (24 * 10000 = 240000) MyFont.SetSize(FontSize);

//Set the Font Name MyFont.SetName("Times New Roman");

//Set Various Font Styles MyFont.SetBold(TRUE); MyFont.SetItalic(FALSE); MyFont.SetUnderline(FALSE); MyFont.SetStrikeThrough(FALSE);

//Set the font back on the component iComponentX1->PutFont((IFontDisp *)MyFont.m_lpDispatch);

The Plot Pack components, as well as the Visual C++ MFC form that they reside on, have a list of events that are available to allow you to respond to events either generated

Iocomp Components – Plot Pack Manual 269 Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

by the user doing something with the component, or to respond to events generated by the component itself. These events include OnXAxisMinChange (this event fires when the minimum displayed value of the X-axis changes, usually due to the user scrolling the X- Axis), or OnBeforePrint (this event fires just before a chart is sent to the printer using our own built-in printing routines, usually due to the user clicking on the Print toolbar button or due to your code calling the PrintChart method), and so on.

FIGURE D.7 To map an event message to a member function (aka Event Handler), select the Object ID, then select the Message to map, then click the “Add Function…” button.

FIGURE D.8 Specify a name for the Event Handler member function. Pick any unique name.

The new Event Handler will be displayed in the “Member Functions” listbox. To view the member function so that you can add code to the event handler, double-click on the “OnLimitLine1PositionChangeiPlotX1” entry.

270 Iocomp Components – Plot Pack Manual Appendix D - Getting Started with Microsoft Visual C++ 6.0 (iDispatch)

FIGURE D.9 After adding the member function, it will be listed in the lower “Member functions” listbox. Double-click or select and click “Edit Code” to edit the Event Handler code.

FIGURE D.10 View of the Visual C++ code window and the Plot Pack OnLimitLine1Position Change event. Notice that the event handler passes you the Data Cursor index, the value of the line’s previous position, and the line’s new position value.

Iocomp Components – Plot Pack Manual 271 Appendix E - Getting Started with Microsoft .NET (C#.NET/VB.NET)

Appendix E - Getting Started with Microsoft .NET (C#.NET/VB.NET)

Introduction The .NET development environment is a harmonized collection of Microsoft development environments, all supporting the CLR (Common Language Runtime) and the same IDE (Integrated Development Environment). All that generally differs between the languages is the syntax used in the language, such as C# always requiring a semi-colon at the end of each line whereas Visual Basic does not.

With respect to accessing our components from a .NET project, the procedure is always the same whether you are using the Visual Basic or C# language. For example, adding our ActiveX components to your Toolbox is exactly the same, dropping components on a form is exactly the same, and accessing methods and properties are exactly the same...

Visual Basic.NET Syntax

AxiPlotX1.get_XAxis(0).Title = "Sample Title 1"

C#.NET Syntax

AxiPlotX1.get_XAxis(0).Title = "Sample Title 1";

Adding Component To Project Each Visual Basic project needs to be configured with a set of component that will be available to it. To add our components to the list of available components in your component toolbox, right-click on the component toolbox and select “Customize Toolbox…”…

FIGURE E.1 To make an ActiveX component available for use with your application, right- click on your component toolbox and select “Customize Toolbox…”.

272 Iocomp Components – Plot Pack Manual Appendix E - Getting Started with Microsoft .NET (C#.NET/VB.NET)

The list of components presented represents the available ActiveX (COM)components on your computer system. Scroll down the list and place a check mark next to “iPlotX Control”…

FIGURE E.2 View of the available ActiveX (COM) components on your computer system. Select “iPlotX Control” to make our iPlot Component available to your application. The component will then show up in the .NET component toolbox.

Adding Component To Form To add a component to a .NET form, simply click once on the iPlotX icon (shown depressed in Figure E.3), …

FIGURE E.3 To add a component to the form, click on the component icon in the .NET component toolbox.

Iocomp Components – Plot Pack Manual 273 Appendix E - Getting Started with Microsoft .NET (C#.NET/VB.NET)

…then click and drag out the component on your form to the size you desire…

FIGURE E.4 Click and drag out the component to the desired size.

FIGURE E.5 View of an iPlotX component on a .NET form. The component is named “AxiPlotX1” as show in the .NET property editor.

274 Iocomp Components – Plot Pack Manual Appendix E - Getting Started with Microsoft .NET (C#.NET/VB.NET)

Custom Property Editor You can use the .NET-provided propery editor, shown in figure E.1 in the lower-right-hand corner, to change some properties of the component at design-time. However, we recommend that you use our own Custom Property Editor, which provides access to the component that the .NET property editor cannot provide.

To open our custom property editor, simply right-click on the component and select “Properties”. FIGURE E.6 To open the Plot Component’s Custom Propety Editor, right-click on the component and select “Properties”.

The custom property editor is organized into different tabs, representing the layout and structure of the Plot Pack components. FIGURE E.7 View of the General Component Property Editor Tab.

For example, the Channel tab allows you to add and remove channels from the component at Design-Time, something that the Visual Basic property editor cannot do.

Iocomp Components – Plot Pack Manual 275 Appendix E - Getting Started with Microsoft .NET (C#.NET/VB.NET)

FIGURE E.8 View of the Channel Property Editor Tab.

Setting Properties and Calling Methods To access any component placed on a form, you will need to know the name of the component you need to access. By default, the first iPlotX component is named “AxiPlotX1”, but you can name the component anything you wish, such as “GraphXYZ”. You will use the name of the component to access properties and methods of the component as follows…

Visual Basic.NET Syntax AxiPlotX1.Property AxiPlotX1.Method

AxiPlotX1.PrintMarginTop = 10 AxiPlotX1.AddChannel()

C#.NET Syntax AxiPlotX1.Property; AxiPlotX1.Method;

AxiPlotX1.PrintMarginTop = 10; AxiPlotX1.AddChannel();

…as well as access sub-objects of the components…

Visual Basic.NET Syntax AxiPlotX1.get_Channel(0).Color = System.Convert.ToUInt32 (System.Drawing.ColorTranslator.ToOle(System.Drawing.Color.Yellow ))

AxiPlotX1.get_XAxis(0).Min = -50 AxiPlotX1.get_YAxis(0).Span = 100

iPlotX1.get_Labels(0).Font.Name = "Arial" iPlotX1.get_Labels(0).FontColor = Convert.ToUInt32(ColorTranslator.ToOle(Color.Blue))

276 Iocomp Components – Plot Pack Manual Appendix E - Getting Started with Microsoft .NET (C#.NET/VB.NET)

C#.NET Syntax AxiPlotX1.get_Channel(0).Color = System.Convert.ToUInt32 (System.Drawing.ColorTranslator.ToOle(System.Drawing.Color.Yellow ));

AxiPlotX1.get_XAxis(0).Min = -50; AxiPlotX1.get_YAxis(0).Span = 100;

iPlotX1.get_Labels(0).Font.Name = "Arial"; iPlotX1.get_Labels(0).FontColor = Convert.ToUInt32(ColorTranslator.ToOle(Color.Blue));

Event Handlers Like all modern Windows development environments, .NET applications are “Event Driven”. This means that your program executes according to events, usually generated by user clicks of the mouse or keyboard buttons.

The Plot Pack components, as well as the .NET form that they reside on, have a list of events that are available to allow you to respond to events either generated by the user doing something with the component, or to respond to events generated by the component itself. These events include OnXAxisMinChange (this event fires when the minimum displayed value of the X-axis changes, usually due to the user scrolling the X- Axis), or OnBeforePrint (this event fires just before a chart is sent to the printer using our own built-in printing routines, usually due to the user clicking on the Print toolbar button or due to your code calling the PrintChart method), and so on.

To create an event handler for a particular event in the Plot Component, navigate to the source code window. There are two combo boxes at the top of the window. The left- hand side has a list of all components (including the form) that are on this form. Select the Iocomp Plot Pack component you are working with (by default named AxiPlotX1). Next, select an available event from the combo box on the right. The list of events will vary depending on the component.

Some events will pass you information to tell you some additional information other than just that the event was fired. For example, the OnClickDataPoint event tells you that a data point was clicked, but how do you know which data point was clicked? This event passes you an Event Object (passed with the name “e”), which contains two pieces of information: ChannelIndex and DataIndex to inform you of the channel that was clicked and the index of the data point that was clicked. Other events will have varying numbers amounts of information, if any, passed to you.

Iocomp Components – Plot Pack Manual 277 Appendix E - Getting Started with Microsoft .NET (C#.NET/VB.NET)

FIGURE E.9 View of the event object and the parameters that are available for this particular event.

This event object is used to access all information passed to from the event. To access the list of variables passed to you, simply type “e” and a “.” to bring up a list of items. FIGURE E.10 View of the .NET code window and the Plot Component’s OnClickDataPoint event.

Example OnClickDataPoint code as shown in Figure E.1 Private Sub AxiPlotX1_OnClickDataPoint(ByVal sender As Object,_ ByVal e As AxiPlotLibrary.IiPlotXEvents_OnClickDataPointEvent) _ Handles AxiPlotX1.OnClickDataPoint MsgBox("You clicked Channel#" & e.channelIndex & _ " and data point at coordinates x:" & _ AxiPlotX1.get_Channel(0).DataX(e.dataIndex) & _ ", y:" & AxiPlotX1.get_Channel(0).DataY(e.dataIndex)) End Sub

278 Iocomp Components – Plot Pack Manual Appendix F - Getting Started with Borland Delphi & Kylix (Pascal)

Appendix F - Getting Started with Borland Delphi & Kylix (Pascal)

Introduction The easiest way to get started using VCL and CLX components in a Delphi project is to simply drop-down a component and open the property editor. In this section, we will cover creating a simple project, dropping down an Iocomp VCL component, and modifying the component’s properties using the built-in property editor. We will also cover creating an event handler and writing some Delphi/Kylix Pascal code to modify the component.

A quick note about VCL and CLX components:

• VCL components are designed to work with Borland Delphi and Borland C++ Builder applications on the Windows 32-bit (Intel processor or compatible processor based) operating system.

• CLX components are designed to currently work with the Borland Delphi, Borland C++ builder applications on the Windows 32-bit operating system (Intel processor or compatible processor based) and Borland Kylix on the Linux 32-bit operating system (Intel processor or compatible processor based). The CLX version will have some features removed that are Microsoft Windows-specific such as OPC support, EMF Metafile export, etc..

Adding Component to Delphi/Kylix IDE Each Delphi/Kylix IDE needs to compile and install our components into the component pallet. This is generally done at instlallation time of our product for you automatically if you are using our Windows Product Installer. If you do not see our components listed in your component pallet, then refer to the installation notes that are installed onto your computer (generally installed into “c:\iocomp\product” for Windows or “/home/username/iocomp/product” for Linux) for detailed compilation and installation instructions.

Adding Component To Form To add a component to a Delphi/Kylix form, simply click once on the iPlot icon (shown depressed in Figure F.1)…

FIGURE F.1 Iocomp VCL and CLX components are automatically installed into the Delphi IDE for you. Refer to the installatin notes for more information about manually installing the components. All Iocomp components are found under the “Iocomp” tab, and the VCL and CLX versions will show up automatically depending on if you have created a VCL or CLX application. Kylix users will need to manually install the Iocomp CLX components.

Iocomp Components – Plot Pack Manual 279 Appendix F - Getting Started with Borland Delphi & Kylix (Pascal)

…then click and drag out the component on your form to the size you desire…

FIGURE F.2 Click and drag out the component to the desired size.

FIGURE F.3 View of an iPlot component on a Delphi TForm. The component is named “PlotX1” as show in the Delphi Object Inspector.

Custom Property Editor You can use the Delphi or Kylix-provided Object Inspector, shown in figure F.4 on the left-hand side, to change some properties of the component at design-time. However, we recommend that you use our own Custom Property Editor, which provides access to the component that the Delphi/Kylix Object Inspector cannot provide.

To open our custom property editor, simply right-click on the component and select “Edit…” or double-click on the component.

FIGURE F.4 To open the Plot Component’s Custom Propety Editor, right-click on the component and select “Edit…”.

280 Iocomp Components – Plot Pack Manual Appendix F - Getting Started with Borland Delphi & Kylix (Pascal)

The custom property editor is organized into different tabs, representing the layout and structure of the Plot Pack components.

FIGURE F.5 View of the General Component Property Editor Tab.

For example, the Channel tab allows you to add and remove channels from the component at Design-Time, something that the Delphi/Kylix Object Inspector cannot do.

FIGURE F.6 View of the Channel Property Editor Tab.

Setting Properties and Calling Methods To access any component placed on a form, you will need to know the name of the component you need to access. By default, the first iPlot component is named “iPlot1”, but you can name the component anything you wish, such as “GraphXYZ”. You will use the name of the component to access properties and methods of the component as follows…

iPlot1.Property; iPlot1.Method;

iPlot1.PrintMarginTop := 10; iPlot1.AddChannel;

…as well as access sub-objects of the components…

iPlot1.Channel[0].Color := clRed; iPlot1.XAxis[0].Min := -50; iPlot1.YAxis[0].Span := 100;

Iocomp Components – Plot Pack Manual 281 Appendix F - Getting Started with Borland Delphi & Kylix (Pascal)

Event Handlers Like all modern Windows development environments, Delphi and Kylix applications are “Event Driven”. This means that your program executes according to events, usually generated by user clicks of the mouse or keyboard buttons.

The Plot Pack components, as well as the Delphi/Kylix form that they reside on, have a list of events that are available to allow you to respond to events either generated by the user doing something with the component, or to respond to events generated by the component itself. These events include OnXAxisMinChange (this event fires when the minimum displayed value of the X-axis changes, usually due to the user scrolling the X- Axis), or OnBeforePrint (this event fires just before a chart is sent to the printer using our own built-in printing routines, usually due to the user clicking on the Print toolbar button or due to your code calling the PrintChart method), and so on.

To create an event handler for a particular event in the Plot Component, open the Object Inspector window, select the pot component from the combo box, and click on the “Events” tab. Next, find the “OnClickDataPoint” event and double-click in the blank combo box area to the right. This will instruct Delphi to automatically create an event handler for you. The list of events will vary depending on the component.

FIGURE F.7 To create an event handler, simply double-click in the blank combo-box area next to the event. Delphi and Kylix will automatically name and generate the “skeleton” code for you in the code window.

The example in figure F.8 shows the OnClickDataPoint event that was automatically created for you, named “iPlot1ClickDataPoint”. The code below was created by hand

282 Iocomp Components – Plot Pack Manual Appendix F - Getting Started with Borland Delphi & Kylix (Pascal)

and pops-up a message box showing the channel that was clicked, and the X and Y-Axis coordinates of the particular data point clicked.

FIGURE F.8 Description…

Example OnClickDataPoint code as shown in Figure F.8 Application.MessageBox(PChar(‘You clicked Channel#’ + IntToStr(ChannelIndex) + ‘ and data point at coordinates x:’ + FloatToStr(iPlot1.Channel[0].DataX[DataIndex] + ‘, y:’ + FloatToStr(iPlot1.Channel[0].DataY[DataIndex])), ‘’);

Iocomp Components – Plot Pack Manual 283 Appendix G - Getting Started with Borland C++ Builder & Kylix (C++)

Appendix G - Getting Started with Borland C++ Builder & Kylix (C++)

Introduction The easiest way to get started using VCL and CLX components in a C++ Builder project is to simply drop-down a component and open the property editor. In this section, we will cover creating a simple project, dropping down an Iocomp VCL component, and modifying the component’s properties using the built-in property editor. We will also cover creating an event handler and writing some C++ Builder/Kylix C++ source code to modify the component.

A quick note about VCL and CLX components:

• VCL components are designed to work with Borland Delphi and Borland C++ Builder applications on the Windows 32-bit (Intel processor or compatible processor based) operating system.

Adding Component to C++ Builder/Kylix IDE Each C++ Builder/Kylix IDE needs to compile and install our components into the component pallet. This is generally done at instlallation time of our product for you automatically if you are using our Windows Product Installer. If you do not see our components listed in your component pallet, then refer to the installation notes that are installed onto your computer (generally installed into “c:\iocomp\product” for Windows or “/home/username/iocomp/product” for Linux) for detailed compilation and installation instructions.

Adding Component To Form To add a component to a C++ Builder/Kylix form, simply click once on the iPlot icon (shown depressed in Figure G.1)…

FIGURE G.1 Iocomp VCL and CLX components are automatically installed into the C++ Builder IDE for you. Refer to the installatin notes for more information about manually installing the components. All Iocomp components are found under the “Iocomp” tab, and the VCL and CLX versions will show up automatically depending on if you have created a VCL or CLX application. Kylix users will need to manually install the Iocomp CLX components.

284 Iocomp Components – Plot Pack Manual Appendix G - Getting Started with Borland C++ Builder & Kylix (C++)

…then click and drag out the component on your form to the size you desire…

FIGURE G.2 Click and drag out the component to the desired size.

FIGURE G.3 View of an iPlot component on a C++ Builder TForm. The component is named “PlotX1” as show in the C++ Builder Object Inspector.

Custom Property Editor You can use the C++ Builder or Kylix-provided Object Inspector, shown in figure F.4 on the left-hand side, to change some properties of the component at design-time. However, we recommend that you use our own Custom Property Editor, which provides access to the component that the C++ Builder/Kylix Object Inspector cannot provide.

To open our custom property editor, simply right-click on the component and select “Edit…” or double-click on the component.

FIGURE G.4 To open the Plot Component’s Custom Propety Editor, right-click on the component and select “Edit…”.

Iocomp Components – Plot Pack Manual 285 Appendix G - Getting Started with Borland C++ Builder & Kylix (C++)

The custom property editor is organized into different tabs, representing the layout and structure of the Plot Pack components.

FIGURE G.5 View of the General Component Property Editor Tab.

For example, the Channel tab allows you to add and remove channels from the component at Design-Time, something that the C++ Builder/Kylix Object Inspector cannot do.

FIGURE G.6 View of the Channel Property Editor Tab.

iPlot1.Property; iPlot1.Method;

iPlot1.PrintMarginTop := 10; iPlot1.AddChannel;

…as well as access sub-objects of the components…

iPlot1->Channel[0]->Color := clRed; iPlot1->XAxis[0]->Min := -50; iPlot1->YAxis[0]->Span := 100;

286 Iocomp Components – Plot Pack Manual Appendix G - Getting Started with Borland C++ Builder & Kylix (C++)

Event Handlers Like all modern Windows development environments, C++ Builder and Kylix applications are “Event Driven”. This means that your program executes according to events, usually generated by user clicks of the mouse or keyboard buttons.

The Plot Pack components, as well as the C++ Builder/Kylix form that they reside on, have a list of events that are available to allow you to respond to events either generated by the user doing something with the component, or to respond to events generated by the component itself. These events include OnXAxisMinChange (this event fires when the minimum displayed value of the X-axis changes, usually due to the user scrolling the X- Axis), or OnBeforePrint (this event fires just before a chart is sent to the printer using our own built-in printing routines, usually due to the user clicking on the Print toolbar button or due to your code calling the PrintChart method), and so on.

To create an event handler for a particular event in the Plot Component, open the Object Inspector window, select the pot component from the combo box, and click on the “Events” tab. Next, find the “OnClickDataPoint” event and double-click in the blank combo box area to the right. This will instruct C++ Builder to automatically create an event handler for you. The list of events will vary depending on the component.

FIGURE G.7 To create an event handler, simply double-click in the blank combo-box area next to the event. C++ Builder and Kylix will automatically name and generate the “skeleton” code for you in the code window.

The example in figure F.8 shows the OnClickDataPoint event that was automatically created for you, named “iPlot1ClickDataPoint”. The code below was created by hand and pops-up a message box showing the channel that was clicked, and the X and Y-Axis coordinates of the particular data point clicked.

Iocomp Components – Plot Pack Manual 287 Appendix G - Getting Started with Borland C++ Builder & Kylix (C++)

FIGURE G.8 View of the C++ Builder code window with the OnClickDataPoint event handler.

Example OnClickDataPoint code as shown in Figure G.8 String TempString; TempString = “You clicked Channel#” + IntToStr(ChannelIndex) + “ and data point at coordinates x:” + FloatToStr(iPlot1->Channel[0]->DataX[DataIndex]) + “, y:” + FloatToStr(iPlot1->Channel[0]->DataY[DataIndex]); Application->MesageBox(TempString.c_str(), “”, MB_OK);

288 Iocomp Components – Plot Pack Manual Appendix H - ActiveX HTML Properties and Events

Appendix H - ActiveX HTML Properties and Events

HTML Page Important Notes

Boolean Values: TRUE = -1 FALSE = 0

Double Values: Double values cannot be of greater precision than 4 decimal places. This is a limitation of the streaming mechanism of Internet Explorer. This is generally a problem with Date/Time values used in the axes properties. It is recommended that you calculate and set Date/Time Min and Span values for axes (and any other property that you need greater than 4 decimal place precision) in your HTML page loading code as a work- around.

Properties Below, you will find all of the currently supported properties that can be streamed in from an HTML page into the iPlotX component. Default values are provided. If you only need the default properties, then you do not need these lines in your HTML Object tag code since the control will set these default properties all by itself. You only need to include param tags for properties that differ from the default. (Note: some HTML editors will automatically insert all of these streamed properties for you. If you don’t need the default properties, simply delete the param lines. If you used the built-in property editors in your HTML editor to set properties at design time, then leave in the param lines if you are not sure which ones to remove or leave)

Array Properties Note: “Channel0” refers to the first channel and “Channel1” refers to the second channel, and so on. All array properties (sub object properties) are coded with the number after the array name, and are zero based. Please note that only the Axes and Channels support multiple items at this time.

The following list shows the available param tags for our iPlot and iXYPlot components along with their default values…

Iocomp Components – Plot Pack Manual 289 Appendix H - ActiveX HTML Properties and Events

290 Iocomp Components – Plot Pack Manual Appendix H - ActiveX HTML Properties and Events

Iocomp Components – Plot Pack Manual 291 Appendix H - ActiveX HTML Properties and Events

292 Iocomp Components – Plot Pack Manual Appendix H - ActiveX HTML Properties and Events

Iocomp Components – Plot Pack Manual 293 Appendix H - ActiveX HTML Properties and Events

294 Iocomp Components – Plot Pack Manual Appendix H - ActiveX HTML Properties and Events

Iocomp Components – Plot Pack Manual 295 Appendix H - ActiveX HTML Properties and Events

296 Iocomp Components – Plot Pack Manual Appendix H - ActiveX HTML Properties and Events

VBScript Events Events in VBScript under Internet Explorer are identical to their counterparts in Visual Basic or VBA except that VBScript does not support variable types and some events (such as drag and focus events). Internet Explorer VBA does not support variable types. All variables are assumed to be Variants, so you will not find any “as” operators in the event declarations.

JavaScript Events If you prefer to use JavaScript in your HTML code, then you will need to first “map” the event you wish to use with the iPlotX component to a particular event handler as follows. Note that this is a hack in Internet Explorer to allow JavaScript to be used with the ActiveX component. Netscape Navigator and other browsers do not support ActiveX controls as this time.

300 Iocomp Components – Plot Pack Manual Appendix H - ActiveX HTML Properties and Events

Iocomp Components – Plot Pack Manual 301 Appendix H - ActiveX HTML Properties and Events

302 Iocomp Components – Plot Pack Manual Appendix H - ActiveX HTML Properties and Events

Events that have parameters must be enclosed within quotation marks.

Now include a separate script tag to include the event handlers, and the code you wish to run when that event is fired…

LPK File Tutorial Web Page ActiveX Licensing: What is an LPK File? An LPK file is a file that licenses our ActiveX controls when running on a Microsoft Internet Explorer Web Browser. This file must be created for all ActiveX components that require licensing, regardless of manufacturer.

Steps to create an LPK File...

FIGURE G.1 Iocomp Installer “Repair” option.

Iocomp Components – Plot Pack Manual 307 Appendix H - ActiveX HTML Properties and Events

1. Make sure you have installed our ActiveX components using our Product Installer (either from the CD-ROM or downloaded version). If you have any reason to believe that our components are missing license information on your system, simply open our installer from the Windows Add/Remove Control Panel and select the REPAIR option to fix our ActiveX licensing. FIGURE G.2 Windows Explorer view of the Microsoft “lpk_tool.exe” program

2. Obtain the Microsoft LPK File Generation Tool either from your Visual Studio Installation, from the Microsoft Internet Explorer API Pack, or from Microsoft's Download File Section of their website (Download: Microsoft LPK Tool [74.5 KB]). This program is the only program that can generate LPK files and is provided by Microsoft. FIGURE G.3 Sample selection of ActiveX licenses to add to the LPK File.

3. Open the LPK Tool and select the Iocomp Components you will be using on the web page. Also select other ActiveX controls that you will be using on the same web page that require licensing. You can only have one LPK file per web page, so you will need to select all ActiveX controls that will be used. We recommend that you create a single LPK file for all web pages on your site for simplicity. Click on the "ADD ->" button when you are done.

308 Iocomp Components – Plot Pack Manual Appendix H - ActiveX HTML Properties and Events

FIGURE G.4 Sample ActiveX licenses that have been selected to be added to the LPK File

4. Click the "Save & Exit" button to generate the LPK file. FIGURE G.5 “lpk_tool.exe” Save As dialog. You can choose any filename you wish.

5. You can name the LPK file anything you wish. We recommend that you don't include spaces or non-standard characters in the name as to avoid issues with different server operating systems (remember that our ActiveX components can be placed on any web server OS, they just have to run on a Windows Web Browser client). 6. Copy the LPK file to a location on your web server. If you are just creating a single web page, we recommend that you place the LPK file in the same folder as the web page. If you are creating multiple web pages, we recommend that you place the LPK file in a common folder off of the root of your web server, such as /download.

You can only have one LPK file per web page. Therefore, you will need to include all licenses for all ActiveX components (whether they are from Iocomp or some other Third Party ActiveX company) in the single LPK file. We recommend that you make one single LPK file for use on your website to make things easier.

Iocomp Components – Plot Pack Manual 309 Appendix H - ActiveX HTML Properties and Events

Steps to integrate the LPK File into your web page... 1. Place the following block of code, substituting the name of your LPK file, at the top the body section of your web page...

LPK File Example Page

...include all ActiveX component object tags only after this line...

2. That's it! Check out our other Internet Explorer Examples for information about integrating ActiveX components into the web page.

The LPK file must be located on the same server as where the HTML page is ! stored/generated.

The CLASSID must always be the value specified above. This is the CLASSID of the Microsoft License Manager component, which provides licensing services to ActiveX components that require licensing. This CLASSID is the same for all versions of ! Microsoft Internet Explorer You can only have one LPK file entry per web page!

310 Iocomp Components – Plot Pack Manual Appendix I -- What is DateTime Format?

Appendix I -- What is DateTime Format?

Date/Time format is commonly used in Microsoft products such as Microsoft Excel and is based on a floating-point value to represent a date or time value...

Date/Time Calculations 1 day = 1 1 hour = 1/24 1 minute = 1/(24*60) 1 second = 1/(24*60*60) 1 millisecond = 1/(24*60*60*1000) Table I.1

Visual Basic: the following formula should be used when using Visual Basic: (1/(24#*60#*60#)). The # symbols force Visual Basic to treat the numbers as floating point values, otherwise you will generate a compiler error since VB is trying to use Integer math. You may find it helpful to setup a constant in your ! program for this calculation to represent one second... Const OneSecond As Double=1/(24# * 60# * 60#)

Visual Layout Manager: if you use the built-in property editor, notice the button next to values which can accept date-time values. If you click on the button, you will be able to access a calculator that will do the above calculations for you when entering values.

C++ Compiler: the following formula should be used when using C++ Compilers such as Visual C++ or Borland C++ Builder and others: (1.0/(24.0*60.0*60.0)). Specifying the numerical values as floating point numbers forces the C++ compiler ! to use floating-point math, and not integer math, which would result in incorrect results.

To specify a particular date such as March 12, 2000, you need to specify a decimal value that represents how much time has elapsed since December 30, 1899 at 12:00am...

December 30, 1899 12:00am = 0 January 1, 1900 = 1 March 12, 2000 = 36597 December 31, 9999 = 2958525 March 12, 2000 12:00pm = 36597.5 March 12, 2000 6:00pm = 36597.75

By default, the axes span in our charting components is set to a value of 10. If you enable the date/time format…

iComponent.Xaxis(0).LabelsFormatStyle = iptfDateTime iComponent.Yaxis(0).LabelsFormatStyle = iptfDateTime

Iocomp Components – Plot Pack Manual 311 Appendix I -- What is DateTime Format?

...in a particular axis, then the axis scale would correspond to a range of 10 days. If you are plotting data to the chart component with such a large scale, it would appear that the chart was not working as it would take 10 days to plot from one side of the axis to the other!

For Example:

Let's say you want to specify an X-Axis scale between 0-10 seconds. You would use the formula (1/(24*60*60)) *10 to obtain the time/date value for ten seconds. You would set the X-Axis min value to 0 and the X-Axis max value to the calculated formula value.

Don’t forget to set the AxisLabelFormatStyle and DateTimeFormat string properties for DateTime mode.

iComponent.Xaxis(0).LabelsFormatStyle = iptfDateTime iComponent.Xaxis(0).DateTimeFormat = "nn:ss:zzz"

DateTime Format String Here are some sample DateTimeFormat strings that can be used to format your date and time values in the axis. You can make other combinations for this string if you need. Refer to the table on the next page for custom formats.

Format String Example d mmm hh:nn:ss am/pm 1 May 12:01:32am d mmm hh:nn:ss 1 May 22:01:32 m/d hh:nn:ss am/pm 2/28 12:01:32am m/d hh:nn:ss 2/28 22:01:32 d mmm hh:nn am/pm 1 May 12:01 am d mmm hh:nn 1 May 22:01 hh:nn:ss.zzzz 22:01:32.254 Table H.2

Month (M) The letter "M" must be uppercase to distinguish months from minutes.

Format String Displays the month as M A number without a leading 0 (zero) for single-digit months. For example, July is "7". MM A number with a leading 0 (zero) for single-digit months. For example, July is "07". MMM A three-letter abbreviation. For example, July is "Jul". MMMM The full name of the month. Table H.3

312 Iocomp Components – Plot Pack Manual Appendix I -- What is DateTime Format?

Day (d) Displays the day of the month or the day of the week. The letter "d" can be either uppercase or lowercase.

Format String Displays the day of the month or week as d A number without a leading 0 (zero) for single-digit days. For example, the sixth day of the month is displayed as "6". dd A number with a leading 0 (zero) for single-digit days. For example, the sixth day of the month is displayed as "06". ddd A three-letter abbreviation. For example, Tuesday is displayed as "Tue". dddd The full name of the day of the week. Table H.4

Year (y) Displays the year as two or four digits. The letter "y" can be either uppercase or lowercase.

Format String Displays the year as yy Two digits with a leading 0 (zero) for years 01 through 09. For example, 1995 is displayed as "95", and 2006 is displayed as "06". yyyy Four digits. Table H.5

Special These are special characters used in the format string that are supported by the labels.

Format String Displays the year as zzz Milliseconds Table H.6

Iocomp Components – Plot Pack Manual 313 Appendix J -- Frequently Asked Questions

Appendix J -- Frequently Asked Questions

Below, you will find some frequently asked questions and specific, real-world situations that our customers have been asking about in our Plot Components…

Q: How do I determine the data point indexes of the channel’s data points currently viewable in the chart? A: Use the DrawStartIndex and DrawStopIndex properties of the channel object to obtain the first and last data point indexes of the viewable data points in that channel. For example…

FirstDataPointIndex = iPlot1.Channel(0).DrawStartIndex LastDataPointIndex = iPlot1.Channel(0).DrawStopIndex

FirstDataPointXValue = iPlot1.Channel(0).DataX(FirstDataPointIndex) FirstDataPointYValue = iPlot1.Channel(0).DataY(FirstDataPointIndex)

LastDataPointXValue = iPlot1.Channel(0).DataX(LastDataPointIndex) LastDataPointYValue = iPlot1.Channel(0).DataY(LastDataPointIndex)

Q: How do I determine the pixel coordinate position of something within the Data View? A: Utilize the PositionToPixels functions of the X-Axis and Y-Axis. The PositionToPixels function of the X-Axis will convert X coordinates on the X-Axis to pixel positions on the overall component (the 0,0 origin is in the upper-left-hand corner of the component) The PositionToPixels function of the Y- Axis will convert Y coordinates on the Y-Axis to pixel positions on the overall component.

For example, to get the pixel coordinate center of a text annotation…

XPixelCoordinate = iPlot1.XAxis(0).PositionToPixels(iPlot1.Annotation(0).X) YPixelCoordinate = iPlot1.YAxis(0).PositionToPixels(iPlot1.Annotation(0).Y)

There are also other conversion functions to convert between pixels coordinates to position and “percent of data view” measurements to positions on the axes: PixelsToPosition, PercentToPosition, and PositionToPercent.

Q: How do I get X-Axis Date-Time labels to word wrap? A: Simply insert a carriage return character where you want the wrap to occur. For example…

iPlot1.Xaxis(0).DateTimeFormatString = “mmm/dd/yyyy” + chr(13) + “hh:nn:ss”

Q: I print my chart, but I don’t want a black background! A: What looks good on the screen doesn’t always look good on the printed page. What you need to do is utilize the OnBeforePrint and OnAfterPrint events which allows you to intercept the chart before it gets printed, change the colors to be “printer-friendly”, and then switch them back after the print has been sent to the printer.

Q: I have a chart I want to print, but only the black portions of the chart print, not the colored portions! A: This is due to how the printer driver convert and handle color to grayscale prints. You will need to either upgrade your printer driver or figure out what settings in the driver will automatically convert color to grayscale. Unfortunately, all printer drivers are customized by the printer manufacturer or

314 Iocomp Components – Plot Pack Manual Appendix J -- Frequently Asked Questions

Microsoft, and each driver has it’s own feature set. You will need to experiment with different settings or consult the printer manufacturer.

The good news is that most new printer models and their drivers handle color conversion beautifully. The bad news is that some older printers and their drivers do not handle color conversion at all or not very well.

If all else fails, you will need to utilize the OnBeforePrint and OnAfterPrint events to change the chart colors to black and white colors before printing.

Q: I tried to set the ZOrder of the Plot Objects (Y-Axes, X-Axes, Legend, DataView, Toolbar, etc), but they don’t go where I want them to go. What could be wrong? A: Be sure to disable the Layout Manager before making your manual ZOrder changes to the plot objects, and then re-enable the Layout Manager when done. This is done automatically for you if you are using the Visual Layout Manager in the Design-Time or Run-Time property editor.

For example, if you are manually doing this using code…

iPlot1.DisableLayoutManager

iPlot.YAxis(0).ZOrder = 0 iPlot.YAxis(1).ZOrder = 0 iPlot.DataViewZVert = 1 iPlot.Legend(0).ZOrder = 2

iPlot1.EnableLayoutManager

Q: I have rotated Annotation Text or Y-Axis labels that won’t display. What is going on? A: Rotated text requires that the font used to draw the text be a True-Type font. If we try and rotate a non-True-Type font, the Windows and QT API will display no text at all. Be sure that you are using True-Type fonts in all Font Name properties of the Plot Pack.

Q: I want the X-Axis labels to show the number of days since the plot was started, not a specific calendar date. How do I do this? A: The DateTimeFormatString property of the X-Axis can be configured to incude the “Julian” (sometimes referred to as a Gregorian Date) or number of days in a year. For example, to show the number of days since you started adding data as well as the hours, minutes, and seconds, format the DateTimeFormat string as…

iPlot.XAxis(0).DateTimeFormatString = “J hh:nn:ss”

If you start adding data at a value of 0, then values of 5.5 will be displayed on the axis as “5 12:00:00”. A value of 30.75 will be “30 18:00:00”, a value of 360.55243 will be “360 13:15:30, and so on.

Iocomp Components – Plot Pack Manual 315 Appendix J -- Frequently Asked Questions

Q: How do I dynamically create a Plot Component at Runtime in Visual C++? A: This is a complex question which has several solutions depending on your type of project (MFC applcation versus ATL component, etc.). For a straight MFC application, you would do the following…

//Add to the top of your form #include "iplotx.h" int IDiPlotX1 = 100; //make sure this is a unique value in your application

//Add somewhere in your initialization code //usually in your OnInitDialog Event Handler //You will need to obtain the actual license string from the Windows //Registry using Regedit.exe. The key is located in //HKEY_LOCAL_MACHINE\SOFTWARE\Iocomp\Keys //under the name TiPlot or TiXYPlot, depending on which Plot Component //you are creating. CRect ComponentRect; CString LicenseString = "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}";

BSTR LicenseKey = LicenseString.AllocSysString(); ComponentRect.SetRect(10,10, 640, 380);

m_iPlotX1.Create("Plot", WS_VISIBLE, ComponentRect, this, IDiPlotX1, NULL, FALSE, LicenseKey);

For more information, examples, and FAQs, check out our examples and FAQ sections of our support website…

Support: http://www.iocomp.com/support FAQ: http://www.iocomp.com/faq Examples: http://www.iocomp.com/examples

316 Iocomp Components – Plot Pack Manual Index

Index

Iocomp Components – Plot Pack Manual 317