Objective Grid User’s Guide Stingray® Studio Version 13.0.1 OBJECTIVE GRID USER’S GUIDE PRODUCT TEAM Development: Terry Crook, Clayton Dean, Boris Meltreger, David Noi Documentation: Marc Betz, Shelley Hoose Development Manager: Clayton Dean Product Manager: Ben Gomez Support: Terry Crook, Boris Meltreger THIS MANUAL © Copyright 1997-2012 Rogue Wave Software, Inc. All Rights Reserved. Rogue Wave and Stingray are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners. ACKNOWLEDGMENTS This documentation, and the information contained herein (the "Documentation"), contains proprietary information of Rogue Wave Software, Inc. Any reproduction, disclosure, modification, creation of derivative works from, license, sale, or other transfer of the Documentation without the express written consent of Rogue Wave Software, Inc., is strictly prohibited. The Documentation may contain technical inaccuracies or typo- graphical errors. Use of the Documentation and implementation of any of its processes or techniques are the sole responsibility of the client, and Rogue Wave Software, Inc., assumes no responsibility and will not be liable for any errors, omissions, damage, or loss that might result from any use or misuse of the Documentation ROGUE WAVE SOFTWARE, INC., MAKES NO REPRESENTATION ABOUT THE SUITABILITY OF THE DOCUMENTATION. THE DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ROGUE WAVE SOFTWARE, INC., HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS WITH REGARD TO THE DOCUMENTATION, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHER- WISE, INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT SHALL ROGUE WAVE SOFTWARE, INC., BE LIABLE, WHETHER IN CONTRACT, TORT, OR OTHERWISE, FOR ANY SPE- CIAL, CONSEQUENTIAL, INDIRECT, PUNITIVE, OR EXEMPLARY DAMAGES IN CONNECTION WITH THE USE OF THE DOCUMENTATION. The Documentation is subject to change at any time without notice. ROGUE WAVE SOFTWARE, INC. Address: 5500 Flatiron Parkway, Boulder, CO 80301 USA Product Information: (303) 473-9118 (800) 487-3217 Fax: (303) 473-9137 Web: http://www.roguewave.com CONTENTS 1Chapter 1 Introduction to Objective Grid 1.1 Welcome to Objective Grid 1 1.2 Product Features 1 1.3 Supported Platforms 3 1.4 Location of Samples 4 1.5 Licensing Restrictions 4 1.5.1 Stingray Naming Conventions 4 1.5.2 File Redistribution 5 1.6 Getting Help 5 1.6.1 Documentation 5 1.6.1.1 Available Formats 6 1.6.1.2 Common Terms 6 PART I User’s Guide 2Chapter 2 Design Overview 2.1 Design Introduction 11 2.1.1 The Style Object 11 2.1.2 The Range Object 13 2.1.3 The Parameter Object 14 2.1.4 Conclusion 14 2.2 Styles Architecture 15 2.2.1 Style Implementation 15 2.2.2 CGXGridCore - Styles Interface 17 2.2.3 CGXStyle - Class Interface 18 Contents iii 2.3 Drawing and Updating 20 2.3.1 CGXGridCore - Commands Interface 22 2.3.2 Accessor Methods 23 2.3.3 CGXGridCore - Drawing Overridables 25 2.4 Control Architecture 26 2.4.1 Current Cell Interface 26 2.4.2 Current Cell Notifications 26 2.4.3 Predefined Controls 29 2.5 Browser Architecture 31 2.5.1 CGXBrowserGrid - Interface 31 2.5.1.1 Current Record 32 2.5.1.2 Data Source Binding 32 2.5.2 ODBC Browser 33 2.5.3 ADO Browser 34 2.6 Formula Engine 35 2.6.1 Adding Formula Support to Your Application 35 2.6.2 Initializing the Grid With Data and Formulas 36 2.6.3 Changing Cell Data and Formulas at Run Time 36 2.7 Run-Time Initialization 39 2.8 Choosing Between Grid Types 42 3Chapter 3 Technical Overview 3.1 Introduction 45 3.2 Class Summary 46 3.3 Drawing Classes 47 3.3.1 CGXGridCore 47 3.3.2 CGXView 48 3.3.3 CGXGridView 48 3.3.4 CGXGridWnd 48 3.3.5 CGXGridHandleView 48 3.3.6 CGXGridHandleWnd 48 3.3.7 CGXGridHint 48 3.4 Control Classes 49 3.4.1 CGXControl 51 3.4.2 CGXBitmapButton 51 3.4.3 CGXCheckBox 51 3.4.4 CGXCheckBoxEx 51 3.4.5 CGXCheckListComboBox 52 3.4.6 CGXComboBox 52 iv Contents 3.4.7 CGXComboBoxWnd 52 3.4.8 CGXCurrencyEdit 53 3.4.9 CGXDateTimeCtrl 53 3.4.10 CGXEditControl 54 3.4.11 CGXHeader 54 3.4.12 CGXHotSpotEdit 54 3.4.13 CGXListBox 55 3.4.14 CGXMaskControl 55 3.4.15 CGXPasswordControl 55 3.4.16 CGXProgressCtrl 55 3.4.17 CGXPushbutton 55 3.4.18 CGXRadioButton 56 3.4.19 CGXRadioButtonEx 56 3.4.20 CGXRichEditCtrl 57 3.4.21 CGXSpinEdit 57 3.4.22 CGXStatic 57 3.4.23 CGXTabbedComboBox 57 3.4.24 CGXTabbedComboBoxWnd 58 3.4.25 CGXVScrollEdit 58 3.4.26 CGXWndWrapper 58 3.4.27 CGXChild 59 3.4.28 CGXButton 59 3.4.29 CGXBitmapButtonChild 59 3.5 Style Classes 60 3.5.1 CGXStyle 60 3.5.2 CGXStylesMap 61 3.5.3 CGXStylesDialog 61 3.5.4 CGXStyleSheet 61 3.5.5 CGXFont, CGXBrush, CGXPen 61 3.5.6 CGXAbstractUserAttribute 61 3.5.7 CGXUserAttribute 61 3.6 Data Structures 62 3.6.1 CGXGridParam 63 3.6.2 CGXData 63 3.6.3 CGXProperties 63 3.6.4 CGXCommand 63 3.6.5 CGXAbstractControlFactory 63 3.6.6 CGXControlFactory 63 3.6.7 CGXGridDropTarget 64 3.6.8 CGXNoOleDataObjectProxy 64 3.6.9 CGXNoOleDataSourceProxy 64 3.6.10 CGXDisplayPropertiesDialog, CGXHeaderFooterDialog, CGXPrintPropertiesDialog 64 3.6.11 CGXRange 64 3.6.12 CGXRangeList 64 3.6.13 CGXPrintDevice 64 Contents v 3.7 Browser Classes 65 3.7.1 CGXBrowserGrid 66 3.7.2 CGXBrowserView 66 3.7.3 CGXBrowserWnd 66 3.7.4 CGXBrowseParam 66 3.7.5 CGXDbParam 66 3.7.6 CGXDynamicRecordset 66 3.7.7 CGXODBCGrid 66 3.7.8 CGXRecordInfoBeam 67 3.7.9 CGXRecordInfoWnd 67 3.7.10 CGXRecordInfoSplitterWnd 67 3.7.11 CGXRecordView 67 3.7.12 CGXRecordWnd 67 3.7.13 CGXRecSetInfo 67 3.7.14 CGXAdoGrid 67 3.7.15 CGXAdoParam 68 3.7.16 CGXAdoRecordView 68 3.7.17 CGXAdoRecordWnd 68 3.8 Utility Classes 69 3.8.1 CGXDrawingAndFormatting 69 3.8.2 CGXLongOperation 69 3.8.3 CGXScrollTip 70 3.8.4 CGXSplitterWnd 70 3.8.5 CGXTabBeam 70 3.8.6 CGXTabInfo 70 3.8.7 CGXTabWnd 70 3.9 Formula Engine Classes 71 3.9.1 CGXFormulaSheet 71 3.9.2 CGXWorksheetFunctions 71 3.9.3 CGXDefaultWorksheetFunctions 71 3.9.4 CGXFormula 72 3.10 Plug-in Component Classes 73 3.10.1 CGXPluginComponent 73 3.10.2 CGXMouseWheelPlugin 73 3.10.3 CGXIntelliMousePlugin 73 3.10.4 CGXGridMouseWheelPlugin 74 3.10.5 CGXGridIntelliMousePlugin 74 3.10.6 CGXScrollTipPlugin 74 3.10.7 CGXCellTipPlugin 74 4Chapter 4 Getting Started 4.1 Creating a Starter Application 75 4.1.1 Using the Objective Grid Static Libraries 75 4.1.2 Using the Objective Grid Extension DLLs 76 vi Contents 4.1.3 Converting an Application to Use the Objective Grid Extension DLL 76 4.2 Using Objective Grid in a Dialog Box 77 4.2.1 Objective Grid vs. ActiveX Controls 77 4.2.2 Using Objective Grid in a Dialog Template 77 4.2.3 Troubleshooting 79 4.3 Miscellaneous Tips 80 4.3.1 Using Pre-Built Libraries 80 4.3.2 Checklist for Build Configurations 80 4.3.2.1 Miscellaneous Configurations 81 4.3.3 Objective Grid and VC++ 81 4.3.3.1 Building and Using VC++ Libraries 81 4.3.3.2 Make Files and Building Directly with nmake 82 4.3.3.3 Known Issues in VC++ Unicode Libraries 82 4.3.3.4 Objective Grid AppWizard 82 4.3.3.5 Objective Grid Designer Utility 82 4.3.3.6 Setting Paths in Visual Studio 82 4.3.4 Objective Grid and Windows Look and Feel 83 4.3.4.1 Vista Look and Feel 83 4.3.4.2 XP Look and Feel 83 4.4 Using Objective Grid in a WinForm 84 4.4.1 Direct Use of Objective Grid in a WinForm 84 4.4.2 Use of Objective Grid in a .NET Control 85 5Chapter 5 Using Objective Grid 5.1 Cell Value 89 5.1.1 Filling the Grid with Values 89 5.1.2 Getting Values from the Grid 90 5.1.3 Clearing Cell Values 91 5.2 Cell Attributes 92 5.2.1 Reusing Style Objects 92 5.2.2 Disabled and Read-Only Cells 92 5.2.2.1 What Are Disabled Cells? 93 5.2.2.2 What Are Read-Only Cells? 93 5.2.3 Covered Cells 94 5.2.4 Floating Cells 94 5.2.4.1 What Are Floating Cells? 94 5.2.5 Merged Cells 95 5.2.5.1 What Are Merged Cells? 96 5.2.6 Registration and Usage of Base Styles 97 5.2.7 Registration and Usage of User Attributes 99 5.2.7.1 Creating Custom Attributes 100 5.3 Controls 102 5.3.1 Registration and Usage of Controls 102 Contents vii 5.4 Columns and Rows 103 5.4.1 Column and Row Count 103 5.4.2 Column and Row Sizing 104 5.4.2.1 Using Code to Size 104 5.4.2.2 End User Resizing 104 5.4.3 Hidden Columns and Rows 105 5.4.3.1 Using Code to Hide 105 5.4.3.2 End User Hiding and Unhiding 105 5.4.4 Frozen Columns and Rows 106 5.5 Cell and Window Coordinates 108 5.5.1 Cell Coordinates 108 5.5.2 Window Coordinates 109 5.5.2.1 Device Context 109 5.5.2.2 Row Heights and Column Widths 109 5.5.2.3 Converting Between Cell and Window Coordinates 110 5.5.3 Hit-Testing 111 5.6 Grid Lines 112 5.6.1 Grid Line Drawing 112 5.7 Events 113 5.7.1 Keyboard Events 113 5.7.2 Keyboard Shortcuts 114 5.8 Deriving a Grid 115 5.9 Virtual Grids 116 5.9.1 Supplying Data 116 5.9.2 Storing Data 118 5.10 Formula Support 119 5.11 Undo and Redo 119 5.11.1 CGXGridCore - Undo/Redo interface 119 5.11.2 Transaction-Like Blocks of Commands 120 5.11.3 Long Operations 120 5.12 Sorting 123 5.12.1 Basic Sorting 123 5.12.2 Natural Sorting 123 5.12.3 Sorting Example 124 5.13 Pre-Built Dialogs for Accessing Objective Grid Objects 124 5.13.1 Display Settings Dialog 124 5.13.2 Header / Footer Dialog 127 5.13.3 Page Setup Dialog 129 5.14 Number Formatting 131 viii Contents 5.14.1 Value Types 131 5.14.2 Formatting Number Values for Static Cells 131 5.14.3 Recognizing Locale Settings in Static Formatting 134 5.15 Miscellaneous 136 5.15.1 Using CGXDrawingAndFormatting 136 5.15.2 IntelliMouse Support 137 5.15.3 Rotated Text in Cells 138 5.15.4 Character Sets 138 5.15.5 Direct Copying and Moving of Cells 139 5.15.6 AutoScrolling